blockworx_tools/

commands.rs

//! The command registry: every invocable operation as a [`Command`] — a stable
//! [`CommandId`], a user-facing label, and the [`Act`] invoking it performs —
//! computed against the current selection and mode by [`CommandSet::available`].
//! The overlays render the set instead of re-deriving availability, so "what
//! can the user do right now" is encoded exactly once; the planned command
//! palette, keyboard shortcuts, and the script `command` step consume the same
//! set.
//!
//! The registry answers permission and target, never flow: an [`Act::Effect`]
//! says which picker or dialog the *shell* is to run and on what, and nothing
//! about the steps of it passes through the core.
//!
//! Toggle pairs (lock/unlock, hide/show tags) are distinct ids: the direction
//! that doesn't apply is simply absent, so a consumer can never invoke the
//! wrong half.

use std::borrow::Cow;

use blockworx_paint::{Chord, Key, Modifiers};
use blockworx_store::doc::{Saving, Viewing, Writability};
use blockworx_store::storage::DocumentRef;

use crate::{
    block_edit::{EditTarget, tool_for_target},
    edit::naming::{Authoring, InterfaceLock, TagVisibility},
    names::{ToolName, band_tools},
    shape::ShapeId,
    tool::{Action, Deletable, RoleTarget, Tool, ToolTrait, Transition},
    widget::drawing::Drawing,
};
use blockworx_doc::{
    id::{BlockId, PinId},
    values::PinDir,
};

/// The export formats offered in the toolbar.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum ExportFormat {
    Svg,
    Png,
    Pdf,
}

/// Which surface a format list is offered on. The whole view exports the
/// document, so it can carry the scope hierarchy PDF is made of; a selection
/// is an excerpt of shapes with no hierarchy to navigate, so PDF is not
/// offered there. The two lists live here rather than at the menus, so the
/// registry and the menus cannot offer different formats.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum ExportScope {
    View,
    Selection,
}

impl ExportScope {
    /// Menu order of the formats this surface offers.
    pub fn formats(self) -> &'static [ExportFormat] {
        match self {
            ExportScope::View => &[ExportFormat::Svg, ExportFormat::Png, ExportFormat::Pdf],
            ExportScope::Selection => &[ExportFormat::Svg, ExportFormat::Png],
        }
    }

    /// The format whose command renders this surface's submenu button; the
    /// rest are reached inside the menu.
    pub fn leading_format(self) -> ExportFormat {
        self.formats()[0]
    }
}

impl ExportFormat {
    /// Menu-entry label.
    pub fn label(self) -> &'static str {
        match self {
            ExportFormat::Svg => "SVG",
            ExportFormat::Png => "PNG",
            ExportFormat::Pdf => "PDF",
        }
    }

    pub fn extension(self) -> &'static str {
        match self {
            ExportFormat::Svg => "svg",
            ExportFormat::Png => "png",
            ExportFormat::Pdf => "pdf",
        }
    }
}

/// What the undo/redo controls stand over this frame: which entry each would
/// take, and of which of the two kinds. `None` is an empty stack — the button
/// draws dead rather than vanishing.
///
/// The kind is load-bearing, not decoration: a `view` entry writes nothing,
/// so it survives the read-only lens that withholds every authoring
/// command.
#[derive(Clone, Copy, Default, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub struct History {
    pub undo: Option<crate::history::Kind>,
    pub redo: Option<crate::history::Kind>,
}

/// The three stacks the suites above this crate build a [`CommandContext`]
/// with. `cfg(test)` stops reaching across a crate line, so they are behind
/// the same feature [`action_name`] is.
#[cfg(any(test, feature = "test-support"))]
impl History {
    /// Nothing to take back either way.
    pub fn empty() -> Self {
        Self::default()
    }

    /// An edit either way — the stack a session that has been editing holds.
    pub fn doc() -> Self {
        Self {
            undo: Some(crate::history::Kind::Doc),
            redo: Some(crate::history::Kind::Doc),
        }
    }

    /// A camera move either way, which costs the log nothing.
    pub fn view() -> Self {
        Self {
            undo: Some(crate::history::Kind::View),
            redo: Some(crate::history::Kind::View),
        }
    }
}

/// Stable identity of one invocable operation.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum CommandId {
    /// Arm a toolbar tool.
    Arm(ToolName),
    Undo,
    Redo,
    Copy,
    Cut,
    /// Export the current selection as a standalone diagram.
    ExportSelection(ExportFormat),
    HideTags,
    ShowTags,
    /// Open the in-place editor on the selection's primary label — a shape's
    /// title, or a pin/port's name.
    Rename,
    /// Open the in-place editor on a block's type label.
    RenameType,
    /// Open the in-place editor on a pin/port's type label.
    Retype,
    /// Open the in-place editor on a pin/port's tag.
    RenameTag,
    /// Open a text box's in-place editor.
    EditText,
    FlipLr,
    FlipUd,
    /// Open the pin-type (I/O) picker for the selected pins.
    PinType,
    /// Open the accent-color picker for the selection.
    Accent,
    Reroute,
    /// Toggle the author's diagnostic overlay: what the selection raises, the
    /// bound the regional router heals it in, and the lattice there. Dev
    /// tooling, reachable only by name.
    ToggleDiagnostic,
    /// Toggle the frame-rate readout: frames in the last second, and what the
    /// last frame spent in the kernel and on the canvas. Dev tooling,
    /// reachable only by name.
    ToggleFrameRate,
    /// One accent value, by name — the picker's cells as commands.
    SetAccent(Option<u8>),
    /// One I/O direction, by name.
    SetPinDir(PinDir),
    AddRouteLabel,
    ExpandBlock,
    GoUp,
    ZoomIn,
    ZoomOut,
    /// Frame the whole level in view — the double-click gesture, by name.
    FitView,
    Lock,
    Unlock,
    AddIcon,
    /// Pick artwork to place as an image of its own — the rail's image cell,
    /// which arms no tool because there is none to arm.
    AddImage,
    RerouteBlock,
    Delete,
    /// Export the current view.
    Export(ExportFormat),
    Import,
    /// Write the log, through the rev on the canvas, somewhere of its own.
    Save,
    /// Open the front end's search — the ⌘K palette of `docs/cad-ui-spec.md`
    /// §9. It draws no control of its own: the chord and the palette are its
    /// two doors, and which of them is open is the shell's own state.
    Search,
    /// Move the selection one grid cell — or a pin group one slot — the way
    /// an arrow key points.
    Nudge(Heading),
}

/// The way an arrow key points.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Heading {
    Left,
    Right,
    Up,
    Down,
}

impl Heading {
    const ALL: [Heading; 4] = [Heading::Left, Heading::Right, Heading::Up, Heading::Down];
    /// A pin group slides along its edge, so only these move one.
    const ALONG_AN_EDGE: [Heading; 2] = [Heading::Up, Heading::Down];

    fn nudge(self) -> Action {
        let (dx, dy) = match self {
            Heading::Left => (-1, 0),
            Heading::Right => (1, 0),
            Heading::Up => (0, -1),
            Heading::Down => (0, 1),
        };
        Action::Nudge { dx, dy }
    }

    fn label(self) -> &'static str {
        match self {
            Heading::Left => "Nudge left",
            Heading::Right => "Nudge right",
            Heading::Up => "Nudge up",
            Heading::Down => "Nudge down",
        }
    }
}

