blockworx/tools/

overlay.rs

//! The selection overlay (spec §3), 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 spec is built around (§1, §3): controls scoped to what the user has
//! already selected.
//!
//! One list feeds three surfaces — the row, the overflow menu it spills into
//! (§3.5), and the right-click menu that duplicates it (§3.6) — because a
//! second list is a second answer to "what applies here", and invariants 3
//! and 6 are both statements that there is only one. [`Bar`] is where the one
//! list is cut, and the cut keeps the registry's order, so what overflowed
//! cannot move what stayed.
//!
//! §3.2's 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 _;
use crate::{
    canvas::Camera,
    edit::{lower::accent_from_role, naming::InterfaceLock},
    export::ExportScope,
    shape::{ShapeId, ShapeRef},
    shell::{SafeArea, glass},
    theme::{Role, Theme, accent_role},
    tools::{
        chrome::Panel,
        commands::{Command, CommandId, CommandSet, Placement},
        tool::{Action, RoleTarget},
    },
    widget::drawing::Drawing,
};
use blockworx_doc::{
    id::PinId,
    values::{PinDir, Role as AccentRole},
};

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

/// 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: AccentRole| accent_from_role(role);
    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)).egui()
}

/// 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 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 (§3.5). 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 air between the selection's bounding box and the bar (§3.3).
const CLEAR: f32 = 14.0;

/// 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;

/// What a selection with no commands says, rather than raising no bar at all.
///
/// §3.2 wrote this for the multi-selection whose members share nothing; item
/// 25 generalised it. A selection that silently draws no bar is
/// indistinguishable from a selection whose bar is broken — which is exactly
/// the misread the area bug produced — so the empty case says so out loud
/// whether one thing is selected or several.
fn nothing_to_say(count: usize) -> &'static str {
    if count > 1 {
        "No actions shared by this selection"
    } else {
        "No actions for this selection"
    }
}

/// 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;

/// The selection the overlay is drawn for: where it sits on screen, and how
/// many things it holds (§3.2's count).
#[derive(Clone, Copy)]
pub struct Selection {
    pub screen: egui::Rect,
    pub count: usize,
}

/// Everything one frame of the overlay resolves against.
pub struct Overlay<'a, 'b> {
    pub commands: &'a mut CommandSet,
    pub data: &'a Drawing<'b>,
    pub theme: &'a Theme,
    pub open_picker: Option<OpenPicker>,
    pub selection: Option<Selection>,
    /// The room the floating chrome left, which the bar clamps into (§3.3).
    pub safe: SafeArea,
    /// Whether the camera is being worked; the bar stands down while it is
    /// and re-places on release (§3.4).
    pub camera: Camera,
    pub right_click: RightClick,
}

/// Where a bar of `size` goes for a selection at `sel` (§3.3): centred above
/// it with [`CLEAR`] air between, flipped below when above would land under
/// the top chrome, and slid sideways into the room the chrome left.
///
/// The clamp is horizontal only, and that is what makes invariant 5 hold
/// rather than a check after the fact: both candidates are wholly clear of the
/// selection in *y*, and nothing downstream touches *y*.
///
/// A selection *larger than the room around it* has no band outside itself, so
/// the bar takes the one just inside its own leading edge instead of standing
/// down. That is the fix for the user's *"The selection overlay for Areas is
/// missing"*: an area is the one selection routinely taller than the canvas
/// it is drawn on, so it was the one selection for which both bands fell
/// outside the region and the bar hid itself. Controls the user cannot reach
/// are worse than a bar over the middle of a rectangle whose interior is not
/// hit-testable anyway.
///
/// `None` only when there is no region at all to put it in.
fn place(sel: egui::Rect, size: egui::Vec2, safe: &SafeArea) -> Option<egui::Rect> {
    let region = safe.region();
    let band =
        |top: f32| egui::Rect::from_min_size(egui::pos2(sel.center().x - size.x / 2.0, top), size);
    let fits = |bar: &egui::Rect| bar.top() >= region.top() && bar.bottom() <= region.bottom();
    let outside = [band(sel.top() - CLEAR - size.y), band(sel.bottom() + CLEAR)]
        .into_iter()
        .find(fits);
    let inside = || {
        let bar = band(sel.top().max(region.top()) + CLEAR);
        fits(&bar).then_some(bar)
    };
    outside.or_else(inside).map(|bar| safe.clamp(bar))
}

