blockworx/tools/

commands.rs

//! The command registry: every invocable operation as a [`Command`] — a stable
//! [`CommandId`], a user-facing label, and the [`Action`] it dispatches —
//! 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.
//!
//! 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 blockworx_store::doc::{Saving, Viewing, Writability};

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

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

impl History {
    /// Nothing to take back either way.
    #[cfg(test)]
    pub fn empty() -> Self {
        Self::default()
    }

    /// An edit either way — the stack a session that has been editing holds.
    #[cfg(test)]
    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.
    #[cfg(test)]
    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)]
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,
    /// 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,
    RerouteBlock,
    Delete,
    /// Export the current view.
    Export(ExportFormat),
    Import,
    /// Refresh the attached container's `document.json` (D11).
    Save,
}

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::Json => "export-selection-json",
                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::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::RerouteBlock => "reroute-block",
            CommandId::Delete => "delete",
            CommandId::Export(format) => match format {
                ExportFormat::Svg => "export-svg",
                ExportFormat::Png => "export-png",
                ExportFormat::Json => "export-json",
                ExportFormat::Pdf => "export-pdf",
            },
            CommandId::Import => "import",
            CommandId::Save => "save",
            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::RerouteBlock
            | CommandId::Delete
            | 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::Copy
            | CommandId::ExportSelection(_)
            | CommandId::Export(_)
            | CommandId::ExpandBlock
            | CommandId::GoUp
            | CommandId::ZoomIn
            | CommandId::ZoomOut
            | CommandId::FitView => false,
        }
    }
}

/// One available operation: its identity, the label/hover text a view shows,
/// and the [`Action`] invoking it dispatches.
pub struct Command {
    pub id: CommandId,
    pub label: &'static str,
    pub action: Action,
    /// Where this command rides in the selection overlay. Set once, here, so
    /// the bar and the right-click menu read one policy.
    pub placement: Placement,
    rendered: Rendered,
    authoring: Authoring,
}

/// Where a selection command rides in the overlay: in the bar's row, or
/// behind its ellipsis.
///
/// The user chose the row by name: *"For sure the primary actions should be
/// 'Accent, Expand, Icon, Lock, Rip, flip lr, and flip ud'. The 'copy/cut/
/// delete' can all be put into the overflow menu, as can the 'export to
/// svg'."* — and, of the port's own controls, *"The selection overlay for the
/// port should also put the copy/cut/delete stuff behind the extension, and
/// use the toolbar for the other controls."*
///
/// This replaces §3.5's split-at-five, which cut the list wherever the fifth
/// command happened to fall — so whether Delete sat in the row or behind the
/// ellipsis depended on how many verbs the selected thing answered to. Where
/// a verb rides is a property of the verb, not of how many neighbours it
/// turned out to have (R35).
///
/// Orthogonal to applicability: a command this selection does not offer is
/// simply absent, whichever partition it belongs to.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Placement {
    Inline,
    Overflow,
}