impl CommandId {
    /// The stable spelling consumers type: the palette matches against it, and
    /// the planned shortcut table names commands by it.
    pub fn name(self) -> &'static str {
        match self {
            // Total despite non-toolbar ToolNames existing: the registry arms
            // only toolbar tools, all of which carry a command spelling.
            CommandId::Arm(tool) => tool.command_name().unwrap_or("select"),
            CommandId::Undo => "undo",
            CommandId::Redo => "redo",
            CommandId::Copy => "copy",
            CommandId::Cut => "cut",
            CommandId::ExportSelection(format) => match format {
                ExportFormat::Svg => "export-selection-svg",
                ExportFormat::Png => "export-selection-png",
                ExportFormat::Pdf => "export-selection-pdf",
            },
            CommandId::HideTags => "hide-tags",
            CommandId::ShowTags => "show-tags",
            CommandId::Rename => "rename",
            CommandId::RenameType => "rename-type",
            CommandId::Retype => "retype",
            CommandId::RenameTag => "rename-tag",
            CommandId::EditText => "edit-text",
            CommandId::FlipLr => "flip-lr",
            CommandId::FlipUd => "flip-ud",
            CommandId::PinType => "io",
            CommandId::Accent => "accent",
            CommandId::Reroute => "reroute",
            CommandId::ToggleDiagnostic => "diagnostic",
            CommandId::ToggleFrameRate => "frame-rate",
            CommandId::AddRouteLabel => "add-label",
            CommandId::ExpandBlock => "expand",
            CommandId::GoUp => "up",
            CommandId::ZoomIn => "zoom-in",
            CommandId::ZoomOut => "zoom-out",
            CommandId::FitView => "fit",
            CommandId::Lock => "lock",
            CommandId::Unlock => "unlock",
            CommandId::AddIcon => "add-icon",
            CommandId::AddImage => "add-image",
            CommandId::RerouteBlock => "reroute-block",
            CommandId::Delete => "delete",
            CommandId::Export(format) => match format {
                ExportFormat::Svg => "export-svg",
                ExportFormat::Png => "export-png",
                ExportFormat::Pdf => "export-pdf",
            },
            CommandId::Import => "import",
            CommandId::Save => "save",
            CommandId::Search => "search",
            CommandId::Nudge(Heading::Left) => "nudge-left",
            CommandId::Nudge(Heading::Right) => "nudge-right",
            CommandId::Nudge(Heading::Up) => "nudge-up",
            CommandId::Nudge(Heading::Down) => "nudge-down",
            CommandId::SetAccent(None) => "accent-none",
            CommandId::SetAccent(Some(0)) => "accent-0",
            CommandId::SetAccent(Some(1)) => "accent-1",
            CommandId::SetAccent(Some(2)) => "accent-2",
            CommandId::SetAccent(Some(3)) => "accent-3",
            CommandId::SetAccent(Some(4)) => "accent-4",
            CommandId::SetAccent(Some(5)) => "accent-5",
            CommandId::SetAccent(Some(6)) => "accent-6",
            CommandId::SetAccent(Some(7)) => "accent-7",
            // Unreachable through `ACCENTS`, which is the only source of
            // these ids; spelled rather than panicked so the name stays total.
            CommandId::SetAccent(Some(_)) => "accent-unknown",
            CommandId::SetPinDir(PinDir::Input) => "io-input",
            CommandId::SetPinDir(PinDir::Output) => "io-output",
            CommandId::SetPinDir(PinDir::InOut) => "io-in-out",
        }
    }

    /// Whether invoking this command writes the document — the one list a
    /// read-only session withholds, so an editing command is *uninvocable*
    /// there rather than offered and refused. Arming an editing tool counts:
    /// a tool that cannot commit what it draws is a worse answer than a
    /// button drawn dead, which is what the toolbar shows instead.
    ///
    /// Going up a level is navigation and stays — wholly, now that its one
    /// writing arm (wrapping the document when there is nowhere above to
    /// go) is gone; at the root the command is simply not offered.
    fn writes_the_document(self) -> bool {
        match self {
            CommandId::Arm(tool) => tool.arming_writes_the_document(),
            CommandId::Undo
            | CommandId::Redo
            | CommandId::Cut
            | CommandId::HideTags
            | CommandId::ShowTags
            | CommandId::Rename
            | CommandId::RenameType
            | CommandId::Retype
            | CommandId::RenameTag
            | CommandId::EditText
            | CommandId::FlipLr
            | CommandId::FlipUd
            | CommandId::PinType
            | CommandId::Accent
            | CommandId::Reroute
            | CommandId::SetAccent(_)
            | CommandId::SetPinDir(_)
            | CommandId::AddRouteLabel
            | CommandId::Lock
            | CommandId::Unlock
            | CommandId::AddIcon
            | CommandId::AddImage
            | CommandId::RerouteBlock
            | CommandId::Delete
            | CommandId::Nudge(_)
            | CommandId::Import => true,
            // Save writes a *file* beside the log, never the log — it is
            // gated on there being a writable container instead, which
            // read-only already fails.
            CommandId::Save
            | CommandId::Search
            | CommandId::Copy
            | CommandId::ExportSelection(_)
            | CommandId::Export(_)
            | CommandId::ExpandBlock
            | CommandId::GoUp
            | CommandId::ZoomIn
            | CommandId::ZoomOut
            | CommandId::FitView
            | CommandId::ToggleDiagnostic
            | CommandId::ToggleFrameRate => false,
        }
    }
}

/// What invoking a command does. The registry answers *permission* — which
/// commands this frame offers, and on what target — and never scripts a flow:
/// what the core executes it hands to the core, and what the shell performs
/// itself it hands back untouched.
#[derive(PartialEq, serde::Serialize, serde::Deserialize)]
pub enum Act {
    Edit(Action),
    Effect(Effect),
}

impl From<Action> for Act {
    fn from(action: Action) -> Self {
        Act::Edit(action)
    }
}

impl From<Effect> for Act {
    fn from(effect: Effect) -> Self {
        Act::Effect(effect)
    }
}

/// An effect the front end performs: a picker window, a platform dialog, a
/// download, a document door. Each carries everything the front end needs to
/// run it, and the front end owns every substate of the flow it opens — what
/// a cancel means included — sending what the flow ended in back as an
/// ordinary [`Action`].
#[derive(PartialEq, serde::Serialize, serde::Deserialize)]
pub enum Effect {
    /// Pick artwork to wear as this block's icon.
    AddIcon(BlockId),
    /// Pick artwork to place as an image of its own.
    AddImage,
    /// Open the accent-color (role) picker for a block, port, route, area or
    /// text box. The popup anchors itself above the selection overlay, so no
    /// screen position is carried here.
    Accent(RoleTarget),
    /// Open the pin-type (I/O style) picker over the pins it would retype, on
    /// the same anchoring terms as [`Effect::Accent`].
    PinType(Vec<PinId>),
    /// Open the import dialog, whose PNG or SVG is added as a plain image.
    Import,
    /// Open — or, when it already is, close — the front end's search
    /// palette. Which of the two it comes to is the shell's, because whether
    /// the palette is up is the shell's.
    Search,
    /// Close whatever is open and start a fresh unsaved session. With
    /// append-on-commit there is nothing to prompt about: a container already
    /// holds everything that was committed to it.
    NewDocument,
    /// Call this document something else, which renames its container: the
    /// container's name *is* the document's name. Carries the name the user
    /// typed, unvalidated — [`blockworx_store::storage::Name::of_document`]
    /// is what says whether it is one.
    RenameDocument(String),
    /// Open the File menu's dialog for `request`; the pick comes back through
    /// [`crate::file::PickReceiver`].
    PickFile(crate::file::FileRequest),
    /// Reopen a remembered document, by the reference the shell that
    /// remembered it resolves.
    OpenRecent(DocumentRef),
}

impl Effect {
    /// The variant's own name, for the log line a host with no surface to
    /// perform it on writes.
    pub fn named(&self) -> &'static str {
        match self {
            Effect::AddIcon(_) => "AddIcon",
            Effect::AddImage => "AddImage",
            Effect::Accent(_) => "Accent",
            Effect::PinType(_) => "PinType",
            Effect::Import => "Import",
            Effect::Search => "Search",
            Effect::NewDocument => "NewDocument",
            Effect::RenameDocument(_) => "RenameDocument",
            Effect::PickFile(_) => "PickFile",
            Effect::OpenRecent(_) => "OpenRecent",
        }
    }
}

/// One available operation: its identity, the label/hover text a view shows,
/// and what invoking it does.
#[derive(PartialEq, serde::Serialize, serde::Deserialize)]
pub struct Command {
    pub id: CommandId,
    pub label: Cow<'static, str>,
    pub act: Act,
    /// Where this command stands in the selection overlay's order. Set once,
    /// here, so the bar and the right-click menu read one policy.
    pub precedence: Precedence,
    rendered: Rendered,
    authoring: Authoring,
}

/// Which of a selection's controls come first in the overlay: the selected
/// thing's own verbs, then the clerical ones every selection has.
///
/// The user named the own verbs: *"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'."* The bar shows the head of the ordered list and puts the rest behind
/// its ellipsis, so the clerical verbs are the first to go there.
///
/// Orthogonal to applicability: a command this selection does not offer is
/// simply absent, whichever rank it holds.
#[derive(
    Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, serde::Serialize, serde::Deserialize,
)]
pub enum Precedence {
    Own,
    Clerical,
}

impl Precedence {
    pub fn of(id: CommandId) -> Self {
        match id {
            CommandId::Accent
            | CommandId::ExpandBlock
            | CommandId::AddIcon
            | CommandId::Lock
            | CommandId::Unlock
            | CommandId::Reroute
            | CommandId::RerouteBlock
            | CommandId::FlipLr
            | CommandId::FlipUd
            // Three the user's list did not name because they had no icons
            // to name them by: a route's label, a pin's tag and a port's I/O
            // direction. They are the selected thing's own verbs the same
            // way Accent and Lock are.
            | CommandId::AddRouteLabel
            | CommandId::HideTags
            | CommandId::ShowTags
            | CommandId::PinType => Precedence::Own,
            // Copy, Cut, Delete, Export — the clerical verbs, which every
            // selection has and none is *about* — and everything that is not
            // in the overlay at all.
            _ => Precedence::Clerical,
        }
    }
}

/// Whether the selection overlay draws a control for `id`.
///
/// Membership is the registry's, not a drawing's: a shell that has no
/// artwork for a verb still has to know the verb belongs on the bar, or two
/// front ends would offer two different bars over one selection. The
/// selection's export offers its leading format only — the rest are reached
/// through that control's own menu.
pub fn in_overlay(id: CommandId) -> bool {
    match id {
        CommandId::ExportSelection(format) => format == ExportScope::Selection.leading_format(),
        CommandId::Accent
        | CommandId::AddIcon
        | CommandId::AddRouteLabel
        | CommandId::Copy
        | CommandId::Cut
        | CommandId::Delete
        | CommandId::ExpandBlock
        | CommandId::FlipLr
        | CommandId::FlipUd
        | CommandId::HideTags
        | CommandId::Lock
        | CommandId::PinType
        | CommandId::Reroute
        | CommandId::RerouteBlock
        | CommandId::ShowTags
        | CommandId::Unlock => true,
        _ => false,
    }
}

impl Command {
    /// Whether this session withholds the command. A withheld command is
    /// uninvocable — every taking door skips it — but it is still *known*,
    /// so a surface can draw its control disabled instead of leaving a
    /// hole (the familiar paradigm, per docs/ui-issues.md's follow-up).
    pub fn withheld(&self) -> bool {
        self.authoring.is_withheld()
    }

    /// Whether this command draws a control, or only answers to its name.
    pub fn rendered(&self) -> Rendered {
        self.rendered
    }
}

/// Whether a command appears as a control, or only answers to its name.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Rendered {
    AsAButton,
    ByNameOnly,
}

/// Everything [`CommandSet::available`] resolves availability against.
pub struct CommandContext<'a, 'b> {
    pub tool: &'a Tool,
    pub data: &'a Drawing<'b>,
    pub history: History,
    /// Whether the block currently viewed keeps its interface frozen — gates
    /// arming the Add Port tool.
    pub current_lock: InterfaceLock,
    /// Whether this session may write the document *at all* — a container
    /// another process holds, or one whose log will not verify, withholds
    /// every command that writes the document. The time
    /// machine is the other half of that question and rides in `viewing`.
    pub writability: Writability,
    /// Whether there is a projection to refresh — gates [`CommandId::Save`]
    /// and nothing else.
    pub saving: Saving,
    /// Which document is on the canvas. A past rev is read-only through
    /// `writability`, like any other read-only session.
    pub viewing: Viewing,
}

