blockworx/shell/

top_bar.rs

//! The top bar: docked, flat, translucent, 54 tall, and the only persistent
//! chrome along the top of the window.
//!
//! Left is navigation, right is actions, centre is mode. That grammar is the
//! whole of the bar's layout rule, and it is why the document chip, the action
//! cluster, the viewing pill and the status chip's breadcrumb are one
//! component rather than four.
//!
//! **Nothing says "saved".** Every edit is already durable, so a save
//! indicator would be a lie about a step the user never takes. The dot beside
//! the menu is a *liveness* signal instead: green when everything is recorded,
//! yellow while the file catches up, red where nothing may be written, grey
//! for a session with no file at all — and each of the four says which it is
//! when the pointer rests on it.
//!
//! **Viewing is a state of this bar, not a second object.** While the lens is
//! open the bar tints amber and its centre fills with the rev, the stepper and
//! Return; nothing new arrives and nothing below it moves. Two of the three
//! signals live here — the tint and the words — with the dimmed tool rail and
//! the drained canvas ([`Saturation`](blockworx_paint::Saturation)) making up
//! the rest.

use crate::canvas::convert::IntoEgui as _;
use blockworx_doc::rev::Rev;
use blockworx_store::doc::{At, TimeStep, Viewing};

use crate::{
    history::{Direction, consequence},
    kernel::{Consequences, Crumb, Lens, Liveness, Locked, TopBar},
    panels::overlay::{EXPORT_ICON, export_format_menu, icon_image},
    preferences::Preferences,
    shell::glass::{self, Live, Opened, Tint},
    theme::{Role, Theme},
    tools::{
        commands::{Act, CommandId, CommandSet},
        tool::Action,
    },
};
// The one effect the bar raises is the rename, and only a container has a name
// to change.
#[cfg(not(target_arch = "wasm32"))]
use crate::tools::commands::Effect;

/// What the bar knows about the document it names, beyond the name itself.
#[cfg(not(target_arch = "wasm32"))]
pub struct Document<'a> {
    /// The rename box's text, which has to outlive the frame the user is
    /// typing in. Reset to the name whenever the box opens, so it always
    /// starts from the document's real name.
    pub draft: &'a mut String,
    pub renaming: blockworx_store::doc::Renaming,
}

/// Everything the bar renders against: what the session says, and what
/// the shell adds — which panel is up, the appearance menu, the recent
/// list and the rename box.
pub struct Docked<'a> {
    pub model: &'a TopBar,
    /// Whether the navigator is on screen, which draws Browse pressed.
    pub navigator: Opened,
    pub theme: &'a Theme,
    pub prefs: &'a mut Preferences,
    /// The containers the menu offers to reopen, most recent first.
    #[cfg(not(target_arch = "wasm32"))]
    pub recent: &'a [std::path::PathBuf],
    /// The document the breadcrumb's root segment can rename.
    #[cfg(not(target_arch = "wasm32"))]
    pub document: Document<'a>,
}

/// What one bar frame asked for: an action to dispatch, or the navigator
/// toggled — which is chrome state, not a document action.
pub struct Clicked {
    pub action: Option<Act>,
    pub browse: bool,
}

/// Draw the bar in its berth.
pub fn top_bar(
    chrome: &mut super::Chrome,
    commands: &mut CommandSet,
    mut bar: Docked<'_>,
) -> Clicked {
    let viewing = bar.model.lens.viewing;
    let width = chrome.safe().viewport().width();
    let tint = tint(chrome.ctx(), viewing, bar.theme);
    chrome.shaped(glass::Berth::TopBar, egui::Vec2::ZERO, tint, |ui| {
        ui.set_width(width - 2.0 * f32::from(glass::Shape::TopBar.margin().left));
        let mut clicked = Clicked {
            action: None,
            browse: false,
        };
        let take = |clicked: &mut Clicked, act: Option<Act>| {
            if act.is_some() {
                clicked.action = act;
            }
        };
        let picked = left(ui, commands, &mut bar);
        take(&mut clicked, picked.action);
        // The right run is laid out from the right edge inward, and what is
        // left between the two runs is the centre — the mockup's own
        // `.left{flex:none} .center{flex:1} .right{flex:none}`.
        ui.allocate_ui_with_layout(
            ui.available_size(),
            egui::Layout::right_to_left(egui::Align::Center),
            |ui| {
                let right = right(ui, commands, &bar.model.steps, bar.navigator, viewing);
                take(&mut clicked, right.action);
                clicked.browse |= right.browse;
                take(
                    &mut clicked,
                    centre(ui, &bar.model.lens, bar.theme).map(Act::from),
                );
            },
        );
        clicked
    })
}

/// How amber the bar is this frame. The mockup transitions the *background*
/// where it swaps the centre outright, so the colour is what animates and the
/// words simply appear — the bar you already look at changes state.
fn tint(ctx: &egui::Context, viewing: Viewing, theme: &Theme) -> Tint {
    let through = glass::Progress::new(ctx.animate_bool_with_time(
        egui::Id::new("top_bar_tint"),
        matches!(viewing, Viewing::Past(_)),
        glass::TINT_MOTION.as_secs_f32(),
    ));
    if f32::from(through) <= 0.0 {
        return Tint::None;
    }
    Tint::Over(
        theme
            .resolve(Role::ViewingTint)
            .egui()
            .gamma_multiply(f32::from(through)),
    )
}

/// Left: the document menu, the liveness dot, and the edit-context breadcrumb
/// rooted at the document's own name.
fn left(ui: &mut egui::Ui, commands: &mut CommandSet, bar: &mut Docked<'_>) -> Picked {
    let mut picked = menu(ui, commands, bar);
    live_dot(ui, bar.model.liveness, bar.theme);
    if let Some(crumb) = breadcrumb(ui, bar) {
        picked.action = Some(crumb);
    }
    picked
}

/// What the bar's left run asked for.
#[derive(Default)]
struct Picked {
    action: Option<Act>,
}

/// The mockup's `.dot`. It is a mark rather than a control, so it is sized
/// to the words beside it — and it always carries them, since a colour alone
/// is a signal only to whoever already knows the code.
fn live_dot(ui: &mut egui::Ui, liveness: Liveness, theme: &Theme) {
    let (role, says) = dot(liveness);
    ui.add_space(DOT_LEAD);
    let (rect, response) =
        ui.allocate_exact_size(egui::Vec2::splat(DOT_SIZE), egui::Sense::hover());
    ui.painter()
        .circle_filled(rect.center(), DOT_SIZE * 0.5, theme.resolve(role).egui());
    response.on_hover_text(says);
    ui.add_space(DOT_LEAD);
}

/// What the dot says, in colour and in words. Every state says both: the
/// user could read three of the four colours and not the fourth, and a mark
/// that means something only to whoever wrote it means nothing.
fn dot(liveness: Liveness) -> (Role, &'static str) {
    match liveness {
        Liveness::Recorded => (Role::LiveDot, "All changes recorded"),
        Liveness::ReadOnly(Locked::Lens) => (
            Role::DotReadOnly,
            "Read-only \u{2014} an earlier rev is on the canvas",
        ),
        Liveness::ReadOnly(Locked::Container) => (
            Role::DotReadOnly,
            "Read-only \u{2014} this document was opened without a write lock",
        ),
        Liveness::Scratch => (
            Role::DotScratch,
            "Scratch session \u{2014} not yet saved to disk",
        ),
    }
}

/// The edit-context breadcrumb, rooted at the document.
///
/// It collapses from the middle: the root and the level the canvas is
/// standing on are never hidden, and what falls out between them goes behind
/// one ellipsis that lists it. Segments truncate rather than wrap, so a long
/// block name cannot push the centre off the bar.
fn breadcrumb(ui: &mut egui::Ui, bar: &mut Docked<'_>) -> Option<Act> {
    let mut action = None;
    ui.spacing_mut().item_spacing.x = SEGMENT_GAP;
    let here = bar.model.scope.here();
    for shown in bar.model.scope.collapsed() {
        match shown {
            Crumb::Root => {
                if let Some(picked) = root_segment(ui, bar, here) {
                    action = Some(picked);
                }
            }
            Crumb::Level(depth) => {
                separator(ui);
                let name = &bar.model.scope.names[depth - 1];
                if segment(ui, name, Standing::from(depth == here)) {
                    action = Some(bar.model.scope.up_to(depth).into());
                }
            }
            Crumb::Elided(hidden) => {
                separator(ui);
                if let Some(depth) = elision(ui, &bar.model.scope.names, hidden) {
                    action = Some(bar.model.scope.up_to(depth).into());
                }
            }
        }
    }
    action
}