/// What the bar shows for one selection: the one list, cut where §3.5 asks.
///
/// Generic over what is being cut so the ids a test compares and the commands
/// a frame draws cannot be divided differently.
enum Bar<T> {
    /// The row, what the ellipsis holds behind it, and — for the right-click
    /// menu, which carries all of them (§3.6) — the one list in the order the
    /// registry offered it, which the partition above does not preserve.
    Row {
        inline: Vec<T>,
        overflow: Vec<T>,
        all: Vec<T>,
    },
    /// A multi-selection whose members share no command (§3.2). Saying so is
    /// the point: an empty bar reads as a bug.
    NothingShared,
    /// One thing selected with nothing to do to it. It says so, rather than
    /// drawing nothing: a selection that raises no bar reads as a bug, and
    /// item 25 was exactly that misread going the other way.
    Nothing,
}

impl<T: Copy> Bar<T> {
    /// Cut the one list in two by what each command *is*, keeping the
    /// registry's order inside each half (R35).
    fn of(commands: Vec<T>, count: usize, placement: impl Fn(T) -> Placement) -> Self {
        if commands.is_empty() {
            return if count > 1 {
                Bar::NothingShared
            } else {
                Bar::Nothing
            };
        }
        let (inline, overflow) = commands
            .iter()
            .partition(|cmd| placement(**cmd) == Placement::Inline);
        Bar::Row {
            inline,
            overflow,
            all: commands,
        }
    }

    /// Everything the bar offers, row then overflow, in the registry's order —
    /// which is exactly what the right-click menu carries (§3.6, invariant 3).
    fn all(&self) -> impl Iterator<Item = &T> {
        match self {
            Bar::Row { all, .. } => all.as_slice(),
            Bar::NothingShared | Bar::Nothing => &[],
        }
        .iter()
    }
}

/// 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<Action>, 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 §3.3 found it a spot.
    At(egui::Pos2),
    /// Measured, and there is nowhere lawful: both of §3.3's 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 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 (spec §1, §3), drawn beside it
/// as a floating bar: §3.3's placement, §3.4's stand-down while the camera
/// moves, §3.5's overflow, §3.2's count, and §3.6's 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<Action>, Option<egui::Pos2>) {
    let Overlay {
        commands,
        data,
        theme,
        open_picker,
        selection,
        safe,
        camera,
        right_click,
    } = overlay;
    let ctx = ui.ctx().clone();
    let ctx = &ctx;
    let Some(selection) = selection.filter(|sel| safe.viewport().intersects(sel.screen)) else {
        return dismissed(ctx);
    };
    // §3.4: 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.placement);

    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 place(selection.screen, size, &safe) {
            Some(bar) => Placed::At(bar.min),
            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();
            (
                selection.screen.center(),
                Panel::SelectionButtons
                    .ui_builder()
                    .sizing_pass()
                    .invisible(),
            )
        }
    };
    let sizing = builder.sizing_pass;
    let controls = Controls {
        data,
        theme,
        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 = ?selection.screen,
        "overlay frame"
    );
    ctx.data_mut(|d| {
        d.insert_temp(
            size_key,
            Measured {
                controls: drawn,
                count,
                rect,
            },
        );
    });
    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: §3.2's count, the row, and §3.5's 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);
        }
        let Bar::Row {
            inline, overflow, ..
        } = bar
        else {
            ui.label(egui::RichText::new(nothing_to_say(count)).small().weak());
            return;
        };
        for cmd in inline {
            if let Some(id) = draw_command(ui, cmd, Shown::InTheBar, controls) {
                clicked = Some(id);
            }
        }
        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
}

/// §3.6: 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 (invariant 3) 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().next()) {
        (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.
fn overlay_controls(commands: &CommandSet) -> impl Iterator<Item = &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: the tool cluster's arming, the
        // action 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(),
    }
}