/// The chord for `key` with the platform command modifier.
const fn chord(key: Key) -> Chord {
    Chord {
        modifiers: Modifiers::Command,
        key,
    }
}

/// A bare key, no modifier — how the tool band's digits and the arrows are
/// pressed.
const fn bare(key: Key) -> Chord {
    Chord {
        modifiers: Modifiers::None,
        key,
    }
}

/// The command modifier with Shift — how a chord's opposite is pressed.
const fn shifted(key: Key) -> Chord {
    Chord {
        modifiers: Modifiers::CommandShift,
        key,
    }
}

/// The chord → command bindings, one table: the app's shortcut pass consumes
/// it and the views print it (tool-band hover text, palette rows), so a chord
/// can never disagree with what it dispatches. Toolbar arming, the camera and
/// the history; selection verbs join here when they earn chords.
///
/// Each band tool answers to two keys: the digit of its place in the row, and
/// its mnemonic chord. The digits are bare keys, which is safe because the
/// whole table is only consulted when no text field holds the keyboard.
pub const BINDINGS: &[(Chord, CommandId)] = &[
    (bare(Key::Num1), CommandId::Arm(ToolName::Select)),
    (chord(Key::E), CommandId::Arm(ToolName::Select)),
    (bare(Key::Num2), CommandId::Arm(ToolName::NewBlock)),
    (chord(Key::B), CommandId::Arm(ToolName::NewBlock)),
    (bare(Key::Num3), CommandId::Arm(ToolName::AddPin)),
    (chord(Key::N), CommandId::Arm(ToolName::AddPin)),
    (bare(Key::Num4), CommandId::Arm(ToolName::Route)),
    (chord(Key::R), CommandId::Arm(ToolName::Route)),
    (bare(Key::Num5), CommandId::Arm(ToolName::AddPort)),
    (chord(Key::P), CommandId::Arm(ToolName::AddPort)),
    (bare(Key::Num6), CommandId::Arm(ToolName::AddText)),
    (chord(Key::T), CommandId::Arm(ToolName::AddText)),
    (bare(Key::Num7), CommandId::Arm(ToolName::NewArea)),
    (chord(Key::M), CommandId::Arm(ToolName::NewArea)),
    (bare(Key::Num8), CommandId::AddImage),
    (chord(Key::I), CommandId::AddImage),
    // Zoom in is bound twice: `+` is a shifted key on most layouts, so the
    // unshifted `=` in its place is the chord people actually press.
    (chord(Key::Equals), CommandId::ZoomIn),
    (chord(Key::Plus), CommandId::ZoomIn),
    (chord(Key::Minus), CommandId::ZoomOut),
    (chord(Key::Num0), CommandId::FitView),
    (chord(Key::Z), CommandId::Undo),
    // Redo is bound twice as well: ⌘⇧Z beside ⌘Z, and ⌘Y where that is the
    // habit.
    (shifted(Key::Z), CommandId::Redo),
    (chord(Key::Y), CommandId::Redo),
    (chord(Key::K), CommandId::Search),
    (bare(Key::ArrowLeft), CommandId::Nudge(Heading::Left)),
    (bare(Key::ArrowRight), CommandId::Nudge(Heading::Right)),
    (bare(Key::ArrowUp), CommandId::Nudge(Heading::Up)),
    (bare(Key::ArrowDown), CommandId::Nudge(Heading::Down)),
];

/// The chord bound to `id`, if any — for the views that print one.
pub fn binding(id: CommandId) -> Option<&'static Chord> {
    chords(id).next()
}

/// Every chord bound to `id`, in table order — for the views that print them
/// all, so a tool with two keys advertises both.
pub fn chords(id: CommandId) -> impl Iterator<Item = &'static Chord> {
    BINDINGS
        .iter()
        .filter(move |(_, bound)| *bound == id)
        .map(|(chord, _)| chord)
}

/// The command one cell of the rail invokes. Every cell but the image arms its
/// tool; there is no image tool — artwork is picked and then placed, and the
/// picker is the shell's — so that cell asks for the artwork instead. Read by
/// the rail, the registry and the chord table, so the three cannot disagree
/// about what a cell does.
pub fn band_command(tool: ToolName) -> CommandId {
    match tool {
        ToolName::NewImage => CommandId::AddImage,
        armed => CommandId::Arm(armed),
    }
}

/// And what invoking it does.
fn band_act(tool: ToolName) -> Act {
    match tool {
        ToolName::NewImage => Effect::AddImage.into(),
        armed => Action::Arm(armed).into(),
    }
}

/// Whether arming `tool` is currently allowed: adding a port inside a locked
/// block is the one refusal — the viewed interface is frozen. Private
/// because the views ask the resolved [`CommandSet`] instead, so a control
/// and the command behind it cannot disagree.
fn arm_available(tool: ToolName, current_lock: InterfaceLock) -> bool {
    !(current_lock.is_locked() && tool == ToolName::AddPort)
}

/// The frame's available commands, in the canonical presentation order the
/// selection overlay renders them in.
#[derive(PartialEq, serde::Serialize, serde::Deserialize)]
pub struct CommandSet {
    available: Vec<Command>,
    /// Applied by [`Self::push`], so the withholding happens once instead of
    /// at each of the thirty-odd sites that offer a command.
    writability: Writability,
    viewing: Viewing,
    /// Which kind of entry undo and redo stand over, since that is what says
    /// whether they write.
    history: History,
}

impl CommandSet {
    pub fn available(ctx: &CommandContext<'_, '_>) -> Self {
        let mut set = CommandSet {
            available: Vec::new(),
            writability: ctx.writability,
            viewing: ctx.viewing,
            history: ctx.history,
        };
        for tool in band_tools() {
            if arm_available(tool, ctx.current_lock) {
                set.push(band_command(tool), tool.label(), band_act(tool));
            }
        }
        if ctx.history.undo.is_some() {
            set.push(CommandId::Undo, "Undo", Action::Undo);
        }
        if ctx.history.redo.is_some() {
            set.push(CommandId::Redo, "Redo", Action::Redo);
        }
        if let Some(sel) = ctx.tool.selection() {
            set.selection_commands(&sel, ctx.data);
        }
        // Rising a level is navigation, and above the document root there is
        // nowhere to rise to — so the toolbar's Up draws dead there rather
        // than doing something else instead. It lives on the toolbar rather
        // than the selection overlay, so it is not ordered among the
        // selection verbs.
        if ctx.data.current_scope() != crate::path::Scope::Root {
            set.push(CommandId::GoUp, "Go up a level", Action::GoUp);
        }
        // View commands: always available, and reachable by chord or palette
        // rather than by any button.
        set.push(
            CommandId::ZoomIn,
            "Zoom in",
            Action::Zoom(blockworx_paint::ZoomStep::In),
        );
        set.push(
            CommandId::ZoomOut,
            "Zoom out",
            Action::Zoom(blockworx_paint::ZoomStep::Out),
        );
        set.push(CommandId::FitView, "Fit diagram in view", Action::ResetView);
        // Dev tooling: offered always, bound to nothing, found by name.
        set.push(
            CommandId::ToggleDiagnostic,
            "Diagnostics: regional router",
            Action::ToggleDiagnostic,
        );
        set.push(
            CommandId::ToggleFrameRate,
            "Diagnostics: frame rate",
            Action::ToggleFrameRate,
        );
        for &format in ExportScope::View.formats() {
            set.push(
                CommandId::Export(format),
                format.label(),
                Action::Export {
                    format,
                    selection: None,
                },
            );
        }
        set.push(CommandId::Import, "Import", Effect::Import);
        set.push_by_name_only(CommandId::Search, "Search", Effect::Search);
        set
    }

    /// The arrow keys' moves, which draw no control of their own.
    fn nudges(&mut self, headings: &[Heading]) {
        for &heading in headings {
            self.push_by_name_only(CommandId::Nudge(heading), heading.label(), heading.nudge());
        }
    }