impl Placement {
    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, and items 26 and 27 gave the last two
            // glyphs so they can ride in the row like the rest.
            | CommandId::AddRouteLabel
            | CommandId::HideTags
            | CommandId::ShowTags
            | CommandId::PinType => Placement::Inline,
            // 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.
            _ => Placement::Overflow,
        }
    }
}

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 a command appears as a control, or only answers to its name.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
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 in [`CommandId::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,
}

/// What the explicit projection refresh is called wherever it is offered.
/// Not "Save": there is no save action, and no UI may imply one (invariant
/// 10, playbook R6). What it actually does is rewrite `document.json`, the
/// readable projection beside the log (D11).
pub const REFRESH_PROJECTION: &str = "Refresh document.json";

/// The chord for `key` with the platform command modifier (Ctrl; ⌘ on mac).
const fn chord(key: egui::Key) -> egui::KeyboardShortcut {
    egui::KeyboardShortcut::new(egui::Modifiers::COMMAND, key)
}

/// A bare key, no modifier — how the tool band's digits are pressed (spec §2).
const fn digit(key: egui::Key) -> egui::KeyboardShortcut {
    egui::KeyboardShortcut::new(egui::Modifiers::NONE, 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 for now;
/// selection verbs join here when they earn chords.
///
/// Each band tool answers to two keys: the digit of its place in the row, and
/// the mnemonic chord it has always had (playbook R8). 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: &[(egui::KeyboardShortcut, CommandId)] = &[
    (digit(egui::Key::Num1), CommandId::Arm(ToolName::Select)),
    (chord(egui::Key::E), CommandId::Arm(ToolName::Select)),
    (digit(egui::Key::Num2), CommandId::Arm(ToolName::NewBlock)),
    (chord(egui::Key::B), CommandId::Arm(ToolName::NewBlock)),
    (digit(egui::Key::Num3), CommandId::Arm(ToolName::NewArea)),
    (chord(egui::Key::M), CommandId::Arm(ToolName::NewArea)),
    (digit(egui::Key::Num4), CommandId::Arm(ToolName::AddPort)),
    (chord(egui::Key::P), CommandId::Arm(ToolName::AddPort)),
    (digit(egui::Key::Num5), CommandId::Arm(ToolName::NewImage)),
    (chord(egui::Key::I), CommandId::Arm(ToolName::NewImage)),
    (digit(egui::Key::Num6), CommandId::Arm(ToolName::AddText)),
    (chord(egui::Key::T), CommandId::Arm(ToolName::AddText)),
    (digit(egui::Key::Num7), CommandId::Arm(ToolName::Route)),
    (chord(egui::Key::R), CommandId::Arm(ToolName::Route)),
    // 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(egui::Key::Equals), CommandId::ZoomIn),
    (chord(egui::Key::Plus), CommandId::ZoomIn),
    (chord(egui::Key::Minus), CommandId::ZoomOut),
    (chord(egui::Key::Num0), CommandId::FitView),
];

/// The chord bound to `id`, if any — for the views that print one.
pub fn binding(id: CommandId) -> Option<&'static egui::KeyboardShortcut> {
    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 egui::KeyboardShortcut> {
    BINDINGS
        .iter()
        .filter(move |(_, bound)| *bound == id)
        .map(|(chord, _)| chord)
}

/// Consume any bound chord from the frame's input, returning its command. A
/// reserved chord is consumed even when its command is currently unavailable
/// (a locked block's Add Port), so it can't leak into other handlers.
pub fn consume_binding(ctx: &egui::Context) -> Option<CommandId> {
    BINDINGS
        .iter()
        .find(|(chord, _)| ctx.input_mut(|i| i.consume_shortcut(chord)))
        .map(|(_, id)| *id)
}

/// 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.
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 (§7.1).
    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(
                    CommandId::Arm(tool),
                    tool.label(),
                    Action::SwitchTool(Tool::from_name(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 used to wrap the
        // whole document in a new top: docs/ui-issues-2.md, item 8). 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);
        for &format in ExportScope::View.formats() {
            set.push(
                CommandId::Export(format),
                format.label(),
                Action::Export {
                    format,
                    selection: None,
                },
            );
        }
        set.push(CommandId::Import, "Import", Action::Import);
        if ctx.saving == Saving::Offered {
            set.push_by_name_only(CommandId::Save, REFRESH_PROJECTION, Action::SaveProjection);
        }
        set
    }

    fn selection_commands(&mut self, sel: &Deletable, data: &Drawing<'_>) {
        if let Some(shapes) = sel.shapes() {
            self.push(CommandId::Copy, "Copy", Action::Copy(shapes.clone()));
            // 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()));
            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);
        // Only the pin-bearing shapes have anything to mirror.
        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),
            );
        }
        // 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",
                Action::OpenPinTypePicker { pins: 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",
                Action::OpenRolePicker { 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::SwitchTool(Tool::AddRouteLabel(crate::tools::AddRouteLabel::Armed(
                    *rid,
                ))),
            );
        }
        if let Deletable::Shape(ShapeId::Rect(rid)) = sel {
            self.block_commands(*rid, data);
        }
        // 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<'_>) {
        use crate::tools::{
            EditTextBox, RenameBlockType, RenamePin, RenameTitle, RetypePin, rename_pin::Field,
        };
        if let Deletable::Shape(id) = sel {
            if let Some(tool) = RenameTitle::new_with_shape(data, *id) {
                self.push(CommandId::Rename, "Rename", Action::SwitchTool(tool.into()));
            }
            if let ShapeId::Rect(rid) = id
                && let Some(tool) = RenameBlockType::new_with_rect(data, *rid)
            {
                self.push(
                    CommandId::RenameType,
                    "Rename type",
                    Action::SwitchTool(tool.into()),
                );
            }
            if let ShapeId::Text(tid) = id
                && let Some(tool) = EditTextBox::new_for(data, *tid)
            {
                self.push(
                    CommandId::EditText,
                    "Edit text",
                    Action::SwitchTool(tool.into()),
                );
            }
        }
        // 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 {
            if let Some(tool) = RenamePin::new_with_anchor(data, anchor, Field::Name) {
                self.push(CommandId::Rename, "Rename", Action::SwitchTool(tool.into()));
            }
            if let Some(tool) = RetypePin::new_with_anchor(data, anchor) {
                self.push(CommandId::Retype, "Retype", Action::SwitchTool(tool.into()));
            }
            if let Some(tool) = RenamePin::new_with_anchor(data, anchor, Field::Tag) {
                self.push(
                    CommandId::RenameTag,
                    "Rename tag",
                    Action::SwitchTool(tool.into()),
                );
            }
        }
    }

    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,
            Action::SwitchTool(Tool::Icon(crate::tools::IconTool::Armed(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, action: Action) {
        self.offer(id, label, action, 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, action: Action) {
        self.offer(id, label, action, 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, action: Action, rendered: Rendered) {
        let authoring = if self.allows(id) {
            Authoring::Offered
        } else {
            Authoring::Withheld
        };
        self.available.push(Command {
            id,
            label,
            action,
            placement: Placement::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 — but since R37 they have 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 (§7.2).
    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 (§7.1): 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 == Some(crate::history::Kind::Doc),
            CommandId::Redo => self.history.redo == Some(crate::history::Kind::Doc),
            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)
    }

    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 `id`'s action for dispatch. At most one command fires per frame,
    /// so taking moves the action out rather than cloning it. A withheld
    /// command cannot be taken, however it was named.
    pub fn take(&mut self, id: CommandId) -> Option<Action> {
        let index = self
            .available
            .iter()
            .position(|c| c.id == id && !c.withheld())?;
        Some(self.available.remove(index).action)
    }

    /// [`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<Action> {
        let name = legacy_command_name(name);
        let index = self
            .available
            .iter()
            .position(|c| c.id.name() == name && !c.withheld())?;
        Some(self.available.remove(index).action)
    }
}