/// The document's own segment: the way back to the root, and — on a double
/// click — the box that types over the name.
///
/// Both gestures on one word is the cost of the grammar: the document sits at
/// the head of the breadcrumb, and it is renamed where it stands. The two are
/// told apart in time rather than by giving one of them somewhere else
/// to live.
fn root_segment(ui: &mut egui::Ui, bar: &mut Docked<'_>, here: usize) -> Option<Act> {
    #[cfg(not(target_arch = "wasm32"))]
    {
        let renaming = bar.document.renaming;
        let name = bar.model.name.as_str();
        let draft = &mut *bar.document.draft;
        if let Some(typed) = name_in_place(ui, name, draft, renaming, Standing::from(here == 0)) {
            return Some(match typed {
                Typed::Renamed(to) => Effect::RenameDocument(to).into(),
                Typed::Rose => bar.model.scope.up_to(0).into(),
            });
        }
        None
    }
    #[cfg(target_arch = "wasm32")]
    {
        // The web build has no container to rename, so the name is a segment
        // like any other there — full ink all the same (`.crumb.root`).
        let standing = Standing::from(here == 0);
        let response = crumb(ui, &bar.model.name, Voice::Full, Listens::from(standing));
        (standing == Standing::Ancestor && response.clicked())
            .then(|| bar.model.scope.up_to(0).into())
    }
}

/// What a click on the document's segment came to.
#[cfg(not(target_arch = "wasm32"))]
enum Typed {
    Renamed(String),
    Rose,
}

/// The document's name, and — once it has been double-clicked — the box that
/// types over it.
///
/// Whether the box is open is egui's to remember, not the document's: it is
/// chrome state that dies with the session, and threading it through `App`
/// would make a transient of the same rank as the path.
#[cfg(not(target_arch = "wasm32"))]
fn name_in_place(
    ui: &mut egui::Ui,
    name: &str,
    draft: &mut String,
    renaming: blockworx_store::doc::Renaming,
    standing: Standing,
) -> Option<Typed> {
    let editing = ui
        .ctx()
        .data(|d| d.get_temp(renaming_id()).unwrap_or(false));
    let close = |ui: &egui::Ui| {
        ui.ctx().data_mut(|d| d.insert_temp(renaming_id(), false));
    };
    if !editing {
        // The mockup gives the document full ink wherever it stands
        // (`.crumb.root`), and it answers a gesture wherever it stands too,
        // since the rename lives on it even at the root.
        let response = crumb(ui, name, Voice::Full, Listens::Yes);
        let renames =
            response.double_clicked() && renaming == blockworx_store::doc::Renaming::Offered;
        if renames {
            draft.clear();
            draft.push_str(name);
            ui.ctx().data_mut(|d| d.insert_temp(renaming_id(), true));
            ui.ctx().memory_mut(|m| m.request_focus(name_field_id()));
        }
        // egui reports the first half of a double click as a click of its
        // own, so the rise is armed and waited out rather than taken: a
        // rename would otherwise leave the root on the canvas and a view
        // entry on the undo stack on its way to the box.
        if renames || response.double_clicked() {
            disarm_rise(ui.ctx());
        } else if response.clicked() && standing == Standing::Ancestor {
            arm_rise(ui.ctx());
        }
        let hint = match renaming {
            blockworx_store::doc::Renaming::Offered => RENAME_HINT,
            blockworx_store::doc::Renaming::Withheld => RENAME_WITHHELD,
        };
        response.on_hover_text(hint);
        return rise_is_due(ui.ctx()).then_some(Typed::Rose);
    }
    let field = ui.add(
        egui::TextEdit::singleline(draft)
            .id(name_field_id())
            .desired_width(NAME_WIDTH),
    );
    if ui.input(|i| i.key_pressed(egui::Key::Escape)) {
        close(ui);
        return None;
    }
    // Clicking away is a commit rather than a cancel: the box opened on the
    // document's own name, so the worst it can settle on is the name it
    // started with.
    if field.lost_focus() {
        close(ui);
        return (draft.as_str() != name).then(|| Typed::Renamed(draft.clone()));
    }
    None
}

/// The mockup's `···`, which lists what it hid rather than merely saying
/// that it hid something.
///
/// Its box is fixed rather than hugged: egui reads a button's margins out of
/// the state it is in, so a box left to its contents is a box that changes
/// width under the pointer — the shifting item 2 is about.
fn elision(ui: &mut egui::Ui, names: &[String], hidden: Vec<usize>) -> Option<usize> {
    let mut picked = None;
    let button = egui::Button::new(egui::RichText::new(ELLIPSIS).weak())
        .min_size(egui::vec2(ELLIPSIS_WIDTH, CRUMB_HEIGHT))
        .corner_radius(CRUMB_RADIUS)
        .frame_when_inactive(false);
    egui::containers::menu::MenuButton::from_button(button).ui(ui, |ui| {
        ui.style_mut().wrap_mode = Some(egui::TextWrapMode::Extend);
        for depth in hidden {
            if let Some(name) = names.get(depth - 1)
                && ui.button(name).clicked()
            {
                picked = Some(depth);
            }
        }
    });
    picked
}

/// Whether a segment is where the canvas is standing or somewhere it could go.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Standing {
    Here,
    Ancestor,
}

impl From<bool> for Standing {
    fn from(here: bool) -> Self {
        if here {
            Standing::Here
        } else {
            Standing::Ancestor
        }
    }
}

/// One segment. The level on the canvas reads at full strength and is a
/// label — *"the last segment in the breadcrumb is not clickable. It's a
/// label that indicates where we are in the hierarchy."* — and its ancestors
/// are quieted, pressable words.
fn segment(ui: &mut egui::Ui, text: &str, standing: Standing) -> bool {
    let response = crumb(ui, text, Voice::from(standing), Listens::from(standing));
    match standing {
        Standing::Here => false,
        Standing::Ancestor => response.on_hover_text(format!("Go to {text}")).clicked(),
    }
}

/// How loudly a segment reads. The mockup gives two of them full ink — the
/// document at the head of the trail (`.crumb.root`) and the level the canvas
/// is standing on (`.crumb.here`) — and mutes what lies between.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Voice {
    Full,
    Muted,
}

impl From<Standing> for Voice {
    fn from(standing: Standing) -> Self {
        match standing {
            Standing::Here => Voice::Full,
            Standing::Ancestor => Voice::Muted,
        }
    }
}

/// Whether a segment answers the pointer at all. Where the canvas is already
/// standing it does not: `.crumb.here` is `cursor:default` with its hover
/// treatment struck out, because there is nowhere for a click to go.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Listens {
    Yes,
    No,
}

impl From<Standing> for Listens {
    fn from(standing: Standing) -> Self {
        match standing {
            Standing::Here => Listens::No,
            Standing::Ancestor => Listens::Yes,
        }
    }
}

/// The mockup's `.crumb`: 32 tall, 9 of shoulder either side, and capped at
/// [`CRUMB_WIDTH`] with an ellipsis so one long name cannot push the bar's
/// centre aside.
///
/// Painted rather than pressed, because egui's button is not a fixed box:
/// its margins come out of the visuals for the state it is in
/// (`button_padding + expansion - stroke width`), so a segment changes size
/// the moment the pointer crosses it. The user: *"The shifting of text layout
/// as you hover over the breadcrumb elements is disturbing."* Here the box is
/// the same in every state and the hover is a fill inside it.
fn crumb(ui: &mut egui::Ui, text: &str, voice: Voice, listens: Listens) -> egui::Response {
    let font = egui::TextStyle::Body.resolve(ui.style());
    let mut job = egui::text::LayoutJob::simple_singleline(
        text.to_owned(),
        font,
        // Chosen once the response says whether the pointer is on it, which
        // is after the galley has to exist to be measured.
        egui::Color32::PLACEHOLDER,
    );
    job.wrap = egui::text::TextWrapping::truncate_at_width(CRUMB_WIDTH - 2.0 * CRUMB_PAD);
    let galley = ui.painter().layout_job(job);
    let size = egui::vec2(galley.size().x + 2.0 * CRUMB_PAD, CRUMB_HEIGHT);
    let sense = match listens {
        Listens::Yes => egui::Sense::click(),
        Listens::No => egui::Sense::hover(),
    };
    let (rect, response) = ui.allocate_exact_size(size, sense);
    if !ui.is_rect_visible(rect) {
        return response;
    }
    let visuals = ui.visuals();
    let ink = match (voice, listens == Listens::Yes && response.hovered()) {
        (Voice::Full, _) | (Voice::Muted, true) => glass::full_ink(visuals),
        (Voice::Muted, false) => visuals.weak_text_color(),
    };
    if listens == Listens::Yes && (response.hovered() || response.is_pointer_button_down_on()) {
        let fill = ui.style().interact(&response).weak_bg_fill;
        ui.painter().rect_filled(rect, CRUMB_RADIUS, fill);
    }
    let at = egui::pos2(
        rect.left() + CRUMB_PAD,
        rect.center().y - galley.size().y * 0.5,
    );
    ui.painter().galley(at, galley, ink);
    response
}