    fn selection_commands(&mut self, sel: &Deletable, data: &Drawing<'_>) {
        if let Some(shapes) = sel.shapes() {
            self.push(CommandId::Copy, "Copy", Action::Copy(shapes.clone()));
            self.nudges(&Heading::ALL);
            // Exporting a selection writes it out as a standalone diagram, so
            // it needs a block: a lone port, area, or text box is an
            // annotation on someone else's diagram, not one of its own.
            if shapes.iter().any(|shape| shape.is_block()) {
                for &format in ExportScope::Selection.formats() {
                    self.push(
                        CommandId::ExportSelection(format),
                        format.label(),
                        Action::Export {
                            format,
                            selection: Some(shapes.clone()),
                        },
                    );
                }
            }
            if !delete_blocked_by_lock(sel, data) {
                self.push(CommandId::Cut, "Cut", Action::Cut(shapes));
            }
        }
        if let Deletable::Pins(pins) = sel {
            self.push(CommandId::Copy, "Copy", Action::CopyPins(pins.clone()));
            self.nudges(&Heading::ALONG_AN_EDGE);
            if !delete_blocked_by_lock(sel, data) {
                self.push(CommandId::Cut, "Cut", Action::CutPins(pins.clone()));
            }
            // "Hide Tags" only when every selected tag is visible; a hidden or
            // mixed group reads "Show Tags".
            let all_visible = pins
                .iter()
                .all(|&a| data.pin_on_shape(a).is_some_and(|(_, pin)| !pin.tag_hidden));
            let (id, label, tags) = if all_visible {
                (CommandId::HideTags, "Hide Tags", TagVisibility::Hidden)
            } else {
                (CommandId::ShowTags, "Show Tags", TagVisibility::Shown)
            };
            self.push(
                id,
                label,
                Action::SetPinTags {
                    pins: pins.clone(),
                    tags,
                },
            );
        }
        if let Deletable::Shape(id) = sel
            && let Some(hidden) = data.shape_tag_hidden(*id)
        {
            let (cid, label, tags) = if hidden {
                (CommandId::ShowTags, "Show Tag", TagVisibility::Shown)
            } else {
                (CommandId::HideTags, "Hide Tag", TagVisibility::Hidden)
            };
            self.push(cid, label, Action::SetShapeTagHidden { shape: *id, tags });
        }
        self.editor_commands(sel, data);
        // A locked block keeps its pin interface frozen, so the I/O (retype)
        // control is withheld when any selected pin's owner is locked.
        if let Some(pins) = io_pins(sel)
            && !pins.iter().any(|a| data.pin_owner_locked(*a))
        {
            self.push(CommandId::PinType, "I/O", Effect::PinType(pins.clone()));
            for (id, label, kind) in PIN_DIRS {
                self.push_by_name_only(
                    id,
                    label,
                    Action::SetPinsKind {
                        pins: pins.clone(),
                        kind,
                    },
                );
            }
        }
        if let Some(target) = role_target(sel) {
            self.push(CommandId::Accent, "Accent", Effect::Accent(target));
            for (id, label, role) in ACCENTS {
                self.push_by_name_only(id, label, Action::SetRole { target, role });
            }
        }
        if let Deletable::Route(rid) = sel {
            self.push(
                CommandId::Reroute,
                "Rip up and autoroute",
                Action::Reroute(*rid),
            );
            self.push(
                CommandId::AddRouteLabel,
                "Add label",
                Action::ArmAddRouteLabel(*rid),
            );
        }
        if let Deletable::Shape(ShapeId::Rect(rid)) = sel {
            self.block_commands(*rid, data);
        }
        // Only the pin-bearing shapes have anything to mirror. The flips come
        // last of the own verbs, where the user's list put them.
        if let Deletable::Shape(id @ (ShapeId::Rect(_) | ShapeId::Port(_))) = sel {
            self.push(CommandId::FlipLr, "Flip L/R", Action::FlipShapePins(*id));
        }
        if let Deletable::Shape(ShapeId::Rect(rid)) = sel {
            self.push(
                CommandId::FlipUd,
                "Flip U/D",
                Action::FlipBlockVertical(*rid),
            );
        }
        // Delete is withheld for a locked pin/port selection — locking protects
        // the interface, not the block's existence, so whole-block Delete (and
        // every other selection's) is unaffected.
        if !delete_blocked_by_lock(sel, data) {
            self.push(CommandId::Delete, "Delete", Action::Delete(sel.clone()));
        }
    }

    /// The in-place label editors the selection can open — the same tools the
    /// double-click path arms. Palette-only: none has an overlay button.
    fn editor_commands(&mut self, sel: &Deletable, data: &Drawing<'_>) {
        if let Deletable::Shape(id) = sel {
            self.offer_editor(data, CommandId::Rename, "Rename", EditTarget::Title(*id));
            if let ShapeId::Rect(rid) = id {
                self.offer_editor(
                    data,
                    CommandId::RenameType,
                    "Rename type",
                    EditTarget::BlockType(*rid),
                );
            }
            if let ShapeId::Text(tid) = id {
                self.offer_editor(
                    data,
                    CommandId::EditText,
                    "Edit text",
                    EditTarget::Text(*tid),
                );
            }
        }
        // A single pin — or a port, whose labels are its one pin's — edits its
        // own name/type/tag.
        let anchor = match sel {
            Deletable::Pins(pins) if pins.len() == 1 => Some(pins[0]),
            Deletable::Shape(ShapeId::Port(pid)) => Some(*pid),
            _ => None,
        };
        if let Some(anchor) = anchor {
            self.offer_editor(
                data,
                CommandId::Rename,
                "Rename",
                EditTarget::PinName(anchor),
            );
            self.offer_editor(
                data,
                CommandId::Retype,
                "Retype",
                EditTarget::PinType(anchor),
            );
            self.offer_editor(
                data,
                CommandId::RenameTag,
                "Rename tag",
                EditTarget::PinTag(anchor),
            );
        }
    }

    /// Offered where the editor would open now. The command names the field,
    /// not the editor, so dispatch builds the editor again against the
    /// drawing as it then stands.
    fn offer_editor(
        &mut self,
        data: &Drawing<'_>,
        id: CommandId,
        label: &'static str,
        target: EditTarget,
    ) {
        if tool_for_target(data, target).is_some() {
            self.push(id, label, Action::OpenEditor(target));
        }
    }

    fn block_commands(&mut self, rid: BlockId, data: &Drawing<'_>) {
        self.push(
            CommandId::ExpandBlock,
            "Expand block",
            Action::ExpandBlock(rid),
        );
        let locked = data.shape_owner_locked(ShapeId::Rect(rid));
        let (id, label, lock) = if locked {
            (CommandId::Unlock, "Unlock pins", InterfaceLock::Unlocked)
        } else {
            (CommandId::Lock, "Lock pins", InterfaceLock::Locked)
        };
        self.push(id, label, Action::SetBlockLocked { block: rid, lock });
        let label = if data.icon(rid).is_some() {
            "Replace icon"
        } else {
            "Add icon"
        };
        self.push(CommandId::AddIcon, label, Effect::AddIcon(rid));
        self.push(
            CommandId::RerouteBlock,
            "Rip up and autoroute every wire on this block",
            Action::RerouteBlock(rid),
        );
    }

    fn push(&mut self, id: CommandId, label: &'static str, act: impl Into<Act>) {
        self.offer(id, label, act.into(), Rendered::AsAButton);
    }

    /// Available to name — a chord, the palette's text field, a script's
    /// `command` step — but not rendered as a control. The accent and I/O
    /// values are the case this exists for: nine colours and three
    /// directions are a picker's job on screen, and nine more buttons would
    /// bury the selection bar, but each still has to be *sayable* or a script
    /// could not set one.
    fn push_by_name_only(&mut self, id: CommandId, label: &'static str, act: impl Into<Act>) {
        self.offer(id, label, act.into(), Rendered::ByNameOnly);
    }

    /// The one gate every command passes through. A read-only session marks
    /// the writing half of the registry withheld here — not at the call
    /// sites — and every door that *invokes* (a chord, the palette, a
    /// script's `command` step, a click) skips a withheld command, so
    /// keeping it around for the overlay to draw disabled cannot make it
    /// reachable.
    fn offer(&mut self, id: CommandId, label: &'static str, act: Act, rendered: Rendered) {
        let authoring = if self.allows(id) {
            Authoring::Offered
        } else {
            Authoring::Withheld
        };
        self.available.push(Command {
            id,
            label: Cow::Borrowed(label),
            act,
            precedence: Precedence::of(id),
            rendered,
            authoring,
        });
    }

    /// Whether `id` survives the frame's two read-only questions. They are
    /// two questions — a container this session may not write, and a past
    /// rev on the canvas — with one answer: nothing writes the document
    /// through the lens. The way out of it is Return or a Save-as, and a
    /// Save-as writes a *file*, never this log. Undo and redo go with the
    /// rest *when they author* — they would act on the head nobody is
    /// looking at — and stay when they do not.
    fn allows(&self, id: CommandId) -> bool {
        if !self.writes(id) {
            return true;
        }
        self.writability == Writability::Writable && self.viewing == Viewing::Head
    }

    /// Whether `id` would write *this frame*. Undo and redo answer with the
    /// kind of entry they stand over: taking back a camera move
    /// restores a camera and touches no log, so it survives both the lens and
    /// a container this session may not write. Every other command answers
    /// from its own identity.
    fn writes(&self, id: CommandId) -> bool {
        match id {
            CommandId::Undo => self.history.undo.is_some_and(crate::history::Kind::writes),
            CommandId::Redo => self.history.redo.is_some_and(crate::history::Kind::writes),
            other => other.writes_the_document(),
        }
    }

    /// The invocable commands to render. Everything else is reachable by
    /// name through [`Self::take`].
    pub fn iter(&self) -> impl Iterator<Item = &Command> {
        self.iter_drawn().filter(|command| !command.withheld())
    }

    /// Every command that draws a control, the withheld ones included — the
    /// selection overlay's view, which renders those disabled rather than
    /// leaving a hole where a control was.
    pub fn iter_drawn(&self) -> impl Iterator<Item = &Command> {
        self.available
            .iter()
            .filter(|command| command.rendered == Rendered::AsAButton)
    }

    /// Every command this frame offers, drawn or not — what a front end that
    /// carries the whole registry across a seam reads, so a chord bound to a
    /// by-name-only command still resolves there.
    pub fn iter_all(&self) -> impl Iterator<Item = &Command> {
        self.available.iter()
    }

    pub fn contains(&self, id: CommandId) -> bool {
        self.get(id).is_some()
    }

    pub fn get(&self, id: CommandId) -> Option<&Command> {
        self.available.iter().find(|c| c.id == id && !c.withheld())
    }

    /// Consume what `id` does, to perform it. At most one command fires per
    /// frame, so taking moves it out rather than cloning it. A withheld
    /// command cannot be taken, however it was named.
    pub fn take(&mut self, id: CommandId) -> Option<Act> {
        let index = self
            .available
            .iter()
            .position(|c| c.id == id && !c.withheld())?;
        Some(self.available.remove(index).act)
    }

    /// [`CommandSet::take`] by the command's typeable name — how the script
    /// `command` step names it.
    #[cfg(test)]
    pub fn take_by_name(&mut self, name: &str) -> Option<Act> {
        let name = legacy_command_name(name);
        let index = self
            .available
            .iter()
            .position(|c| c.id.name() == name && !c.withheld())?;
        Some(self.available.remove(index).act)
    }
}

/// Older command spellings, still resolved so a script that names one keeps
/// running.
#[cfg(test)]
fn legacy_command_name(name: &str) -> &str {
    match name {
        "comment" => "area",
        other => other,
    }
}