/// Pre-rename command spellings, still resolved so scripts written against
/// them keep running.
#[cfg(test)]
fn legacy_command_name(name: &str) -> &str {
    match name {
        "comment" => "area",
        other => other,
    }
}

/// What became of an action offered to [`apply_scripted`]: applied against
/// the drawing — carrying the tool the arm settles on, where it settles one
/// — or handed back because it needs app machinery (clipboard, the undo
/// stack, dialogs, navigation, pickers).
pub enum ScriptedApply {
    Applied(Option<Tool>),
    NeedsApp(Box<Action>),
}

/// Apply the document-scoped subset of [`Action`] — 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(action: Action, drawing: &mut Drawing<'_>) -> ScriptedApply {
    use crate::tools::SelectTool;
    let settles_on = match action {
        // 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.
        Action::SwitchTool(next)
            if next.name().arming_writes_the_document()
                && drawing.authoring() == Authoring::Withheld =>
        {
            None
        }
        Action::SwitchTool(next) => Some(next),
        // 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,
        // An image has to be picked before there is anything to place, and
        // the picker is the app's.
        image @ Action::StampTool {
            tool: ToolName::NewImage,
            ..
        } => return ScriptedApply::NeedsApp(Box::new(image)),
        Action::StampTool { tool, at } => crate::tools::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)
}

/// 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 values, as commands. The picker's own cells (`role_picker`'s
/// `CELLS`): "no accent" plus the eight numbered ones, in the order they are
/// drawn, so `accent-3` on screen and `accent-3` in a script name one colour.
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 directions, as commands, on the same terms as [`ACCENTS`].
const PIN_DIRS: [(CommandId, &str, PinDir); 3] = [
    (CommandId::SetPinDir(PinDir::Input), "Input", PinDir::Input),
    (
        CommandId::SetPinDir(PinDir::Output),
        "Output",
        PinDir::Output,
    ),
    (CommandId::SetPinDir(PinDir::InOut), "In/out", PinDir::InOut),
];

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