/// Arm the rise the document's segment was asked for, to be taken once the
/// second click of a double cannot arrive any more.
#[cfg(not(target_arch = "wasm32"))]
fn arm_rise(ctx: &egui::Context) {
    let at = ctx.input(|i| i.time);
    ctx.data_mut(|data| data.insert_temp(rising_id(), Rising { at }));
    ctx.request_repaint_after(double_click_window(ctx));
}

#[cfg(not(target_arch = "wasm32"))]
fn disarm_rise(ctx: &egui::Context) {
    ctx.data_mut(|data| data.remove::<Rising>(rising_id()));
}

/// Whether an armed rise has outlived egui's own double-click window, and so
/// is a single click after all. It asks for exactly the frame it will fire
/// on, so an idle bar still settles.
#[cfg(not(target_arch = "wasm32"))]
fn rise_is_due(ctx: &egui::Context) -> bool {
    let Some(armed) = ctx.data(|data| data.get_temp::<Rising>(rising_id())) else {
        return false;
    };
    let waited = core::time::Duration::from_secs_f64((ctx.input(|i| i.time) - armed.at).max(0.0));
    match double_click_window(ctx).checked_sub(waited) {
        None | Some(core::time::Duration::ZERO) => {
            disarm_rise(ctx);
            true
        }
        Some(left) => {
            ctx.request_repaint_after(left);
            false
        }
    }
}

/// How long egui itself waits before it stops calling two clicks one — read
/// from egui rather than restated, so the bar and the toolkit cannot
/// disagree about what a double click is.
#[cfg(not(target_arch = "wasm32"))]
fn double_click_window(ctx: &egui::Context) -> core::time::Duration {
    core::time::Duration::from_secs_f64(
        ctx.options(|options| options.input_options.max_double_click_delay),
    )
}

/// A click on the document's segment that has not yet proved to be a single
/// one.
#[cfg(not(target_arch = "wasm32"))]
#[derive(Clone, Copy)]
struct Rising {
    at: f64,
}

fn separator(ui: &mut egui::Ui) {
    ui.label(egui::RichText::new(SEPARATOR).weak());
}

/// The centre: empty unless a mode is active, and centred in the room the
/// two runs left rather than in the window — the mockup's own
/// `.center{flex:1;justify-content:center}`.
///
/// egui lays a row out from where the cursor is, so the row is measured on a
/// pass of its own before it is placed. The alternative — adding up the
/// widths of what the row holds — is the same layout written twice, and the
/// copy drifts the first time the mode gains a control.
fn centre(ui: &mut egui::Ui, lens: &Lens, theme: &Theme) -> Option<Action> {
    if !matches!(lens.viewing, Viewing::Past(_)) {
        return None;
    }
    let room = ui.available_rect_before_wrap();
    let row = |rect: egui::Rect| {
        egui::UiBuilder::new()
            .max_rect(rect)
            .layout(egui::Layout::left_to_right(egui::Align::Center))
    };
    let wanted = {
        let mut probe = ui.new_child(row(room).sizing_pass().invisible());
        let _ = mode(&mut probe, lens, theme);
        probe.min_rect().width().min(room.width())
    };
    let at = egui::Rect::from_min_size(
        egui::pos2(room.center().x - wanted * 0.5, room.top()),
        egui::vec2(wanted, room.height()),
    );
    let mut child = ui.new_child(row(at));
    let action = mode(&mut child, lens, theme);
    ui.advance_cursor_after_rect(room);
    action
}

/// What the centre holds while the lens is open: the rev, the stepper that
/// walks it, and the one way out.
fn mode(ui: &mut egui::Ui, lens: &Lens, theme: &Theme) -> Option<Action> {
    let Viewing::Past(at) = lens.viewing else {
        return None;
    };
    let ink = theme.resolve(Role::ViewingInk).egui();
    let mut action = None;
    // The centre is inverse video against the amber, so the icons on it have
    // to be too: egui tints them from the enclosing style's foreground, which
    // is the one meant for the untinted bar around it.
    ui.visuals_mut().widgets.inactive.fg_stroke.color = ink;
    ui.label(
        egui::RichText::new(headline(at, &lens.age))
            .color(ink)
            .strong(),
    );
    if let Some(stepped) = stepper(ui, lens) {
        action = Some(stepped);
    }
    if glass::tap_filled(
        ui,
        RETURN,
        theme.resolve(Role::ViewingInk).egui(),
        theme.resolve(Role::ViewingReturnInk).egui(),
        RETURN_HINT,
    )
    .clicked()
    {
        action = Some(Action::ViewHead);
    }
    action
}

/// What the centre leads with: the rev, and how long ago it was written where
/// there is a clock to say. Lower-case "rev" throughout the chrome.
///
/// The rev's *name* is not here: the history row is where a tag is read —
/// one surface for the name rather than two that can word it differently.
fn headline(at: Rev, age: &str) -> String {
    let rev = format!("Rev {}", at.get());
    match age.trim() {
        "" => rev,
        age => format!("{rev} \u{00b7} {age}"),
    }
}

/// The stepper: adjacent revs differ by one operation, so walking them is how
/// a reader finds the change — row selection is the fallback, not the primary
/// interaction. Stepping off the newest rev closes the loop back into
/// the writable present.
fn stepper(ui: &mut egui::Ui, lens: &Lens) -> Option<Action> {
    let mut action = None;
    for (icon, hover, to) in [
        (
            STEP_OLDER_ICON,
            "Older rev",
            lens.viewing.stepped(lens.head, TimeStep::Back),
        ),
        (
            STEP_NEWER_ICON,
            "Newer rev",
            lens.viewing.stepped(lens.head, TimeStep::Forward),
        ),
    ] {
        if glass::tap_button(ui, icon, Live::from(to.is_some()), hover).clicked() {
            action = Some(match to {
                Some(At::Rev(rev)) => Action::ViewRev(rev),
                _ => Action::ViewHead,
            });
        }
    }
    action
}

/// Right: undo, redo, then the two that move the view and the one that opens
/// the navigator. Laid out from the right edge inward, so the list below
/// reads backwards and the bar reads `undo redo | up fit browse`.
fn right(
    ui: &mut egui::Ui,
    commands: &mut CommandSet,
    steps: &Consequences,
    navigator: Opened,
    viewing: Viewing,
) -> Clicked {
    let mut clicked = None;
    let browse = glass::tap_toggle(
        ui,
        BROWSE_ICON,
        Live::Yes,
        navigator,
        browse_hover(ui.ctx()),
    )
    .clicked();
    let fit = commands.contains(CommandId::FitView);
    if glass::tap_button(ui, FIT_ICON, Live::from(fit), fit_hover(ui.ctx())).clicked() {
        clicked = Some(CommandId::FitView);
    }
    // The user's own order: *"After Undo/Redo | <Go Up> <Fit> <Panel>, where
    // <Go Up> is enabled if we can pop something off of our scope."* The
    // registry is what knows whether there is a scope to pop, so the button
    // reads it rather than forming a second opinion.
    let can_rise = Live::from(commands.contains(CommandId::GoUp));
    if glass::tap_button(ui, UP_ICON, can_rise, rise_hover(can_rise)).clicked() {
        clicked = Some(CommandId::GoUp);
    }
    // What takes back an edit and what moves the camera are two different
    // kinds of thing, so the mockup's separator stands between them.
    glass::separator(ui, glass::Run::Row);
    if let Some(id) = tape(ui, commands, steps, viewing) {
        clicked = Some(id);
    }
    Clicked {
        action: clicked.and_then(|id| commands.take(id)),
        browse,
    }
}

/// Undo and redo, in the order a right-to-left run wants them.
fn tape(
    ui: &mut egui::Ui,
    commands: &mut CommandSet,
    steps: &Consequences,
    viewing: Viewing,
) -> Option<CommandId> {
    let mut clicked = None;
    for (id, icon, step, of) in [
        (CommandId::Redo, REDO_ICON, Direction::Forward, &steps.redo),
        (CommandId::Undo, UNDO_ICON, Direction::Back, &steps.undo),
    ] {
        let live = Live::from(commands.contains(id));
        let hover = consequence(step, of.as_ref(), (live == Live::Yes).into(), viewing);
        if glass::tap_button(ui, icon, live, hover).clicked() {
            clicked = Some(id);
        }
    }
    clicked
}

/// Fit names its chord, since it is the one button whose keyboard equivalent
/// nothing else shows.
fn fit_hover(ctx: &egui::Context) -> String {
    let chords: Vec<String> = crate::tools::commands::chords(CommandId::FitView)
        .map(|chord| crate::keys::spelled(ctx, *chord))
        .collect();
    if chords.is_empty() {
        FIT.to_owned()
    } else {
        format!("{FIT} ({})", chords.join(", "))
    }
}