/// 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: the document
/// the accent swatch reads its colour out of, the theme that resolves it, and
/// which picker is currently up.
#[derive(Clone, Copy)]
struct Controls<'a, 'b> {
    data: &'a Drawing<'b>,
    theme: &'a Theme,
    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 (R19), 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 {
        data,
        theme,
        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);
                    egui::Popup::menu(&button).show(|ui| {
                        picked = export_format_menu(ui, ExportScope::Selection);
                    });
                }
                Shown::InAMenu => {
                    ui.menu_button(cmd.label, |ui| {
                        picked = export_format_menu(ui, ExportScope::Selection);
                    });
                }
            }
            picked.map(CommandId::ExportSelection)
        }
        CommandId::Accent => {
            let Action::OpenRolePicker { target } = &cmd.action else {
                return None;
            };
            let opened = glass::Opened::from(open_picker == Some(OpenPicker::Role));
            let response = match shown {
                Shown::InTheBar => {
                    accent_swatch(ui, accent_swatch_color(data, *target, theme), 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(pins_of(&cmd.action).and_then(|pins| shared_dir(data, pins)));
            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),
                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),
                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, reversing the half of item 26 that made the trigger's glyph
/// follow the pins: *"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
/// (invariant 8). 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}")
}

/// The pins an I/O command stands over.
fn pins_of(action: &Action) -> Option<&[PinId]> {
    match action {
        Action::OpenPinTypePicker { pins } => Some(pins),
        _ => None,
    }
}

/// The one direction every pin in `pins` is facing, or `None` where they
/// disagree or the selection has gone.
fn shared_dir(data: &Drawing<'_>, pins: &[PinId]) -> Option<PinDir> {
    let mut dirs = pins
        .iter()
        .map(|&pin| data.pin_on_shape(pin).map(|(_, pin)| pin.dir));
    let first = dirs.next()??;
    dirs.all(|dir| dir == Some(first)).then_some(first)
}

/// 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 (invariant 11).
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::canvas::convert::IntoGeom as _;

    use blockworx_store::doc::Writability;

    use crate::{
        shell::insets::Edge,
        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}";

    // ---- §3.3 placement ------------------------------------------------

    #[test]
    fn places_the_bar_above_the_selection_with_the_specs_air() {
        let sel = Rect::from_min_size(pos2(400.0, 400.0), vec2(100.0, 100.0));
        let safe = SafeArea::over(viewport());
        assert!(
            safe.region().contains_rect(sel),
            "precondition: the selection is inside the room the chrome left",
        );
        let bar = place(sel, SIZE, &safe).expect("a mid-canvas selection has room above it");
        assert_eq!(
            bar.bottom(),
            sel.top() - CLEAR,
            "the air is not §3.3's 14px"
        );
        assert_eq!(
            bar.center().x,
            sel.center().x,
            "the bar is not centred on it"
        );
        assert_eq!(bar.size(), SIZE, "placing resized the bar");
    }

    #[test]
    fn flips_below_when_above_would_land_under_the_top_chrome() {
        let mut safe = SafeArea::over(viewport());
        safe.covered_by(
            Edge::Top,
            Rect::from_min_size(pos2(16.0, 16.0), vec2(300.0, 52.0)),
        );
        let sel = Rect::from_min_size(pos2(400.0, 100.0), vec2(100.0, 100.0));
        assert!(
            sel.top() - CLEAR - SIZE.y < safe.region().top(),
            "precondition: above is under the chrome",
        );
        let bar = place(sel, SIZE, &safe).expect("there is room below it");
        assert_eq!(bar.top(), sel.bottom() + CLEAR, "it did not flip below");
    }

    #[test]
    fn clamps_sideways_into_the_room_the_chrome_left() {
        let mut safe = SafeArea::over(viewport());
        safe.covered_by(
            Edge::Right,
            Rect::from_min_size(pos2(700.0, 16.0), vec2(284.0, 700.0)),
        );
        let sel = Rect::from_min_size(pos2(640.0, 400.0), vec2(40.0, 40.0));
        let region = safe.region();
        assert!(
            sel.center().x + SIZE.x / 2.0 > region.right(),
            "precondition: centred, the bar would run under the navigator",
        );
        let bar = place(sel, SIZE, &safe).expect("a clamped bar still has a place");
        assert!(
            region.contains_rect(bar),
            "the bar landed at {bar:?}, outside {region:?}",
        );
        assert_eq!(bar.size(), SIZE, "clamping resized the bar");
    }

    /// Invariant 5, over a spread of selections: wherever the bar lands, it is
    /// never on top of the thing it describes. This holds because the clamp is
    /// horizontal and both candidate bands are wholly clear in *y* — so a
    /// clamp that ever moved *y* would fail here.
    #[test]
    fn the_bar_never_covers_what_is_selected() {
        let mut safe = SafeArea::over(viewport());
        safe.covered_by(
            Edge::Top,
            Rect::from_min_size(pos2(16.0, 16.0), vec2(300.0, 52.0)),
        );
        safe.covered_by(
            Edge::Left,
            Rect::from_min_size(pos2(16.0, 300.0), vec2(64.0, 200.0)),
        );
        let mut placed = 0;
        for x in [-60.0, 0.0, 120.0, 500.0, 900.0, 980.0] {
            for y in [-60.0, 0.0, 90.0, 400.0, 700.0, 780.0] {
                for size in [vec2(24.0, 24.0), vec2(320.0, 180.0)] {
                    let sel = Rect::from_min_size(pos2(x, y), size);
                    let Some(bar) = place(sel, SIZE, &safe) else {
                        continue;
                    };
                    placed += 1;
                    assert!(
                        !bar.intersects(sel),
                        "the bar at {bar:?} covers the selection at {sel:?}",
                    );
                    assert!(
                        safe.region().contains_rect(bar),
                        "the bar at {bar:?} left {:?}",
                        safe.region(),
                    );
                }
            }
        }
        assert!(
            placed > 0,
            "no selection was placed — the sweep proved nothing"
        );
    }

    /// A selection bigger than the room around it now takes the band just
    /// inside its own leading edge (item 25). Phase G hid the bar here on
    /// invariant 5 — *the bar never covers what is selected* — and the user
    /// met the consequence as a missing overlay on every area. The invariant
    /// is kept where it can be: the bar goes outside the selection whenever
    /// there is an outside, and only an oversized selection sees it inside.
    #[test]
    fn a_selection_with_no_room_either_side_takes_the_band_inside_itself() {
        let sel = Rect::from_min_size(pos2(-100.0, -100.0), vec2(1200.0, 1000.0));
        let safe = SafeArea::over(viewport());
        let region = safe.region();
        assert!(
            !region.contains_rect(sel),
            "precondition: the selection overruns the region",
        );
        let placed = place(sel, SIZE, &safe).expect("an oversized selection still gets a bar");
        assert!(
            region.contains_rect(placed),
            "the bar landed outside the region at {placed:?}",
        );
        assert!(
            placed.top() >= region.top() + CLEAR,
            "the bar sits flush against the region's own edge: {placed:?}",
        );
    }

    // ---- §3.2 and §3.5: what the bar shows -----------------------------

    /// R35: the split is by what a command *is*, not by where it fell in the
    /// list. The user named the row — *"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.
    #[test]
    fn the_row_holds_the_primaries_and_the_clerical_verbs_go_behind_the_ellipsis() {
        let all: Vec<CommandId> = Harness::block().laid_out().iter().map(|c| c.0).collect();
        let Bar::Row {
            inline,
            overflow,
            all: whole,
        } = Bar::of(all.clone(), 1, Placement::of)
        else {
            panic!("a block's commands are a row");
        };
        for wanted in [
            CommandId::Accent,
            CommandId::ExpandBlock,
            CommandId::AddIcon,
            CommandId::FlipLr,
            CommandId::FlipUd,
        ] {
            assert!(
                inline.contains(&wanted),
                "{wanted:?} is not in the row: {inline:?}",
            );
        }
        assert!(
            inline
                .iter()
                .any(|id| matches!(id, CommandId::Lock | CommandId::Unlock)),
            "the lock toggle is not in the row: {inline:?}",
        );
        for clerical in [CommandId::Copy, CommandId::Cut, CommandId::Delete] {
            assert!(
                overflow.contains(&clerical),
                "{clerical:?} is still in the row: {inline:?}",
            );
        }
        assert!(
            overflow
                .iter()
                .any(|id| matches!(id, CommandId::ExportSelection(_))),
            "the selection export is still in the row: {inline:?}",
        );

        // Invariant 6 in its new form: the partition keeps the registry's
        // order inside each half, and the whole list keeps it outright — the
        // right-click menu reads that one (§3.6).
        assert_eq!(whole, all, "the split disturbed the one list");
        for half in [&inline, &overflow] {
            let mut in_registry_order: Vec<CommandId> =
                all.iter().copied().filter(|id| half.contains(id)).collect();
            in_registry_order.dedup();
            assert_eq!(*half, in_registry_order, "a half 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 — ride
    /// the row; the clerical ones go behind the ellipsis, exactly as a
    /// block's do, because placement lives on the command rather than on the
    /// type that offered it.
    #[test]
    fn a_ports_own_controls_ride_the_row_and_its_clerical_verbs_do_not() {
        let mut port = Harness::port();
        let ids: Vec<CommandId> = port.laid_out().iter().map(|c| c.0).collect();
        let Bar::Row {
            inline, overflow, ..
        } = Bar::of(ids.clone(), 1, Placement::of)
        else {
            panic!("a port raises no row: {ids:?}");
        };
        for own in [CommandId::PinType, CommandId::Accent, CommandId::FlipLr] {
            assert!(
                inline.contains(&own),
                "the port's own {own:?} is not in the row: {inline:?} / {overflow:?}",
            );
        }
        assert!(
            inline
                .iter()
                .any(|id| matches!(id, CommandId::HideTags | CommandId::ShowTags)),
            "the port's tag toggle is not in the row: {inline:?}",
        );
        for clerical in [CommandId::Copy, CommandId::Cut, CommandId::Delete] {
            assert!(
                overflow.contains(&clerical),
                "the port keeps {clerical:?} in the row: {inline:?}",
            );
        }
    }

    /// 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",
        );
    }

    /// Placement is orthogonal to applicability: a route and a block share
    /// the clerical verbs and put them in the same place, though almost
    /// nothing else about their two lists is the same.
    #[test]
    fn every_selection_type_puts_its_clerical_verbs_in_the_same_place() {
        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::Row {
                inline, overflow, ..
            } = Bar::of(ids.clone(), 1, Placement::of)
            else {
                panic!("{what} raises no row: {ids:?}");
            };
            for clerical in [CommandId::Copy, CommandId::Cut, CommandId::Delete] {
                assert!(
                    !inline.contains(&clerical),
                    "{what} keeps {clerical:?} in the row: {inline:?}",
                );
            }
            assert!(
                overflow.contains(&CommandId::Delete),
                "{what} lost Delete altogether: {ids:?}",
            );
        }
    }

    /// §3.2: a multi-selection whose members share nothing says so. A single
    /// selection with nothing to do to it shows no bar at all — there is
    /// nothing to explain, and a sentence beside one object reads as an error.
    /// Item 25, red first: 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");
    }

    /// The other half of item 25, which is where the bug actually was: an
    /// area is the one selection routinely *bigger* than the room around it,
    /// and `place` had no band for that — both candidates fell outside the
    /// region, so the bar stood down and the user saw no overlay at all.
    #[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),
        );
        assert!(
            area.selection.screen.top() - CLEAR - SIZE.y < region.top()
                && area.selection.screen.bottom() + CLEAR + SIZE.y > region.bottom(),
            "precondition: neither band outside the selection fits the region",
        );
        let placed = place(area.selection.screen, SIZE, &area.safe)
            .expect("a selection bigger than its room still has somewhere lawful");
        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",
        );
    }

    #[test]
    fn a_multi_selection_sharing_nothing_says_so_rather_than_showing_an_empty_bar() {
        assert!(matches!(
            Bar::of(Vec::<CommandId>::new(), 3, Placement::of),
            Bar::NothingShared
        ));
        assert!(matches!(
            Bar::of(Vec::<CommandId>::new(), 1, Placement::of),
            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::tools::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(),
        );
    }

    // ---- §3.6 right-click ----------------------------------------------

    /// Invariant 3: 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::tools::painted::Chrome::new(viewport().geom());
        let mut block = Harness::block();
        chrome.settle(|ui| block.show(ui));
        let expected: Vec<&str> = block.laid_out().iter().map(|c| c.1).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",
        );
    }

    // ---- §3.4 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, R19, 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" (R19). 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 §3 varies: 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, &'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,
        /// Every action a click fired.
        fired: Vec<Action>,
    }

    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)),
                    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))
                .collect();
            self.invocable = commands
                .iter()
                .filter(|cmd| drawn_in_overlay(cmd.id))
                .count();
            let theme = Theme::default();
            let (action, corner) = selection_overlay(
                ui,
                Overlay {
                    commands: &mut commands,
                    data: &drawing,
                    theme: &theme,
                    open_picker: None,
                    selection: Some(self.selection),
                    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, &'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()
    }
}