/// What became of an [`Act`] offered to [`apply_scripted`]: applied against
/// the drawing — carrying the tool the arm settles on, where it settles one —
/// handed back because it needs app machinery (clipboard, the undo stack,
/// navigation, the lens), or not a document edit at all.
pub enum ScriptedApply {
    Applied(Option<Tool>),
    NeedsApp(Box<Action>),
    /// An effect the shell performs. A driver with no shell has no dialog to
    /// open and nothing to apply.
    NotApplicable(Effect),
}

/// Apply the document-scoped subset of [`Act`] — the arms that write nothing
/// but the drawing. The app's dispatcher routes these same arms here, so a
/// scripted session and a live one cannot drift. The gesture the caller
/// opened owns the sealing: every write lands in its sink, and the solve
/// rider re-routes what these arms disturbed.
pub fn apply_scripted(act: Act, drawing: &mut Drawing<'_>) -> ScriptedApply {
    use crate::SelectTool;
    let action = match act {
        Act::Edit(action) => action,
        Act::Effect(effect) => return ScriptedApply::NotApplicable(effect),
    };
    let settles_on = match action {
        Action::Arm(name) => armed(Tool::from_name(name), drawing),
        Action::ArmAddRouteLabel(route) => {
            armed(crate::AddRouteLabel::Armed(route).into(), drawing)
        }
        // A field gone since the command was offered opens nothing.
        Action::OpenEditor(target) => {
            tool_for_target(drawing, target).and_then(|tool| armed(tool, drawing))
        }
        // The same gate, for the cell's other gesture: a session that cannot
        // arm a creator cannot drop one either, whichever door asked. The
        // cell already draws dead, so this is the floor under that rather
        // than the only refusal.
        Action::StampTool { .. } if drawing.authoring() == Authoring::Withheld => None,
        Action::StampTool { tool, at } => crate::stamp::stamp(drawing, tool, at),
        Action::Delete(what) => {
            drawing.delete(what);
            Some(Tool::Select(SelectTool))
        }
        // Keep the pin selection so the label updates and a follow-up click
        // can finish synchronizing a mixed group.
        Action::SetPinTags { pins, tags } => {
            drawing.set_pins_tag_hidden(&pins, tags);
            None
        }
        Action::SetShapeTagHidden { shape, tags } => {
            drawing.set_shape_tag_hidden(shape, tags);
            None
        }
        // Flipping moves pins to new sides, so re-approach the connected
        // routes exactly like a drag does: drop the stale approach corners
        // and let the rider re-route. The shape stays selected, so its bar
        // stays up.
        Action::FlipShapePins(shape) => {
            drawing.flip_shape_pins(shape);
            drawing.trim_partial_route_approaches(&[shape]);
            None
        }
        Action::FlipBlockVertical(block) => {
            drawing.flip_block_vertical(block);
            drawing.trim_partial_route_approaches(&[ShapeId::Rect(block)]);
            None
        }
        // The lock governs only future pin/port edits, so nothing re-routes;
        // the block stays selected so its overlay (and lock toggle) stays.
        Action::SetBlockLocked { block, lock } => {
            drawing.set_block_locked(block, lock);
            None
        }
        Action::Reroute(id) => {
            drawing.reroute(id);
            None
        }
        // The selection stays, so the picker that asked stays open and a
        // second colour can be tried without re-selecting.
        Action::SetRole { target, role } => {
            drawing.set_role(target, role);
            None
        }
        Action::SetPinsKind { pins, kind } => {
            drawing.set_pins_kind(&pins, kind);
            None
        }
        Action::RerouteBlock(id) => {
            drawing.reroute_block(id);
            None
        }
        other => return ScriptedApply::NeedsApp(Box::new(other)),
    };
    ScriptedApply::Applied(settles_on)
}

/// [`apply_scripted`] for what a tool's own frame asks for. A hand-off to a
/// seeded tool passes the same arming gate an [`Action::Arm`] does.
pub fn apply_transition(transition: Transition, drawing: &mut Drawing<'_>) -> ScriptedApply {
    match transition {
        Transition::SwitchTool(next) => ScriptedApply::Applied(armed(next, drawing)),
        Transition::Action(action) => apply_scripted(Act::Edit(action), drawing),
    }
}

/// The last gate on arming: a read-only session refuses a tool whose whole
/// purpose is to write, whichever door asked for it — a chord, a script's
/// `command` step, or another tool handing off.
fn armed(next: Tool, drawing: &Drawing<'_>) -> Option<Tool> {
    let refused =
        next.name().arming_writes_the_document() && drawing.authoring() == Authoring::Withheld;
    (!refused).then_some(next)
}

/// The pin anchors an I/O-style change would retype, or `None` for selections
/// with no pins to retype. A pin or pin group maps to its anchors directly; a
/// boundary port maps to its single port pin.
fn io_pins(sel: &Deletable) -> Option<Vec<PinId>> {
    match sel {
        Deletable::Pins(pins) => Some(pins.clone()),
        Deletable::Shape(ShapeId::Port(pid)) => Some(vec![*pid]),
        _ => None,
    }
}

/// The accent target a selection maps to, or `None` for selections that carry
/// no accent (an image/icon shape, a multi-selection, or a pin group — the
/// picker targets one role-bearing object).
/// The accent picker's cells: "no accent" plus the eight numbered ones, in
/// the order they are drawn, each as the command that sets it — so
/// `accent-3` on screen and `accent-3` in a script name one colour, and a
/// picker cannot offer a tenth colour the registry cannot be told about.
pub const ACCENTS: [(CommandId, &str, Option<u8>); 9] = [
    (CommandId::SetAccent(None), "No accent", None),
    (CommandId::SetAccent(Some(0)), "Accent 0", Some(0)),
    (CommandId::SetAccent(Some(1)), "Accent 1", Some(1)),
    (CommandId::SetAccent(Some(2)), "Accent 2", Some(2)),
    (CommandId::SetAccent(Some(3)), "Accent 3", Some(3)),
    (CommandId::SetAccent(Some(4)), "Accent 4", Some(4)),
    (CommandId::SetAccent(Some(5)), "Accent 5", Some(5)),
    (CommandId::SetAccent(Some(6)), "Accent 6", Some(6)),
    (CommandId::SetAccent(Some(7)), "Accent 7", Some(7)),
];

/// The I/O picker's cells, on the same terms as [`ACCENTS`]: an arrow
/// arriving, one arriving and leaving, one leaving — the order a picker lays
/// them out in, which is also the order they read in.
pub const PIN_DIRS: [(CommandId, &str, PinDir); 3] = [
    (CommandId::SetPinDir(PinDir::Input), "Input", PinDir::Input),
    (
        CommandId::SetPinDir(PinDir::InOut),
        "Input Output",
        PinDir::InOut,
    ),
    (
        CommandId::SetPinDir(PinDir::Output),
        "Output",
        PinDir::Output,
    ),
];

fn role_target(sel: &Deletable) -> Option<RoleTarget> {
    match sel {
        Deletable::Shape(ShapeId::Rect(rid)) => Some(RoleTarget::Block(*rid)),
        Deletable::Shape(ShapeId::Port(pid)) => Some(RoleTarget::Port(*pid)),
        Deletable::Shape(ShapeId::Area(cid)) => Some(RoleTarget::Area(*cid)),
        Deletable::Shape(ShapeId::Text(tid)) => Some(RoleTarget::Text(*tid)),
        Deletable::Route(rid) => Some(RoleTarget::Route(*rid)),
        Deletable::Shape(ShapeId::Image(_) | ShapeId::Icon(_))
        | Deletable::Shapes(_)
        | Deletable::Pins(_) => None,
    }
}

/// Whether the Delete/Cut controls are withheld because the selection is a
/// locked pin/port interface: any selected child-block pin whose owner is
/// locked, or a boundary port of a locked current block.
fn delete_blocked_by_lock(sel: &Deletable, data: &Drawing<'_>) -> bool {
    match sel {
        Deletable::Pins(pins) => pins.iter().any(|a| data.pin_owner_locked(*a)),
        Deletable::Shape(id @ ShapeId::Port(_)) => data.shape_owner_locked(*id),
        _ => false,
    }
}

/// What an [`Act`] does, named — for the failure message when a test invoked
/// something other than what it meant to.
#[cfg(any(test, feature = "test-support"))]
pub fn act_name(act: &Act) -> &'static str {
    match act {
        Act::Edit(action) => action_name(action),
        Act::Effect(effect) => effect.named(),
    }
}