/// The word for the button is *Browse*, not Panels — it is not workspace
/// furniture being shown or hidden.
fn browse_hover(ctx: &egui::Context) -> String {
    let chord = ctx.format_shortcut(&egui::KeyboardShortcut::new(
        egui::Modifiers::COMMAND,
        egui::Key::Backslash,
    ));
    format!("{BROWSE} ({chord})")
}

/// Rising a level names where it would land, and where it cannot: the
/// button's consequence varies with where the canvas is standing.
fn rise_hover(can_rise: Live) -> &'static str {
    if can_rise == Live::Yes {
        "Go up a level \u{2014} out to the scope that holds this one"
    } else {
        "Go up a level \u{2014} the canvas is at the document root"
    }
}

/// The project itself, offered under Help.
const GITHUB_URL: &str = "https://github.com/samitbasu/blockworx";

/// The bar's one menu. The bar has a single document affordance, so a second
/// icon beside it would be a second document menu.
fn menu(ui: &mut egui::Ui, commands: &mut CommandSet, bar: &mut Docked<'_>) -> Picked {
    let mut picked = Picked::default();
    let button = egui::Button::image(icon_image(ui, MENU_ICON))
        .min_size(egui::Vec2::splat(glass::TAP))
        .frame_when_inactive(false);
    egui::containers::menu::MenuButton::from_button(button)
        .ui(ui, |ui| {
            ui.style_mut().wrap_mode = Some(egui::TextWrapMode::Extend);
            #[cfg(not(target_arch = "wasm32"))]
            if let Some(chosen) =
                crate::panels::file_menu::menu(ui, bar.recent, bar.model.lens.viewing)
            {
                picked.action = Some(chosen.into());
            }
            #[cfg(not(target_arch = "wasm32"))]
            ui.separator();
            if let Some(chosen) = import_export(ui, commands) {
                picked.action = Some(chosen);
            }
            ui.separator();
            ui.menu_button("Help", |ui| {
                // See `preferences_menu::no_wrap`: a menu popup shrinks to
                // fit, and a proportional font can round a label just past
                // that width, wrapping the last glyph.
                ui.style_mut().wrap_mode = Some(egui::TextWrapMode::Extend);
                if ui.button("GitHub").clicked() {
                    ui.ctx().open_url(egui::OpenUrl::new_tab(GITHUB_URL));
                }
            });
            ui.menu_button("Preferences", |ui| {
                crate::preferences_menu::menu(ui, bar.prefs);
            });
            ui.separator();
            palette_hint(ui);
        })
        .0
        .on_hover_text("Document menu");
    picked
}

/// The command palette's chord, told rather than offered: the palette is a
/// keyboard surface, and no persistent search field belongs in the chrome.
fn palette_hint(ui: &mut egui::Ui) {
    let chord = ui.ctx().format_shortcut(&egui::KeyboardShortcut::new(
        egui::Modifiers::COMMAND,
        egui::Key::K,
    ));
    ui.add_enabled(
        false,
        egui::Button::new(format!("Search tools, blocks and revs\u{2003}{chord}")),
    );
}

/// Diagrams in and out. The format is picked up front rather than in a save
/// dialog: the web dialog can offer no format chooser, so a dialog-driven
/// choice would always yield SVG there.
fn import_export(ui: &mut egui::Ui, commands: &mut CommandSet) -> Option<Act> {
    let mut action = None;
    // Import lands a document as a block in the current level, so it is a
    // write like any other and the registry gates it.
    let import = ui.add_enabled(
        commands.contains(CommandId::Import),
        egui::Button::image_and_text(icon_image(ui, IMPORT_ICON), "Import\u{2026}"),
    );
    if import.clicked() {
        action = commands.take(CommandId::Import);
    }
    ui.menu_image_text_button(icon_image(ui, EXPORT_ICON), "Export", |ui| {
        ui.style_mut().wrap_mode = Some(egui::TextWrapMode::Extend);
        if let Some(format) = export_format_menu(ui, crate::export::ExportScope::View) {
            action = Some(
                Action::Export {
                    format,
                    selection: None,
                }
                .into(),
            );
        }
    });
    action
}

/// Escape returns to the present from anywhere.
///
/// Claimed here rather than in the editor's keyboard handler because the bar
/// is in the mode exactly when the key means this, and claimed *before* the
/// canvas pass so a tool still armed from before the lens opened cannot answer
/// the key first. A focused text field — the palette's box, the rename box —
/// keeps its own Escape.
pub fn escape_exits(ctx: &egui::Context) -> Option<Action> {
    let pressed = !ctx.egui_wants_keyboard_input()
        && ctx.input_mut(|i| i.consume_key(egui::Modifiers::NONE, egui::Key::Escape));
    pressed.then_some(Action::ViewHead)
}

/// Where the armed rise is kept: chrome state that dies with the session.
#[cfg(not(target_arch = "wasm32"))]
fn rising_id() -> egui::Id {
    egui::Id::new("top_bar_rising")
}

#[cfg(not(target_arch = "wasm32"))]
fn renaming_id() -> egui::Id {
    egui::Id::new("top_bar_renaming")
}

#[cfg(not(target_arch = "wasm32"))]
fn name_field_id() -> egui::Id {
    egui::Id::new("top_bar_name_field")
}

/// Where a document is renamed.
#[cfg(not(target_arch = "wasm32"))]
const RENAME_HINT: &str = "Double-click to rename";
/// The same name, on a session that cannot rename it — disabled, not silent.
#[cfg(not(target_arch = "wasm32"))]
const RENAME_WITHHELD: &str = "This session has no diagram on disk to rename";
/// How wide the box that types over the name stands.
#[cfg(not(target_arch = "wasm32"))]
const NAME_WIDTH: f32 = 160.0;

const FIT: &str = "Zoom to fit";
const BROWSE: &str = "Browse";
const RETURN: &str = "Return";
const RETURN_HINT: &str = "Return to current (Escape)";

/// The mockup's `.dot{width:8px;margin:0 6px 0 4px}`.
const DOT_SIZE: f32 = 8.0;
const DOT_LEAD: f32 = 4.0;

/// The mockup's `.crumb{height:32px;padding:0 9px;max-width:200px;
/// border-radius:9px}` and `.crumbs{gap:1px}`.
const CRUMB_HEIGHT: f32 = 32.0;
const CRUMB_WIDTH: f32 = 200.0;
const CRUMB_PAD: f32 = 9.0;
const CRUMB_RADIUS: u8 = 9;
/// The mockup's `.crumb.ell{padding:0 7px}` around three dots — a fixed box,
/// so the collapse's own segment does not shift under the pointer either.
const ELLIPSIS_WIDTH: f32 = 30.0;
const SEGMENT_GAP: f32 = 1.0;
const SEPARATOR: &str = "/";
const ELLIPSIS: &str = "\u{00b7}\u{00b7}\u{00b7}";

/// The mockup's own document-menu glyph, three lines with a short last one
/// — *"The ellipses icon is hard to see. The icon from the mockup was
/// better."* The selection bar's overflow keeps the horizontal ellipsis, so
/// no two surfaces wear one mark.
const MENU_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-menu.svg");
const IMPORT_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-import.svg");
const UNDO_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-undo.svg");
const REDO_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-redo.svg");
const FIT_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-fit.svg");
const UP_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-level-up.svg");
const BROWSE_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-panel.svg");
/// The mockup's own stepper: an arrow down into the log for the older rev
/// and one up out of it for the newer — *"instead of left and right index
/// controls in the rev view bar, use the up and down arrows from the mockup
/// concept. They take up less space and feel cleaner."* The mapping is the
/// mockup's (`#stepold` points down), and the tooltips still say which.
const STEP_OLDER_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-step-older.svg");
const STEP_NEWER_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-step-newer.svg");

#[cfg(test)]
mod tests {
    use super::*;
    use crate::canvas::convert::IntoGeom as _;
    use crate::history::{Consequence, Kind};
    use crate::panels::painted::Chrome;
    use crate::path::BlockPath;
    use crate::path::Scope as PathScope;
    use crate::shell::tests::screen;
    use crate::tools::commands::{CommandContext, History};
    use crate::widget::test_fixtures::{self as fx, Scene};
    use blockworx_doc::fixtures::{block_id, rev};
    use blockworx_geom::{Pos2, Rect};
    use blockworx_store::doc::{Attachment, Saving, Viewing, Writability};

    fn of(target: &str, kind: Kind) -> Consequence {
        Consequence {
            target: target.to_owned(),
            kind,
        }
    }

    const DOCUMENT: &str = "engine";
    /// How far past a segment's own height its plate may stand — egui
    /// expands a pressed control by a point, and the plate is still that
    /// control's.
    const PLATE_SLACK: f32 = 4.0;
    /// The commit one undo would take back — what the button's tooltip names.
    const NEWEST: &str = "Add block Filter";
    /// The log the mode is a view of: rev 2 of four.
    const AT: u64 = 2;
    const HEAD: u64 = 4;