/// The [`Action`] variant's own name, for the failure message when a
/// test dispatched something other than what it meant to.
#[cfg(test)]
pub(crate) fn action_name(action: &Action) -> &'static str {
    match action {
        Action::SwitchTool(_) => "SwitchTool",
        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::Camera(_) => "Camera",
        Action::SetRole { .. } => "SetRole",
        Action::SetPinsKind { .. } => "SetPinsKind",
        Action::OpenRolePicker { .. } => "OpenRolePicker",
        Action::OpenPinTypePicker { .. } => "OpenPinTypePicker",
        Action::GoUp => "GoUp",
        Action::NavSelect { .. } => "NavSelect",
        Action::Undo => "Undo",
        Action::Redo => "Redo",
        Action::Nudge { .. } => "Nudge",
        Action::ResetView => "ResetView",
        Action::Export { .. } => "Export",
        Action::ExportRev { .. } => "ExportRev",
        Action::Import => "Import",
        Action::Reroute(_) => "Reroute",
        Action::RerouteBlock(_) => "RerouteBlock",
        Action::ViewRev(_) => "ViewRev",
        Action::ViewHead => "ViewHead",
        Action::TagRev { .. } => "TagRev",
        #[cfg(not(target_arch = "wasm32"))]
        Action::SaveProjection => "SaveProjection",
        // The File flow is app chrome: a script has no dialogs to drive.
        #[cfg(not(target_arch = "wasm32"))]
        Action::NewDocument => "NewDocument",
        #[cfg(not(target_arch = "wasm32"))]
        Action::PickFile(_) => "PickFile",
        #[cfg(not(target_arch = "wasm32"))]
        Action::OpenRecent(_) => "OpenRecent",
        #[cfg(not(target_arch = "wasm32"))]
        Action::RenameDocument(_) => "RenameDocument",
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::{
        tools::{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::tools::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::tools::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. It used to be offered everywhere and *wrap the document* at
    /// the root: a navigation button that quietly wrote a block
    /// (docs/ui-issues-2.md, item 8).
    #[test]
    fn rising_a_level_is_offered_everywhere_but_the_document_root() {
        let tool: Tool = crate::tools::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));
    }

    /// R37 leaves the lens with no writing command at all: under it a
    /// writable container offers exactly what a read-only one does. Restore
    /// was the single exception, and the way out of the past is now 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::tools::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::tools::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::FlipLr,
            CommandId::FlipUd,
            CommandId::Accent,
            CommandId::ExpandBlock,
            CommandId::Lock,
            CommandId::AddIcon,
            CommandId::RerouteBlock,
            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));
    }

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

    /// 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::tools::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));
    }

    #[test]
    fn take_consumes_the_action() {
        let mut scene = scene_with_block();
        let tool: Tool = crate::tools::SelectTool.into();
        let mut set = available_for(&mut scene, &tool, no_history());
        assert!(matches!(set.take(CommandId::Import), Some(Action::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::tools::names::on_the_band(*tool),
                        "{tool:?} is not on the band"
                    );
                    bound.insert(*tool);
                }
                // The view commands carry no button: a chord and the palette
                // are their only routes.
                CommandId::ZoomIn | CommandId::ZoomOut | CommandId::FitView => {}
                other => panic!("{other:?} is bound but is neither a tool nor a view command"),
            }
        }
        // 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::tools::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");
        }
    }

    #[test]
    fn bound_chords_consume_from_the_input() {
        let ctx = egui::Context::default();
        let press = |key| egui::RawInput {
            events: vec![egui::Event::Key {
                key,
                physical_key: None,
                pressed: true,
                repeat: false,
                modifiers: egui::Modifiers::COMMAND,
            }],
            ..Default::default()
        };
        ctx.run_ui(press(egui::Key::B), |ui| {
            assert_eq!(
                consume_binding(ui.ctx()),
                Some(CommandId::Arm(ToolName::NewBlock))
            );
            // Consumed: a second scan finds nothing.
            assert_eq!(consume_binding(ui.ctx()), None);
        })
        .drop_without_applying_deltas();
        ctx.run_ui(press(egui::Key::Z), |ui| {
            assert_eq!(consume_binding(ui.ctx()), None, "ctrl-z is not a binding");
        })
        .drop_without_applying_deltas();
    }

    /// Every constructible id, for exhaustive name checks.
    fn every_id() -> Vec<CommandId> {
        let mut ids: Vec<CommandId> = band_tools().map(CommandId::Arm).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(Action::SwitchTool(t)) if t.name() == 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 that used to be written from inside a popup, and
            // so could not be driven at all. They are ordinary commands now.
            (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",
                );
            }
        }
    }
}