/// The [`Action`] variant's own name, on the same terms.
#[cfg(any(test, feature = "test-support"))]
pub fn action_name(action: &Action) -> &'static str {
    match action {
        Action::Arm(_) => "Arm",
        Action::ArmAddRouteLabel(_) => "ArmAddRouteLabel",
        Action::OpenEditor(_) => "OpenEditor",
        Action::StampTool { .. } => "StampTool",
        Action::Delete(_) => "Delete",
        Action::Copy(_) => "Copy",
        Action::CopyPins(_) => "CopyPins",
        Action::Cut(_) => "Cut",
        Action::CutPins(_) => "CutPins",
        Action::SetPinTags { .. } => "SetPinTags",
        Action::SetShapeTagHidden { .. } => "SetShapeTagHidden",
        Action::FlipShapePins(_) => "FlipShapePins",
        Action::FlipBlockVertical(_) => "FlipBlockVertical",
        Action::SetBlockLocked { .. } => "SetBlockLocked",
        Action::Paste(_) => "Paste",
        Action::ExpandBlock(_) => "ExpandBlock",
        Action::GoToPath(_) => "GoToPath",
        Action::Zoom(_) => "Zoom",
        Action::SetRole { .. } => "SetRole",
        Action::SetPinsKind { .. } => "SetPinsKind",
        Action::GoUp => "GoUp",
        Action::AcknowledgeFailure(_) => "AcknowledgeFailure",
        Action::FrameRect(_) => "FrameRect",
        Action::NavSelect { .. } => "NavSelect",
        Action::Undo => "Undo",
        Action::Redo => "Redo",
        Action::Nudge { .. } => "Nudge",
        Action::ResetView => "ResetView",
        Action::ToggleDiagnostic => "ToggleDiagnostic",
        Action::ToggleFrameRate => "ToggleFrameRate",
        Action::Export { .. } => "Export",
        Action::SetIcon { .. } => "SetIcon",
        Action::PlaceImage { .. } => "PlaceImage",
        Action::Reroute(_) => "Reroute",
        Action::RerouteBlock(_) => "RerouteBlock",
        Action::ViewRev(_) => "ViewRev",
        Action::ViewHead => "ViewHead",
        Action::TagRev { .. } => "TagRev",
        Action::SetPalette(_) => "SetPalette",
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::{
        resize_block::ResizeBlock,
        select_pin::SelectPin,
        widget::test_fixtures::{self as fx, Scene},
    };
    use blockworx_doc::{
        fixtures::{block_id, pin_id, route_id},
        values::PinSide,
    };
    use blockworx_geom::{Rect, pos2};

    /// Block `1` ("core") carrying its one West pin `2` — the selection every
    /// availability claim below is made against.
    fn scene_with_block() -> Scene {
        Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(80.0, 80.0)),
            ),
            fx::titled(1, "core"),
            fx::pin(2, 1, PinSide::West, 0),
        ])
    }

    /// Two wired blocks, each tall enough to offer several pin slots — so a
    /// route, a pin group and a block are all selectable, *and* a vertical
    /// flip has somewhere to move the pin to. A block one slot tall makes
    /// `FlipUd` an exact no-op, which the emitter correctly drops; the fixture
    /// has to give the command room to act or the test proves nothing.
    fn scene_for_effects() -> Scene {
        Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 150.0)),
            ),
            fx::block_in(
                2,
                Scope::Root,
                Rect::from_min_max(pos2(180.0, 0.0), pos2(240.0, 150.0)),
            ),
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[(20, 4)]),
        ])
    }

    fn block_tool() -> Tool {
        ResizeBlock::Selected {
            shape: ShapeId::Rect(block_id(1)),
        }
        .into()
    }

    /// Ripping up one wire is a route verb, offered only to a route
    /// selection — which is the edit-route tool's, not the select tool's.
    fn route_tool() -> Tool {
        crate::EditRoute::Selected {
            id: route_id(5),
            anchor: pos2(120.0, 40.0),
        }
        .into()
    }

    /// The tag toggle is a pin-*group* verb, so it needs the group selection
    /// the multi-pin tool holds rather than the single-pin one.
    fn pin_group_tool() -> Tool {
        crate::MultiPinSelect::Selected {
            pins: vec![pin_id(3)],
        }
        .into()
    }

    fn no_history() -> History {
        History::empty()
    }

    fn available_for(scene: &mut Scene, tool: &Tool, history: History) -> CommandSet {
        let drawing = scene.drawing();
        CommandSet::available(&CommandContext {
            tool,
            data: &drawing,
            history,
            current_lock: InterfaceLock::Unlocked,
            writability: Writability::Writable,
            saving: blockworx_store::doc::Saving::Withheld,
            viewing: Viewing::Head,
        })
    }

    fn position(set: &CommandSet, id: CommandId) -> usize {
        set.iter()
            .position(|c| c.id == id)
            .unwrap_or_else(|| panic!("{id:?} not in the set"))
    }

    /// Rising a level is navigation, so a read-only session keeps it — but
    /// above the document root there is nowhere to rise to, and the command
    /// is simply not there, which draws the toolbar's Up button dead. A
    /// navigation button must never quietly write a block.
    #[test]
    fn rising_a_level_is_offered_everywhere_but_the_document_root() {
        let tool: Tool = crate::SelectTool.into();
        let offered = |scene: &mut Scene, writability| {
            let drawing = scene.drawing();
            CommandSet::available(&CommandContext {
                tool: &tool,
                data: &drawing,
                history: no_history(),
                current_lock: InterfaceLock::Unlocked,
                writability,
                saving: blockworx_store::doc::Saving::Withheld,
                viewing: Viewing::Head,
            })
            .contains(CommandId::GoUp)
        };
        let mut inside = scene_with_block().inside(block_id(1));
        assert!(offered(&mut inside, Writability::Writable));
        assert!(
            offered(&mut inside, Writability::ReadOnly),
            "navigation writes nothing, so a reader may still rise",
        );
        let mut root = scene_with_block();
        assert!(!offered(&mut root, Writability::Writable));
        assert!(!offered(&mut root, Writability::ReadOnly));
    }

    /// The lens has no writing command at all: under it a writable
    /// container offers exactly what a read-only one does, and the way out of
    /// the past is Return or a Save-as — which writes a *file*, never this
    /// log.
    #[test]
    fn nothing_writes_the_document_through_the_lens() {
        let mut scene = scene_with_block();
        let tool: Tool = crate::SelectTool.into();
        let mut offered = |writability, viewing| {
            let drawing = scene.drawing();
            CommandSet::available(&CommandContext {
                tool: &tool,
                data: &drawing,
                history: no_history(),
                current_lock: InterfaceLock::Unlocked,
                writability,
                saving: blockworx_store::doc::Saving::Withheld,
                viewing,
            })
        };
        let past = Viewing::Past(blockworx_doc::fixtures::rev(2));
        assert!(
            offered(Writability::Writable, Viewing::Head).contains(CommandId::Import),
            "precondition: the writable present offers a command that writes",
        );
        let under_the_lens: Vec<CommandId> = offered(Writability::Writable, past)
            .iter()
            .map(|command| command.id)
            .collect();
        assert!(
            !under_the_lens.is_empty(),
            "the lens withheld everything, reading included",
        );
        for id in under_the_lens {
            assert!(
                !id.writes_the_document(),
                "{id:?} writes the document, and it is offered under the lens",
            );
        }
    }

    /// The corner cluster's Enter button is enabled by this command's presence,
    /// so it must appear only with a block selected.
    #[test]
    fn entering_a_block_needs_a_block_selected() {
        let mut scene = scene_with_block();
        let nothing: Tool = crate::SelectTool.into();
        assert!(
            !available_for(&mut scene, &nothing, no_history()).contains(CommandId::ExpandBlock),
            "nothing selected: there is no block to enter"
        );
        let block: Tool = ResizeBlock::Selected {
            shape: ShapeId::Rect(block_id(1)),
        }
        .into();
        assert!(available_for(&mut scene, &block, no_history()).contains(CommandId::ExpandBlock));
    }

    /// Exporting a selection writes a standalone diagram, so it is offered for
    /// a block but not for a port — which belongs to a diagram rather than
    /// being one.
    #[test]
    fn only_a_selection_holding_a_block_offers_export() {
        let mut scene = scene_with_block();
        let port = pin_id(3);
        scene.apply(vec![fx::pin_at(
            3,
            Scope::Root,
            "io",
            fx::slot(PinSide::East, 0),
            Rect::from_min_max(pos2(0.0, 0.0), pos2(75.0, 30.0)),
        )]);

        let block_tool: Tool = ResizeBlock::Selected {
            shape: ShapeId::Rect(block_id(1)),
        }
        .into();
        let set = available_for(&mut scene, &block_tool, no_history());
        assert!(set.contains(CommandId::ExportSelection(ExportFormat::Svg)));

        let port_tool: Tool = ResizeBlock::Selected {
            shape: ShapeId::Port(port),
        }
        .into();
        let set = available_for(&mut scene, &port_tool, no_history());
        assert!(
            !set.contains(CommandId::ExportSelection(ExportFormat::Svg)),
            "a port is not a diagram to export"
        );
        // The selection verbs it *does* have are untouched.
        assert!(set.contains(CommandId::Copy));
        assert!(set.contains(CommandId::Delete));
    }

    #[test]
    fn a_selected_block_offers_the_block_verbs_in_overlay_order() {
        let mut scene = scene_with_block();
        let tool: Tool = ResizeBlock::Selected {
            shape: ShapeId::Rect(block_id(1)),
        }
        .into();
        let set = available_for(&mut scene, &tool, no_history());
        let order = [
            CommandId::Copy,
            CommandId::ExportSelection(ExportFormat::Svg),
            CommandId::Cut,
            CommandId::Accent,
            CommandId::ExpandBlock,
            CommandId::Lock,
            CommandId::AddIcon,
            CommandId::RerouteBlock,
            CommandId::FlipLr,
            CommandId::FlipUd,
            CommandId::Delete,
        ];
        for pair in order.windows(2) {
            assert!(
                position(&set, pair[0]) < position(&set, pair[1]),
                "{:?} should precede {:?}",
                pair[0],
                pair[1]
            );
        }
        assert!(!set.contains(CommandId::Unlock));
        assert!(!set.contains(CommandId::PinType));
        assert!(!set.contains(CommandId::Reroute));
    }

    /// Adding an icon needs an image, and the registry says so directly: the
    /// button is not a tool to arm but the effect the shell's picker runs,
    /// already carrying the block it was offered for.
    #[test]
    fn add_icon_asks_for_an_image_for_the_block_it_was_offered_for() {
        let mut scene = scene_with_block();
        let block = block_id(1);
        let tool: Tool = ResizeBlock::Selected {
            shape: ShapeId::Rect(block),
        }
        .into();
        let mut set = available_for(&mut scene, &tool, no_history());

        match set.take(CommandId::AddIcon) {
            Some(Act::Effect(Effect::AddIcon(target))) => {
                assert_eq!(target, block, "the icon was asked for the wrong block");
            }
            other => panic!(
                "Add icon asked for {}",
                other.as_ref().map_or("nothing", act_name)
            ),
        }
    }

    #[test]
    fn a_locked_block_swaps_lock_for_unlock_but_keeps_delete() {
        let mut scene = scene_with_block();
        scene.apply(vec![fx::locked(1)]);
        let tool: Tool = ResizeBlock::Selected {
            shape: ShapeId::Rect(block_id(1)),
        }
        .into();
        let set = available_for(&mut scene, &tool, no_history());
        assert!(set.contains(CommandId::Unlock));
        assert!(!set.contains(CommandId::Lock));
        assert_eq!(set.get(CommandId::Unlock).unwrap().label, "Unlock pins");
        // Locking freezes the interface, not the block's existence.
        assert!(set.contains(CommandId::Delete));
        assert!(set.contains(CommandId::Cut));
    }

    #[test]
    fn a_locked_pin_selection_loses_cut_delete_and_io() {
        let mut scene = scene_with_block();
        // Tags start hidden in the doc fixtures, and which of the pair is
        // offered follows the tag's current state — show it, so the control
        // under test is "Hide Tags".
        scene.apply(vec![fx::pin_tag_shown(2), fx::locked(1)]);
        let tool: Tool = SelectPin::Selected { anchor: pin_id(2) }.into();
        let set = available_for(&mut scene, &tool, no_history());
        assert!(set.contains(CommandId::Copy));
        // A lock freezes the pin interface, not what the pin's tag shows —
        // the emitter agrees (`edit::naming`'s
        // `set_tag_visibility_hides_a_group_and_a_locked_owner_does_not_stop_it`).
        assert!(set.contains(CommandId::HideTags));
        assert!(!set.contains(CommandId::Cut));
        assert!(!set.contains(CommandId::Delete));
        assert!(!set.contains(CommandId::PinType));
    }

    #[test]
    fn arming_add_port_respects_the_current_lock() {
        assert!(arm_available(ToolName::AddPort, InterfaceLock::Unlocked));
        assert!(!arm_available(ToolName::AddPort, InterfaceLock::Locked));
        assert!(arm_available(ToolName::Route, InterfaceLock::Locked));

        let mut scene = scene_with_block();
        let tool: Tool = crate::SelectTool.into();
        let drawing = scene.drawing();
        let set = CommandSet::available(&CommandContext {
            tool: &tool,
            data: &drawing,
            history: no_history(),
            current_lock: InterfaceLock::Locked,
            writability: Writability::Writable,
            saving: blockworx_store::doc::Saving::Withheld,
            viewing: Viewing::Head,
        });
        assert!(!set.contains(CommandId::Arm(ToolName::AddPort)));
        assert!(set.contains(CommandId::Arm(ToolName::Route)));
    }

    /// A container this session may not write withholds every command that
    /// would write it — including the tools that draw. What is left is
    /// looking around: select, navigate, zoom, copy, export.
    #[test]
    fn a_read_only_session_offers_only_the_commands_that_write_nothing() {
        let mut scene = scene_with_block();
        let tool = block_tool();
        let drawing = scene.drawing();
        let set = CommandSet::available(&CommandContext {
            tool: &tool,
            data: &drawing,
            history: History::doc(),
            current_lock: InterfaceLock::Unlocked,
            writability: Writability::ReadOnly,
            saving: blockworx_store::doc::Saving::Withheld,
            viewing: Viewing::Head,
        });
        for withheld in [
            CommandId::Undo,
            CommandId::Redo,
            CommandId::Cut,
            CommandId::Delete,
            CommandId::Rename,
            CommandId::Accent,
            CommandId::SetAccent(Some(3)),
            CommandId::Lock,
            CommandId::Import,
            CommandId::Nudge(Heading::Left),
            CommandId::Arm(ToolName::NewBlock),
            CommandId::Arm(ToolName::Route),
        ] {
            assert!(
                !set.contains(withheld),
                "{withheld:?} is invocable on a read-only container",
            );
        }
        for kept in [
            CommandId::Arm(ToolName::Select),
            CommandId::Copy,
            CommandId::ExpandBlock,
            CommandId::ZoomIn,
            CommandId::FitView,
            CommandId::Export(ExportFormat::Svg),
            CommandId::ExportSelection(ExportFormat::Svg),
        ] {
            assert!(
                set.contains(kept),
                "{kept:?} writes nothing but was withheld",
            );
        }
    }

    /// The arrows reach a selected shape every way, and draw no control.
    #[test]
    fn a_selected_shape_is_nudged_by_name_every_way() {
        let mut scene = scene_with_block();
        let set = available_for(&mut scene, &block_tool(), no_history());
        for heading in Heading::ALL {
            let id = CommandId::Nudge(heading);
            assert!(set.contains(id), "{id:?} not offered to a selected block");
            assert!(
                set.iter_all().any(|cmd| cmd.id == id),
                "{id:?} missing from the registry a front end reads chords against",
            );
            assert!(
                !set.iter_drawn().any(|cmd| cmd.id == id),
                "{id:?} drew a control"
            );
        }
    }

    /// A withheld command is still *drawn* — the overlay grays it out
    /// instead of leaving a hole — but no invoking door reaches it: not a
    /// click's `take`, not a script's `take_by_name`, not a view's
    /// `contains`. Known and untouchable are the same entry.
    #[test]
    fn a_withheld_command_is_drawn_but_cannot_be_invoked() {
        let mut scene = scene_with_block();
        let tool = block_tool();
        let drawing = scene.drawing();
        let mut set = CommandSet::available(&CommandContext {
            tool: &tool,
            data: &drawing,
            history: History::doc(),
            current_lock: InterfaceLock::Unlocked,
            writability: Writability::ReadOnly,
            saving: blockworx_store::doc::Saving::Withheld,
            viewing: Viewing::Head,
        });
        let delete = set
            .iter_drawn()
            .find(|cmd| cmd.id == CommandId::Delete)
            .expect("a selected block draws its Delete control even read-only");
        assert!(delete.withheld());
        assert!(
            !set.iter().any(|cmd| cmd.id == CommandId::Delete),
            "a withheld command leaked into the invocable view",
        );
        let name = CommandId::Delete.name();
        assert!(set.take_by_name(name).is_none(), "taken by name");
        assert!(set.take(CommandId::Delete).is_none(), "taken by id");
    }

    /// Availability follows one list, so a new command has to declare which
    /// side of it it is on — and a *writing* command that claims to write
    /// nothing would sneak past the read-only gate.
    #[test]
    fn every_document_mutating_command_declares_that_it_writes() {
        for (id, _, _) in ACCENTS {
            assert!(id.writes_the_document(), "{id:?}");
        }
        for (id, _, _) in PIN_DIRS {
            assert!(id.writes_the_document(), "{id:?}");
        }
        for id in [
            CommandId::Delete,
            CommandId::Cut,
            CommandId::FlipLr,
            CommandId::FlipUd,
            CommandId::Lock,
            CommandId::Unlock,
            CommandId::Reroute,
            CommandId::RerouteBlock,
            CommandId::ShowTags,
            CommandId::HideTags,
        ] {
            assert!(id.writes_the_document(), "{id:?}");
        }
    }

    #[test]
    fn undo_and_redo_follow_the_history() {
        let mut scene = scene_with_block();
        let tool: Tool = crate::SelectTool.into();
        let set = available_for(
            &mut scene,
            &tool,
            History {
                undo: Some(crate::history::Kind::Doc),
                redo: None,
            },
        );
        assert!(set.contains(CommandId::Undo));
        assert!(!set.contains(CommandId::Redo));
        assert!(set.contains(CommandId::Import));
    }

    /// Taking a rename back or forward writes storage, so it is withheld
    /// wherever an authored step is: on a read-only container and under the
    /// lens.
    #[test]
    fn a_rename_on_the_stack_is_withheld_wherever_writing_is() {
        let mut scene = scene_with_block();
        let tool: Tool = crate::SelectTool.into();
        let renames = History {
            undo: Some(crate::history::Kind::Rename),
            redo: Some(crate::history::Kind::Rename),
        };
        let mut offers = |writability, viewing| {
            let drawing = scene.drawing();
            let set = CommandSet::available(&CommandContext {
                tool: &tool,
                data: &drawing,
                history: renames,
                current_lock: InterfaceLock::Unlocked,
                writability,
                saving: blockworx_store::doc::Saving::Withheld,
                viewing,
            });
            (set.contains(CommandId::Undo), set.contains(CommandId::Redo))
        };
        assert_eq!(
            offers(Writability::Writable, Viewing::Head),
            (true, true),
            "precondition: a writable present offers the rename both ways",
        );
        assert_eq!(
            offers(Writability::ReadOnly, Viewing::Head),
            (false, false),
            "a read-only container offered to rename itself",
        );
        assert_eq!(
            offers(
                Writability::Writable,
                Viewing::Past(blockworx_doc::fixtures::rev(1))
            ),
            (false, false),
            "the lens offered to rename the document",
        );
    }

    #[test]
    fn take_consumes_the_action() {
        let mut scene = scene_with_block();
        let tool: Tool = crate::SelectTool.into();
        let mut set = available_for(&mut scene, &tool, no_history());
        assert!(matches!(
            set.take(CommandId::Import),
            Some(Act::Effect(Effect::Import))
        ));
        assert!(set.take(CommandId::Import).is_none());
    }

    #[test]
    fn a_selection_offers_its_label_editors() {
        let mut scene = scene_with_block();
        let pin = pin_id(2);
        let tool: Tool = ResizeBlock::Selected {
            shape: ShapeId::Rect(block_id(1)),
        }
        .into();
        let set = available_for(&mut scene, &tool, no_history());
        assert!(set.contains(CommandId::Rename));
        assert!(!set.contains(CommandId::Retype));

        let tool: Tool = SelectPin::Selected { anchor: pin }.into();
        let set = available_for(&mut scene, &tool, no_history());
        for id in [CommandId::Rename, CommandId::Retype, CommandId::RenameTag] {
            assert!(set.contains(id), "{id:?} missing for a pin selection");
        }

        // A locked block freezes its pin labels, so the editors vanish.
        scene.apply(vec![fx::locked(1)]);
        let tool: Tool = SelectPin::Selected { anchor: pin }.into();
        let set = available_for(&mut scene, &tool, no_history());
        for id in [CommandId::Rename, CommandId::Retype, CommandId::RenameTag] {
            assert!(!set.contains(id), "{id:?} offered on a locked pin");
        }
    }

    #[test]
    fn every_toolbar_tool_is_bound_and_no_chord_is_shared() {
        let mut chords = std::collections::HashSet::new();
        let mut bound = std::collections::HashSet::new();
        for (chord, id) in BINDINGS {
            assert!(
                chords.insert(format!("{chord:?}")),
                "chord {chord:?} bound twice"
            );
            match id {
                CommandId::Arm(tool) => {
                    assert!(
                        crate::names::on_the_band(*tool),
                        "{tool:?} is not on the band"
                    );
                    bound.insert(*tool);
                }
                // The image cell's command, which arms no tool: it is on the
                // band all the same, and its digit is the cell's.
                CommandId::AddImage => {
                    bound.insert(ToolName::NewImage);
                }
                // The view commands carry no button, so a chord and the
                // palette are their only routes; the history steps have a
                // button on the bar and the chords every editor's hands
                // expect; and search is the one command whose chord *is* its
                // control, since what it opens is the front end's own.
                CommandId::ZoomIn
                | CommandId::ZoomOut
                | CommandId::FitView
                | CommandId::Undo
                | CommandId::Redo
                | CommandId::Search
                // The arrows move a selection, and have no control to press.
                | CommandId::Nudge(_) => {}
                other => panic!(
                    "{other:?} is bound but is neither a cell, a view command nor a history step"
                ),
            }
        }
        // A new band tool must pick a chord (or explicitly opt out here).
        for tool in band_tools() {
            assert!(bound.contains(&tool), "{tool:?} has no key binding");
        }
    }

    /// Zoom and fit depend on nothing in the document, so they are always in
    /// the set — which is what puts them in the palette.
    #[test]
    fn the_view_commands_are_always_available_and_bound() {
        let mut scene = scene_with_block();
        let tool: Tool = crate::SelectTool.into();
        let set = available_for(&mut scene, &tool, no_history());
        for id in [CommandId::ZoomIn, CommandId::ZoomOut, CommandId::FitView] {
            assert!(set.contains(id), "{id:?} missing with nothing selected");
            assert!(binding(id).is_some(), "{id:?} has no chord");
        }
    }

    /// Every constructible id, for exhaustive name checks.
    fn every_id() -> Vec<CommandId> {
        let mut ids: Vec<CommandId> = band_tools().map(band_command).collect();
        ids.extend([
            CommandId::Undo,
            CommandId::Redo,
            CommandId::Copy,
            CommandId::Cut,
            CommandId::HideTags,
            CommandId::ShowTags,
            CommandId::Rename,
            CommandId::RenameType,
            CommandId::Retype,
            CommandId::RenameTag,
            CommandId::EditText,
            CommandId::FlipLr,
            CommandId::FlipUd,
            CommandId::PinType,
            CommandId::Accent,
            CommandId::Reroute,
            CommandId::AddRouteLabel,
            CommandId::ExpandBlock,
            CommandId::GoUp,
            CommandId::Lock,
            CommandId::Unlock,
            CommandId::AddIcon,
            CommandId::RerouteBlock,
            CommandId::Delete,
            CommandId::Import,
        ]);
        for &format in ExportScope::Selection.formats() {
            ids.push(CommandId::ExportSelection(format));
        }
        for &format in ExportScope::View.formats() {
            ids.push(CommandId::Export(format));
        }
        for (id, _, _) in ACCENTS {
            ids.push(id);
        }
        for (id, _, _) in PIN_DIRS {
            ids.push(id);
        }
        ids
    }

    /// A command that answers to its name but draws no control still has to
    /// be *reachable* by that name — that is the whole of its contract, and
    /// the scripted `command` step depends on it.
    #[test]
    fn by_name_only_commands_resolve_but_are_not_offered() {
        let mut scene = scene_for_effects();
        let tool = block_tool();
        let set = available_for(&mut scene, &tool, no_history());
        assert!(
            set.contains(CommandId::SetAccent(Some(3))),
            "accent-3 is not in the set for a block selection",
        );
        assert!(
            !set.iter().any(|c| c.id == CommandId::SetAccent(Some(3))),
            "accent-3 was rendered as a control; nine colours would bury the bar",
        );
        assert!(
            set.iter().any(|c| c.id == CommandId::Accent),
            "the picker that opens them is still a control",
        );

        let mut set = available_for(&mut scene, &tool, no_history());
        assert!(
            set.take_by_name("accent-3").is_some(),
            "a script naming accent-3 must resolve it",
        );
    }

    /// The area tool was spelled `comment` before the rename, and scripted
    /// scripts written against that spelling still run.
    #[test]
    fn the_pre_rename_comment_spelling_still_arms_the_area_tool() {
        let mut scene = scene_for_effects();
        let tool = block_tool();
        assert_eq!(
            CommandId::Arm(ToolName::NewArea).name(),
            "area",
            "the tool's own spelling is the new one",
        );
        let set = available_for(&mut scene, &tool, no_history());
        assert!(
            set.contains(CommandId::Arm(ToolName::NewArea)),
            "the area tool is armable in this scene",
        );

        let mut set = available_for(&mut scene, &tool, no_history());
        let armed = set.take_by_name("comment");
        assert!(
            matches!(armed, Some(Act::Edit(Action::Arm(ToolName::NewArea)))),
            "a script naming `comment` must arm the area tool",
        );
    }

    /// Digits are allowed since the accents became nameable (`accent-3`):
    /// the value is the point of the name, and spelling it out reads worse.
    #[test]
    fn command_names_are_unique_kebab_case_spellings() {
        let mut seen = std::collections::HashSet::new();
        for id in every_id() {
            let name = id.name();
            assert!(seen.insert(name), "duplicate command name {name}");
            assert!(
                name.chars()
                    .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'),
                "{name} is not kebab-case"
            );
        }
    }
    /// Apply one command the way the scripted driver does, and report whether
    /// it authored anything.
    ///
    /// Deliberately not `Scene::commit`: that runs the gesture's solve rider,
    /// which re-solves routes and can change the document all by itself — so a
    /// content-hash assertion around it passes for a command that does nothing.
    /// (It did: neutering `SetBlockLocked` left the first draft of these tests
    /// green.) Measuring the gesture's own ops before the rider is what makes
    /// the claim about the command.
    fn command_authored(scene: &mut Scene, tool: &Tool, id: CommandId, writes: &str) -> bool {
        let action = available_for(scene, tool, no_history())
            .take(id)
            .unwrap_or_else(|| {
                let have: Vec<CommandId> = available_for(scene, tool, no_history())
                    .iter()
                    .map(|command| command.id)
                    .collect();
                panic!("{id:?} is not offered on its fixture; offered: {have:?}")
            });
        let before = scene.doc.clone();
        let (outcome, narrated) = scene.authored(|drawing| apply_scripted(action, drawing));
        assert!(
            matches!(outcome, ScriptedApply::Applied(_)),
            "{id:?} was handed back by the scripted dispatch instead of applied",
        );
        // The kind of write, not merely *a* write: several arms ride a route
        // trim alongside their own edit, so "the gesture is non-empty" is
        // satisfied by the rider even when the command itself does nothing.
        // (It was: deleting `flip_shape_pins` from its arm left an earlier
        // draft of this green, because the trim beside it still authored.)
        if !narrated.iter().any(|line| line.starts_with(writes)) {
            return false;
        }
        assert_ne!(
            scene.doc.clone(),
            before,
            "{id:?} pushed ops that folded to no change",
        );
        true
    }

    /// Availability is only half of a command. The tests above prove *which*
    /// commands a selection offers; this one proves each document-mutating
    /// command, resolved from that same set and applied through the same
    /// [`apply_scripted`] the scripted driver uses, actually writes the
    /// document.
    #[test]
    fn every_document_mutating_command_writes_the_document() {
        /// A command, the selection that offers it, and the narration its
        /// *own* edit must produce.
        type Case = (CommandId, fn() -> Tool, &'static str);
        let cases: Vec<Case> = vec![
            (CommandId::Delete, block_tool, "block"),
            (CommandId::FlipLr, block_tool, "pin"),
            (CommandId::FlipUd, block_tool, "pin"),
            (CommandId::Lock, block_tool, "block"),
            (CommandId::RerouteBlock, block_tool, "route"),
            (CommandId::Reroute, route_tool, "route"),
            (CommandId::ShowTags, pin_group_tool, "pin"),
            // The two rows a popup writes: ordinary commands, so a script
            // can ask for them by name.
            (CommandId::SetAccent(Some(3)), block_tool, "block"),
            (CommandId::SetPinDir(PinDir::Output), pin_group_tool, "pin"),
        ];
        for (id, tool_of, writes) in cases {
            let mut scene = scene_for_effects();
            assert!(
                command_authored(&mut scene, &tool_of(), id, writes),
                "{id:?} is offered by the registry but authored no {writes} edit",
            );
        }
    }

    /// A toggle that only works one way is the drift the paired ids exist to
    /// prevent, so each direction is driven from the state its partner leaves
    /// behind. The fixture's pins start tagged-hidden, hence show-then-hide.
    #[test]
    fn the_reverse_of_each_toggle_writes_the_document_too() {
        for (first, second, tool_of, writes) in [
            (
                CommandId::Lock,
                CommandId::Unlock,
                block_tool as fn() -> Tool,
                "block",
            ),
            (
                CommandId::ShowTags,
                CommandId::HideTags,
                pin_group_tool as fn() -> Tool,
                "pin",
            ),
        ] {
            let mut scene = scene_for_effects();
            let tool = tool_of();
            for id in [first, second] {
                assert!(
                    command_authored(&mut scene, &tool, id, writes),
                    "{id:?} authored no {writes} edit, so the toggle only works one way",
                );
            }
        }
    }
}