    /// The session the bar is a view of.
    struct Session {
        history: History,
        steps: Consequences,
        /// What both tape buttons stand over, so a session can be put under
        /// the lens with a view entry on top and asked whether undo works.
        kind: Kind,
        writability: Writability,
        attachment: Attachment,
        viewing: Viewing,
        navigator: Opened,
        prefs: Preferences,
        theme: Theme,
        scene: Scene,
        path: BlockPath,
        names: Vec<String>,
        #[cfg(not(target_arch = "wasm32"))]
        draft: String,
        #[cfg(not(target_arch = "wasm32"))]
        renaming: blockworx_store::doc::Renaming,
        fired: Vec<Act>,
        browses: usize,
    }

    impl Session {
        fn new() -> Self {
            Session {
                history: History::doc(),
                steps: Consequences {
                    undo: Some(of(NEWEST, Kind::Doc)),
                    redo: Some(of("Delete block Filter", Kind::Doc)),
                },
                kind: Kind::Doc,
                writability: Writability::Writable,
                attachment: Attachment::Attached,
                viewing: Viewing::Head,
                navigator: Opened::No,
                prefs: Preferences::default(),
                theme: Theme::default(),
                scene: Scene::new(Vec::new()),
                path: BlockPath::empty(),
                names: Vec::new(),
                #[cfg(not(target_arch = "wasm32"))]
                draft: String::new(),
                #[cfg(not(target_arch = "wasm32"))]
                renaming: blockworx_store::doc::Renaming::Offered,
                fired: Vec::new(),
                browses: 0,
            }
        }

        /// A session standing `depth` levels inside the document, with a name
        /// for every level — what the breadcrumb is a picture of.
        fn nested(depth: usize) -> Self {
            let body = egui::Rect::from_min_max(egui::pos2(0.0, 0.0), egui::pos2(60.0, 60.0));
            let mut ops = Vec::new();
            let mut path = BlockPath::empty();
            let mut names = Vec::new();
            for level in 1..=depth {
                let id = block_id(level as u32);
                let scope = match level {
                    1 => PathScope::Root,
                    _ => PathScope::Block(block_id(level as u32 - 1)),
                };
                ops.push(fx::block_in(level as u32, scope, body.geom()));
                ops.push(fx::titled(level as u32, &format!("Level {level}")));
                path.push(id);
                names.push(format!("Level {level}"));
            }
            let mut session = Session::new();
            // The registry reads the *drawing's* scope, not the path beside
            // it, so a breadcrumb without one would draw Go Up dead.
            session.scene = Scene::new(ops).inside(block_id(depth as u32));
            session.path = path;
            session.names = names;
            session
        }

        fn under_the_lens(mut self) -> Self {
            self.viewing = Viewing::Past(rev(AT));
            self
        }

        fn frame(&mut self, ui: &mut egui::Ui) {
            let tool: crate::tools::tool::Tool = crate::tools::SelectTool.into();
            let mut commands = {
                let drawing = self.scene.drawing();
                CommandSet::available(&CommandContext {
                    tool: &tool,
                    data: &drawing,
                    history: self.history,
                    current_lock: crate::edit::naming::InterfaceLock::Unlocked,
                    writability: self.writability,
                    saving: Saving::Withheld,
                    viewing: self.viewing,
                })
            };
            let mut chrome = crate::shell::Chrome::over(ui.ctx(), ui.max_rect());
            let steps = Consequences {
                undo: self.steps.undo.as_ref().map(|of| Consequence {
                    target: of.target.clone(),
                    kind: self.kind,
                }),
                redo: self.steps.redo.as_ref().map(|of| Consequence {
                    target: of.target.clone(),
                    kind: self.kind,
                }),
            };
            let model = TopBar {
                name: DOCUMENT.to_owned(),
                scope: crate::kernel::ScopePath {
                    path: self.path.clone(),
                    names: self.names.clone(),
                },
                steps,
                lens: Lens {
                    viewing: self.viewing,
                    head: rev(HEAD),
                    age: "3 hours ago".to_owned(),
                },
                liveness: Liveness::of(self.viewing, self.writability, self.attachment),
                #[cfg(not(target_arch = "wasm32"))]
                renaming: self.renaming,
            };
            let clicked = top_bar(
                &mut chrome,
                &mut commands,
                Docked {
                    model: &model,
                    navigator: self.navigator,
                    theme: &self.theme,
                    prefs: &mut self.prefs,
                    #[cfg(not(target_arch = "wasm32"))]
                    recent: &[],
                    #[cfg(not(target_arch = "wasm32"))]
                    document: Document {
                        draft: &mut self.draft,
                        renaming: self.renaming,
                    },
                },
            );
            if let Some(act) = clicked.action {
                self.fired.push(act);
            }
            if clicked.browse {
                self.browses += 1;
            }
        }
    }

    /// The bar, driven through real frames and clicked through egui's own
    /// hit-testing.
    struct Bar {
        chrome: Chrome,
        session: Session,
    }

    impl Bar {
        fn over(session: Session) -> Self {
            let mut bar = Bar {
                chrome: Chrome::new(screen().geom()),
                session,
            };
            // In the app's own colours, always: the bar is drawn on the
            // theme's surfaces, and a question about ink asked against
            // egui's stock palette is a question about the wrong app. The
            // document name was invisible for a whole pass because of it.
            bar.chrome.ctx().set_visuals(app_visuals());
            bar.settle();
            bar
        }

        fn new() -> Self {
            Bar::over(Session::new())
        }

        fn settle(&mut self) {
            let Self { chrome, session } = self;
            chrome.settle(|ui| session.frame(ui));
        }

        fn rect(&self) -> Rect {
            crate::shell::berth_rect(self.chrome.ctx(), glass::Berth::TopBar)
                .expect("the top bar never laid out")
                .geom()
        }

        fn click_at(&mut self, at: Pos2) {
            let Self { chrome, session } = self;
            chrome.click_at(at, |ui| session.frame(ui));
        }

        fn click_on(&mut self, label: &str) {
            let Self { chrome, session } = self;
            chrome.click_on(label, |ui| session.frame(ui));
        }

        fn type_text(&mut self, text: &str) {
            let Self { chrome, session } = self;
            chrome.type_text(text, |ui| session.frame(ui));
        }

        fn press(&mut self, key: egui::Key) {
            let Self { chrome, session } = self;
            chrome.press(key, |ui| session.frame(ui));
        }

        /// Every verb a click at each 5px step across the bar dispatched —
        /// finer than the narrowest control on it.
        fn scan(&mut self) -> Vec<&'static str> {
            let bar = self.rect();
            let mut x = bar.left();
            while x <= bar.right() {
                self.click_at(Pos2::new(x, bar.center().y));
                x += 5.0;
            }
            self.session
                .fired
                .iter()
                .map(crate::tools::commands::act_name)
                .collect()
        }

        /// Every word the bar says with the pointer resting on each 5px step
        /// across it — which is where a tooltip lives.
        fn hovers(&mut self) -> Vec<String> {
            let bar = self.rect();
            let mut said = Vec::new();
            let mut x = bar.left();
            while x <= bar.right() {
                let Self { chrome, session } = self;
                chrome.hover_at(Pos2::new(x, bar.center().y), |ui| session.frame(ui));
                said.extend(self.chrome.texts().iter().map(|t| (*t).to_owned()));
                x += 5.0;
            }
            said
        }

        /// The document menu is the bar's left end.
        fn open_the_menu(&mut self) {
            let at = self.rect();
            self.click_at(Pos2::new(at.left() + glass::TAP * 0.5, at.center().y));
        }

        /// Two clicks on the document's own segment, which follows the dot.
        fn double_click_the_name(&mut self) {
            let at = self.name_rect();
            let Self { chrome, session } = self;
            chrome.double_click_at(at.center(), |ui| session.frame(ui));
        }

        /// One click on it, and the frames after it: the second click's
        /// window has to run out before a single click is one.
        fn click_the_name(&mut self) {
            let at = self.name_rect();
            self.click_at(at.center());
        }

        fn name_rect(&self) -> Rect {
            self.chrome
                .rect(DOCUMENT)
                .expect("the bar never drew the document's name")
        }

        fn hover_at(&mut self, at: Pos2) {
            let Self { chrome, session } = self;
            chrome.hover_at(at, |ui| session.frame(ui));
        }

        /// Where each of `names` landed on the last frame.
        fn trail(&self, names: &[&str]) -> Vec<Rect> {
            names
                .iter()
                .map(|name| {
                    self.chrome
                        .rect(name)
                        .unwrap_or_else(|| panic!("the breadcrumb never drew {name}"))
                })
                .collect()
        }

        /// Whether the last frame painted a plate *of `at`'s own size*. The
        /// bar's own fill covers every segment on it, so a plate counts only
        /// when it is no bigger than the thing it sits under.
        fn lit(&self, at: Rect) -> bool {
            self.chrome.fills().iter().any(|(drawn, _)| {
                drawn.contains_rect(at) && drawn.height() <= CRUMB_HEIGHT + PLATE_SLACK
            })
        }

        /// Every verb the bar has asked for so far, for a failure to print.
        fn verbs(&self) -> Vec<&'static str> {
            self.session
                .fired
                .iter()
                .map(crate::tools::commands::act_name)
                .collect()
        }
    }

    /// Item 1: *"the last segment in the breadcrumb is not clickable. It's a
    /// label that indicates where we are in the hierarchy."* It answers no
    /// pointer, so it never lights up; an ancestor still does, which is what
    /// keeps the difference legible.
    #[test]
    fn the_level_the_canvas_stands_on_is_a_label_and_its_ancestors_are_not() {
        let mut bar = Bar::over(Session::nested(2));
        let trail = bar.trail(&["Level 1", "Level 2"]);
        let (ancestor, leaf) = (trail[0], trail[1]);
        assert!(
            !bar.lit(leaf) && !bar.lit(ancestor),
            "precondition: an untouched breadcrumb lights nothing up",
        );

        bar.hover_at(leaf.center());
        assert!(
            !bar.lit(leaf),
            "the level the canvas is standing on lit up under the pointer",
        );

        bar.hover_at(ancestor.center());
        assert!(
            bar.lit(ancestor),
            "an ancestor gives no sign that it can be pressed",
        );
    }

    /// Item 2: *"The shifting of text layout as you hover over the breadcrumb
    /// elements is disturbing."* Every segment keeps its box in every state,
    /// so the trail is still where it was when the pointer arrives.
    #[test]
    fn nothing_on_the_breadcrumb_moves_when_the_pointer_crosses_it() {
        let names = [DOCUMENT, "Level 1", "Level 2"];
        let mut bar = Bar::over(Session::nested(2));
        let at_rest = bar.trail(&names);
        for hovered in &at_rest {
            bar.hover_at(hovered.center());
            assert_eq!(
                bar.trail(&names),
                at_rest,
                "the trail moved with the pointer over {hovered:?}",
            );
        }
    }

    /// One click on the document is an ordinary breadcrumb click, landing
    /// once egui's own double-click window has run out without a second
    /// one arriving.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn one_click_on_the_document_rises_to_the_root() {
        let mut bar = Bar::over(Session::nested(2));
        bar.click_the_name();
        let rose =
            bar.session.fired.iter().any(
                |act| matches!(act, Act::Edit(Action::GoToPath(to)) if to.segments().is_empty()),
            );
        assert!(
            rose,
            "the document's segment did not rise: {:?}",
            bar.verbs()
        );
    }

    /// A double click renames, and the rise its first click armed is never
    /// taken — a scope pop is a view entry on the one undo stack, so a rise
    /// taken and absorbed would still be a rise the user has to take back
    /// by hand.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn a_double_click_renames_the_document_without_moving_the_canvas() {
        let mut bar = Bar::over(Session::nested(2));
        bar.double_click_the_name();
        assert_eq!(
            bar.session.draft, DOCUMENT,
            "the box did not open on the document's own name",
        );
        assert!(
            bar.session.fired.is_empty(),
            "the rename navigated on its way to the box: {:?}",
            bar.verbs(),
        );
    }

    /// The visuals the editor actually draws in.
    fn app_visuals() -> egui::Visuals {
        crate::canvas::convert::visuals(
            &blockworx_paint::Scheme::default().palette(blockworx_paint::Luminance::Dark),
        )
    }

    /// How bright a colour reads, the way a reader's eye weights it.
    fn luminance(color: egui::Color32) -> f32 {
        0.299 * f32::from(color.r()) + 0.587 * f32::from(color.g()) + 0.114 * f32::from(color.b())
    }

    /// The document's name has to be *readable*, which is not the same claim
    /// as "it is painted".
    ///
    /// `Visuals::strong_text_color` reads `widgets.active.fg_stroke`, and
    /// this palette sets that to its darkest base — the ink for a word on an
    /// accent-filled control. A name drawn with it sits at luminance 32 on a
    /// bar of 25, which is how a whole pass shipped with the document's name
    /// invisible on the real desktop and every test green: egui's stock dark
    /// visuals make the same call come out white.
    #[test]
    fn the_document_name_is_painted_in_ink_that_stands_off_the_bar() {
        let visuals = app_visuals();
        let bar = Bar::new();
        let ink = bar
            .chrome
            .format_of(DOCUMENT)
            .expect("the bar drew no document name")
            .color;
        assert_eq!(
            ink,
            glass::full_ink(&visuals),
            "the name is not painted in the shell's full-strength ink",
        );
        assert_ne!(
            ink,
            visuals.strong_text_color(),
            "the name went back to egui's strong text colour",
        );
        let against = luminance(visuals.window_fill);
        assert!(
            luminance(ink) - against > READABLE,
            "the name reads at {} against a bar at {against}",
            luminance(ink),
        );
    }

    /// The muted segments have to clear the same bar, by less. An ancestor
    /// the eye cannot find is a control nobody presses.
    #[test]
    fn a_quieted_segment_still_stands_off_the_bar() {
        let visuals = app_visuals();
        let bar = Bar::over(Session::nested(2));
        let ink = bar
            .chrome
            .format_of("Level 1")
            .expect("the bar drew no ancestor segment")
            .color;
        let against = luminance(visuals.window_fill);
        assert!(
            luminance(ink) - against > QUIET,
            "an ancestor reads at {} against a bar at {against}",
            luminance(ink),
        );
        assert!(
            luminance(ink) < luminance(glass::full_ink(&visuals)),
            "an ancestor is as loud as where the canvas is standing",
        );
    }

    /// How far the shell's ink must stand off its own surface, in the
    /// luminance the review measured this regression in: full-strength text
    /// clears it comfortably, and a quieted segment by enough to be found.
    const READABLE: f32 = 100.0;
    const QUIET: f32 = 40.0;

    /// Everything the right run offers, clicked through egui's own
    /// hit-testing: a control that lays out but dispatches nothing fails here.
    #[test]
    fn the_bar_undoes_redoes_fits_and_opens_the_navigator() {
        let mut bar = Bar::new();
        let fired = bar.scan();
        for verb in ["Undo", "Redo", "ResetView"] {
            assert!(
                fired.contains(&verb),
                "the bar never dispatched {verb}: {fired:?}",
            );
        }
        assert!(bar.session.browses > 0, "Browse never toggled");
    }

    /// The right run's order: *"After Undo/Redo | <Go Up> <Fit> <Panel>."*
    /// Dead at the document root, live one level in, and what it dispatches
    /// is the one verb the breadcrumb's ancestry serves.
    #[test]
    fn go_up_is_dead_at_the_root_and_rises_one_level_from_inside_a_block() {
        let from_root = Bar::new().scan();
        assert!(
            !from_root.contains(&"GoUp"),
            "the root offered somewhere to rise to: {from_root:?}",
        );

        let mut inside = Bar::over(Session::nested(2));
        let fired = inside.scan();
        assert!(
            fired.contains(&"GoUp"),
            "a nested scope will not rise: {fired:?}",
        );
        // The breadcrumb's parent segment rises too, and it is scanned
        // first, so the *button* is the last Go Up on the sweep.
        let first = |verb: &str| fired.iter().position(|f| *f == verb);
        let button = fired.iter().rposition(|f| *f == "GoUp");
        assert!(
            first("Redo") < button && button < first("ResetView"),
            "the right run is not in the order the user gave it: {fired:?}",
        );
    }

    /// Redo keeps its place and draws dead, exactly as undo does — and a dead
    /// button still says what it would have done.
    #[test]
    fn undo_and_redo_keep_their_place_and_their_words_when_their_stacks_empty() {
        let mut bar = Bar::over(Session {
            history: History::empty(),
            steps: Consequences::default(),
            ..Session::new()
        });
        let said = bar.hovers();
        for verb in ["Undo", "Redo"] {
            assert!(
                said.iter()
                    .any(|word| word.starts_with(verb) && word.contains("nothing to take back")),
                "an empty stack hid {verb} instead of disabling it: {said:?}",
            );
        }
        let fired = bar.scan();
        assert!(
            !fired.contains(&"Undo") && !fired.contains(&"Redo"),
            "an empty stack's buttons dispatched anyway: {fired:?}",
        );
        assert!(
            fired.contains(&"ResetView"),
            "precondition: the scan reaches the run's live half: {fired:?}",
        );
    }

    /// The undo tooltip must name the target *and* what undoing it costs —
    /// and the two kinds of entry cost materially different things.
    #[test]
    fn the_undo_hover_names_the_target_and_which_of_the_two_kinds_it_is() {
        use crate::history::Offered;
        let edit = consequence(
            Direction::Back,
            Some(&of("Add block Filter", Kind::Doc)),
            Offered::Yes,
            Viewing::Head,
        );
        assert_eq!(edit, "Undo Add block Filter \u{2014} authors a rev");

        let camera = consequence(
            Direction::Back,
            Some(&of("zoom to fit", Kind::View)),
            Offered::Yes,
            Viewing::Head,
        );
        assert_eq!(camera, "Undo zoom to fit \u{2014} view only, no rev");

        assert!(
            consequence(Direction::Back, None, Offered::Yes, Viewing::Head)
                .contains("nothing to take back"),
            "an empty stack's button says so rather than promising a rev",
        );
        // The mockup's own words for the one case where the button is dead
        // for a reason the user can act on.
        assert_eq!(
            consequence(
                Direction::Back,
                Some(&of("Add block Filter", Kind::Doc)),
                Offered::No,
                Viewing::Past(rev(AT)),
            ),
            "Undo \u{2014} return to current first",
        );
    }

    /// The hover is rendered, not merely computed: resting on the bar names
    /// the edit one press would take back.
    #[test]
    fn hovering_the_bar_names_the_edit_undo_would_take_back() {
        let mut bar = Bar::new();
        assert!(
            !bar.chrome.shows(NEWEST),
            "precondition: the bar names no commit until a button is hovered",
        );
        let said = bar.hovers();
        assert!(
            said.iter().any(|word| word.contains(NEWEST)),
            "no button on the bar names the edit undo would take back: {said:?}",
        );
    }

    /// Under the lens undo still serves a *view* entry, which costs the log
    /// nothing — and the withheld half says why.
    #[test]
    fn under_the_lens_a_view_entry_is_still_undoable_and_a_doc_entry_says_why_not() {
        let mut view = Bar::over(Session {
            history: History::view(),
            kind: Kind::View,
            ..Session::new().under_the_lens()
        });
        let fired = view.scan();
        assert!(
            fired.contains(&"Undo") && fired.contains(&"Redo"),
            "the lens took the camera history with it: {fired:?}",
        );

        let mut doc = Bar::over(Session::new().under_the_lens());
        let said = doc.hovers();
        assert!(
            said.iter()
                .any(|word| word.contains("return to current first")),
            "a withheld undo does not say what would free it: {said:?}",
        );
        let fired = doc.scan();
        assert!(
            !fired.contains(&"Undo") && !fired.contains(&"Redo"),
            "the bar wrote from a session that may not: {fired:?}",
        );
        assert!(
            fired.contains(&"ResetView"),
            "the lens took the view controls with it: {fired:?}",
        );
    }

    /// The centre: the rev and its age, the stepper that walks either way,
    /// and Return. Clicked through egui's own hit-testing, so a control that
    /// lays out but dispatches nothing fails here.
    #[test]
    fn the_mode_names_the_rev_and_steps_and_returns() {
        assert_eq!(
            headline(rev(23), "3 hours ago"),
            "Rev 23 \u{00b7} 3 hours ago"
        );
        assert_eq!(
            headline(rev(23), "   "),
            "Rev 23",
            "a session with no clock is not made to guess at one",
        );

        let mut bar = Bar::over(Session::new().under_the_lens());
        assert!(
            bar.chrome.shows("Rev 2 \u{00b7} 3 hours ago"),
            "the centre does not name the rev on the canvas: {:?}",
            bar.chrome.texts(),
        );
        let fired = bar.scan();
        for verb in ["ViewRev", "ViewHead"] {
            assert!(
                fired.contains(&verb),
                "the centre never dispatched {verb}: {fired:?}",
            );
        }
    }

    /// The states, as the user reads them: green (all is good), red (no
    /// editing allowed), grey (nothing behind it). A colour and a set of
    /// words each — because the colours are palette slots whose hue is the
    /// scheme's to choose, a mark alone would say nothing.
    #[test]
    fn the_dot_tells_its_states_apart_in_colour_and_in_words() {
        let theme = Theme::default();
        let states = [
            Liveness::Recorded,
            Liveness::ReadOnly(Locked::Lens),
            Liveness::ReadOnly(Locked::Container),
            Liveness::Scratch,
        ];
        let colours: std::collections::HashSet<[u8; 4]> = states
            .iter()
            .map(|state| theme.resolve(dot(*state).0).to_array())
            .collect();
        assert_eq!(
            colours.len(),
            3,
            "the read-only pair share a colour; the other two must not",
        );
        let words: std::collections::HashSet<&str> =
            states.iter().map(|state| dot(*state).1).collect();
        assert_eq!(words.len(), states.len(), "two states say the same thing");
        assert!(
            words.iter().all(|said| !said.is_empty()),
            "a state says nothing at all: {words:?}",
        );

        // The one resolver, over every input that reaches it.
        assert_eq!(
            Liveness::of(Viewing::Head, Writability::Writable, Attachment::Scratch,),
            Liveness::Scratch,
            "a session with nothing behind it is not the recorded state",
        );
        assert_eq!(
            Liveness::of(Viewing::Head, Writability::Writable, Attachment::Attached,),
            Liveness::Recorded,
        );
        assert_eq!(
            Liveness::of(Viewing::Head, Writability::ReadOnly, Attachment::Attached,),
            Liveness::ReadOnly(Locked::Container),
        );
        // The lens outranks the container: "no editing allowed" is what it
        // means, whatever may be written behind it.
        assert_eq!(
            Liveness::of(
                Viewing::Past(rev(AT)),
                Writability::Writable,
                Attachment::Attached,
            ),
            Liveness::ReadOnly(Locked::Lens),
        );
    }

    /// The words are rendered, not merely computed: resting on the dot in
    /// any state names that state.
    #[test]
    fn the_dot_says_which_state_it_is_in_when_the_pointer_rests_on_it() {
        for (state, session) in [
            (Liveness::Recorded, Session::new()),
            (
                Liveness::Scratch,
                Session {
                    attachment: Attachment::Scratch,
                    ..Session::new()
                },
            ),
            (
                Liveness::ReadOnly(Locked::Lens),
                Session::new().under_the_lens(),
            ),
        ] {
            let mut bar = Bar::over(session);
            let said = bar.hovers();
            let wanted = dot(state).1;
            assert!(
                said.iter().any(|word| word == wanted),
                "the dot never said {wanted:?} in {state:?}: {said:?}",
            );
        }
    }

    /// The breadcrumb is rooted at the document, ancestors navigate, and the
    /// level the canvas is standing on takes no click at all.
    #[test]
    fn the_breadcrumb_is_rooted_at_the_document_and_its_ancestors_navigate() {
        let mut bar = Bar::over(Session::nested(3));
        assert!(
            bar.chrome.shows(DOCUMENT),
            "the breadcrumb is not rooted at the document: {:?}",
            bar.chrome.texts(),
        );
        for level in ["Level 1", "Level 2", "Level 3"] {
            assert!(
                bar.chrome.shows(level),
                "the breadcrumb lost {level}: {:?}",
                bar.chrome.texts(),
            );
        }
        let fired = bar.scan();
        assert!(
            fired.contains(&"GoUp"),
            "the parent segment did not go up: {fired:?}",
        );
        let jumped: Vec<usize> = bar
            .session
            .fired
            .iter()
            .filter_map(|a| match a {
                Act::Edit(Action::GoToPath(to)) => Some(to.segments().len()),
                _ => None,
            })
            .collect();
        assert!(
            jumped.contains(&0) && jumped.contains(&1),
            "the document and the grandparent are not reachable: {jumped:?}",
        );
        assert!(
            !jumped.contains(&3),
            "the level the canvas is on answered a click: {jumped:?}",
        );
    }

    /// The middle collapse, at the depth that forces it: the rule itself is
    /// the kernel's, and what is checked here is that the bar draws what it
    /// answers — both ends still on the strip.
    #[test]
    fn a_deep_path_collapses_from_the_middle_and_keeps_its_ends() {
        let bar = Bar::over(Session::nested(5));
        let said = bar.chrome.texts();
        assert!(
            said.contains(&DOCUMENT) && said.contains(&"Level 5"),
            "the collapse hid one of the ends: {said:?}",
        );
        assert!(
            !said.contains(&"Level 2"),
            "the middle did not collapse: {said:?}",
        );
        assert!(
            said.contains(&ELLIPSIS),
            "the collapse says nothing about what it hid: {said:?}",
        );
    }

    /// A segment wider than the cap truncates rather than pushing the bar's
    /// centre aside.
    #[test]
    fn a_long_segment_is_capped_rather_than_allowed_to_push_the_bar_around() {
        let mut session = Session::nested(1);
        session.names = vec!["A block with a preposterously long name on it".to_owned()];
        let bar = Bar::over(session);
        let long = bar
            .chrome
            .rect("A block with a preposterously long name on it")
            .expect("the long segment never drew");
        let short = bar
            .chrome
            .rect(DOCUMENT)
            .expect("the document's own segment never drew");
        assert!(
            short.width() < CRUMB_WIDTH,
            "precondition: a short segment is not capped: {short:?}",
        );
        assert!(
            long.width() <= CRUMB_WIDTH,
            "a long segment ran to {} points, past the {CRUMB_WIDTH} cap",
            long.width(),
        );
    }

    /// One menu carries what the document bar's File menu, Help menu and
    /// preferences gear carried — clicked through a real frame, so a section
    /// that lays out but opens onto nothing fails here.
    #[test]
    fn the_menu_reaches_every_door_the_document_chip_had() {
        let mut bar = Bar::new();
        bar.open_the_menu();
        #[cfg(not(target_arch = "wasm32"))]
        for entry in ["New diagram", "Open diagram\u{2026}"] {
            assert!(
                bar.chrome.shows(entry),
                "the bar's menu offers no {entry:?}: {:?}",
                bar.chrome.texts(),
            );
        }
        for entry in ["Import\u{2026}", "Export", "Help", "Preferences"] {
            assert!(
                bar.chrome.shows(entry),
                "the bar's menu lost {entry:?}: {:?}",
                bar.chrome.texts(),
            );
        }
        bar.click_on("Export");
        for format in crate::export::ExportScope::View.formats() {
            assert!(
                bar.chrome.shows(format.label()),
                "the view's Export menu is missing {}: {:?}",
                format.label(),
                bar.chrome.texts(),
            );
        }
    }

    /// The user's own words: *"'open Json file' is unneeded detail for the
    /// end user... the JSON file is not a self contained archive of the
    /// document (it does not, for example, include the assets). So it can't
    /// really be 'loaded' as a document in an unsaved session."* One door
    /// into the menu, and it asks for a diagram.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn the_menu_opens_one_thing_and_it_is_a_diagram() {
        let mut bar = Bar::new();
        bar.open_the_menu();
        assert!(
            bar.chrome.shows("Open diagram\u{2026}"),
            "the menu lost the one way in: {:?}",
            bar.chrome.texts(),
        );
        for gone in ["JSON", "Open document", "shared diagram", "Share\u{2026}"] {
            assert!(
                !bar.chrome.says(gone),
                "the menu still offers {gone:?}: {:?}",
                bar.chrome.texts(),
            );
        }
    }

    /// Help and preferences are cascading submenus rather than icons of their
    /// own, and they still open onto their entries.
    #[test]
    fn help_and_preferences_keep_their_entries() {
        for (menu, entry) in [("Help", "GitHub"), ("Preferences", "Theme")] {
            let mut bar = Bar::new();
            bar.open_the_menu();
            bar.click_on(menu);
            assert!(
                bar.chrome.shows(entry),
                "the {menu} submenu does not open onto {entry:?}: {:?}",
                bar.chrome.texts(),
            );
        }
    }

    /// A read-only session still lists Import — the menu keeps its shape —
    /// but the entry is dead, because the registry withheld the command
    /// rather than the bar forming a second opinion about writability.
    #[test]
    fn import_is_listed_in_a_read_only_session_and_does_nothing() {
        let mut writable = Bar::new();
        writable.open_the_menu();
        writable.click_on("Import\u{2026}");
        assert!(
            matches!(
                writable.session.fired.last(),
                Some(Act::Effect(Effect::Import))
            ),
            "a writable session's Import dispatched something else",
        );

        let mut read_only = Bar::over(Session {
            writability: Writability::ReadOnly,
            ..Session::new()
        });
        read_only.open_the_menu();
        assert!(
            read_only.chrome.shows("Import\u{2026}"),
            "a read-only session hid Import instead of disabling it",
        );
        read_only.click_on("Import\u{2026}");
        assert!(
            read_only.session.fired.is_empty(),
            "a read-only session's Import dispatched",
        );
    }

    /// Nothing on the bar implies a save — no word, and no dot promising one.
    /// The one "Save as…" the editor keeps lives inside the menu, which is
    /// closed here.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn nothing_on_the_bar_says_saved() {
        let mut bar = Bar::new();
        for said in bar.chrome.texts() {
            assert!(
                !said.to_lowercase().contains("sav"),
                "the top bar says {said:?}",
            );
        }
        bar.open_the_menu();
        // Nothing here offers to refresh the projection either.
        assert!(
            !bar.chrome.says("document.json"),
            "the menu still offers to refresh the projection: {:?}",
            bar.chrome.texts(),
        );
    }

    /// Save-as is contextual: the *same* entry, pressed under the lens, asks
    /// for the log through the rev on the canvas.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn save_as_asks_for_the_rev_on_the_canvas() {
        use crate::file::{FileRequest, SaveScope};
        let mut bar = Bar::new();
        bar.open_the_menu();
        bar.click_on("Save as\u{2026}");
        assert!(
            matches!(
                bar.session.fired.last(),
                Some(Act::Effect(Effect::PickFile(FileRequest::SaveAsContainer(
                    SaveScope::Whole
                )))),
            ),
            "at the present, Save-as asked for something other than the whole document",
        );

        let mut under = Bar::over(Session::new().under_the_lens());
        under.open_the_menu();
        under.click_on("Save as\u{2026}");
        assert!(
            matches!(
                under.session.fired.last(),
                Some(Act::Effect(Effect::PickFile(FileRequest::SaveAsContainer(
                    SaveScope::Through(at)
                )))) if *at == rev(AT),
            ),
            "under the lens, Save-as did not ask for the rev on the canvas",
        );
    }

    /// On the segment the document owns: the box opens on the document's own
    /// name, takes what is typed, and dispatches exactly that.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn double_clicking_the_name_renames_the_document_in_place() {
        let mut bar = Bar::new();
        assert!(
            bar.chrome.shows(DOCUMENT),
            "precondition: the bar draws the name: {:?}",
            bar.chrome.texts(),
        );
        bar.double_click_the_name();
        assert_eq!(
            bar.session.draft, DOCUMENT,
            "the box did not open on the document's own name",
        );
        bar.type_text("2");
        assert_ne!(bar.session.draft, DOCUMENT, "typing never reached the box");
        let typed = bar.session.draft.clone();

        bar.press(egui::Key::Enter);
        let renamed = bar.session.fired.iter().find_map(|act| match act {
            Act::Effect(Effect::RenameDocument(to)) => Some(to.clone()),
            _ => None,
        });
        assert_eq!(
            renamed.as_deref(),
            Some(typed.as_str()),
            "what was typed is not what was sent",
        );
    }

    /// One door, not two: the name is the only way to rename.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn the_menu_no_longer_offers_a_second_way_to_rename() {
        let mut bar = Bar::new();
        bar.open_the_menu();
        assert!(
            !bar.chrome.says("Rename"),
            "the menu still offers its own rename: {:?}",
            bar.chrome.texts(),
        );
    }

    /// Guarded as artwork rather than as file names: the document menu wears
    /// the mockup's own three lines with a short last one, and the stepper
    /// wears its up and down arrows, pointing the way the mockup points them.
    #[test]
    fn the_bar_wears_the_mockups_own_glyphs() {
        let menu = include_str!("../../icons/icon-menu.svg");
        for line in [r#"d="M4 7h16""#, r#"d="M4 12h16""#, r#"d="M4 17h10""#] {
            assert!(
                menu.contains(line),
                "the document menu is not the mockup's: {menu}",
            );
        }
        let older = include_str!("../../icons/icon-step-older.svg");
        let newer = include_str!("../../icons/icon-step-newer.svg");
        // `#stepold` draws down into the log and `#stepnew` up out of it.
        assert!(older.contains(r#"points="7 14 12 19 17 14""#), "{older}");
        assert!(newer.contains(r#"points="7 10 12 5 17 10""#), "{newer}");
        for icon in [menu, older, newer] {
            assert!(icon.contains(r#"viewBox="0 0 24 24""#), "{icon}");
            assert!(icon.contains(r#"stroke-width="2""#), "{icon}");
            assert!(icon.contains(r#"fill="none""#), "{icon}");
        }
    }

    /// The stepper's words outlive its arrows: an arrow says *a* direction,
    /// and which end of the log that is stays in the tooltip.
    #[test]
    fn the_stepper_says_which_way_each_arrow_goes() {
        let mut bar = Bar::over(Session::new().under_the_lens());
        let said = bar.hovers();
        for way in ["Older rev", "Newer rev"] {
            assert!(
                said.iter().any(|word| word == way),
                "the stepper does not say {way}: {said:?}",
            );
        }
    }

    /// Never tools: the rail carries them, and the bar carries none.
    #[test]
    fn the_bar_holds_no_tools() {
        let mut bar = Bar::new();
        bar.open_the_menu();
        for tool in crate::tools::names::band_tools() {
            assert!(
                !bar.chrome.shows(tool.label()),
                "{tool:?} strayed into the top bar",
            );
        }
    }
}