blockworx_editor/widget/

drawing.rs

//! [`Drawing`]: the editing surface for one level of the document.
//!
//! This module holds the view itself — construction, the per-kind accessors that
//! add, read, and edit shapes, deletion, and the broad-phase candidate queries.
//! The rest of the surface lives in sibling modules, each carrying its own
//! `impl Drawing` block:
//!
//! - [`hit_target`](crate::widget::hit_target) — what sits at a point, in z-order.
//! - [`clipboard`](crate::widget::clipboard) — copy, cut, and paste.
//! - [`routing`](crate::widget::routing) — solving and re-solving a level's wires.
//! - [`movement`](crate::widget::movement) — moving shapes and the routes that follow.

/// Paint-layer precedence of a shape, matching [`Drawing::shapes`] order
/// (blocks, ports, texts, images) with areas last. Paired with the
/// entity's write order it reproduces that walk exactly, which is how the
/// index-limited candidate list and the linear scan stay one order.
fn shape_layer_rank(id: ShapeId) -> u8 {
    match id {
        ShapeId::Rect(_) => 0,
        ShapeId::Port(_) => 1,
        ShapeId::Text(_) => 2,
        ShapeId::Image(_) => 3,
        ShapeId::Area(_) => 4,
        // Icons have their own foreground hit-test (`icon_at_pos`) and never enter
        // the shared candidate scan, so this rank is never actually consulted.
        ShapeId::Icon(_) => 5,
    }
}

/// The entity a shape names to the delete cascade. An icon has none — it is
/// a value on its block, not an entity, so it is zeroed rather than
/// deleted.
fn title_target(id: ShapeId) -> Option<crate::edit::naming::TitleTarget> {
    use crate::edit::naming::TitleTarget;
    match id {
        ShapeId::Rect(id) => Some(TitleTarget::Block(id)),
        ShapeId::Area(id) => Some(TitleTarget::Area(id)),
        ShapeId::Port(_) | ShapeId::Text(_) | ShapeId::Image(_) | ShapeId::Icon(_) => None,
    }
}

fn delete_target(id: ShapeId) -> Option<crate::edit::delete::Target> {
    use crate::edit::delete::Target;
    Some(match id {
        ShapeId::Rect(id) => Target::Block(id),
        ShapeId::Port(id) => Target::Pin(id),
        ShapeId::Text(id) => Target::Text(id),
        ShapeId::Area(id) => Target::Area(id),
        ShapeId::Image(id) => Target::Image(id),
        ShapeId::Icon(_) => return None,
    })
}

use blockworx_doc::{
    block_model::{Area, Asset, Block, Icon, Image, Pin, Route, Text},
    commit::CommitBuilder,
    document::{BlockIndex, Document as DocDocument, IndexedDocument, chronological},
    entity::Entity,
    geometry::{PinSlot, Waypoint},
    hash::AssetHash,
    id::{Allocator, AreaId, BlockId, Id, IdKind, ImageId, PinId, RouteId, RouteLabelId, TextId},
    values::PinDir,
};
use blockworx_geom::{Pos2, Rect};

use crate::edit::naming::Authoring;
use crate::render::Course;
use crate::theme::Style;
use crate::{
    edit::{
        self,
        geometry::PinMove,
        naming::{InterfaceLock, LabelFitWidth, TagVisibility},
    },
    grid::{artwork_rect, pin_slot},
    path::BlockPath,
    shape::{BlockShape, Deletable, PinLocation, PortShape, RoleTarget, ShapeId, ShapeRef},
    widget::{
        auto_route::{Crossing, RouteGeometry, Wire, route_labels},
        spatial::{HitId, SpatialIndex},
    },
};
use blockworx_paint::Renderer;

/// The slot a boundary offset in world pixels names.
fn slot_at(location: PinLocation) -> PinSlot {
    PinSlot {
        side: location.side,
        offset: pin_slot(location.offset),
    }
}

/// What [`Drawing::standing_conflicts`] marks, in world space.
#[derive(Default, Debug)]
pub(crate) struct Conflicts {
    /// Where two routing shapes share cells.
    pub overlaps: Vec<Rect>,
    /// Where a wire runs through a routing shape, grown half a cell so the
    /// draw pass has an area to hatch.
    pub crossings: Vec<Rect>,
}

/// Whether wires route around `id`: the blocks and the ports.
fn is_routing(id: ShapeId) -> bool {
    matches!(id, ShapeId::Rect(_) | ShapeId::Port(_))
}

/// What a preview draws this frame that the document does not hold:
/// shapes at hypothetical rects, and the routes re-solved against them. The
/// cull set and the conflict pass read it — the spatial index holds committed
/// rects, so a shape whose committed rect is off screen must still draw when
/// its preview is on screen, and is marked where it is dragged — and a
/// [`Drawing`] is one frame, so a preview cannot outlive the frame that made
/// it.
#[derive(Default)]
pub(crate) struct Previewed {
    shapes: Vec<(ShapeId, Rect)>,
    routes: Vec<RouteId>,
}

/// A transient view onto one scope of the document. Reads project the
/// scope's entities out of `indexed`; writes are emitted into `sink` and
/// only become document state when the gesture seals and submits.
pub struct Drawing<'a> {
    /// The session's prediction. Reads go through [`Drawing::indexed`],
    /// which overlays whatever the gesture has already authored — never
    /// this field directly, which is what makes a gesture able to read its
    /// own writes.
    base: IndexedDocument<'a>,
    path: &'a BlockPath,
    /// Optional spatial index over the current level's hittables, for broad-phase
    /// viewport culling and hit-testing. Built and cached by `App`; `None` on the
    /// paths that don't need it (SVG export, tests, popups), where queries fall
    /// back to a full linear scan with identical results.
    index: Option<&'a SpatialIndex>,
    /// The document's derived state — solver geometry, measurement caches,
    /// propagated accents. Mandatory where the index is optional: derived
    /// state has no linear-scan fallback, and the solver passes that fill
    /// it run inside `Drawing` methods, so it rides every borrow.
    pub(super) presentation: &'a mut crate::presentation::Presentation,
    /// The gesture in progress. Private, and reachable only through
    /// [`Drawing::author`]: a tool cannot hold the sink, and a write cannot
    /// skip advancing the prediction the next read will see.
    gesture: &'a mut crate::gesture::Gesture,
    previewed: Previewed,
}

/// A committed title/type-label placement: the resolved offset (world px
/// — grid-rounded and clamped by the caller, who owns the text metrics)
/// and the side the release height chose, when it chose one.
#[derive(Clone, Copy, Debug)]
pub struct LabelPlacement {
    pub offset: f32,
    pub side: Option<blockworx_doc::values::LabelSide>,
}

impl From<LabelPlacement> for edit::naming::LabelPlacement {
    fn from(placement: LabelPlacement) -> Self {
        edit::naming::LabelPlacement {
            offset: placement.offset.into(),
            side: placement.side,
        }
    }
}

/// Prepare the whole document to be looked at: turn what the document
/// *authors* into what the canvas *shows*.
///
/// A route's full path is stored as its corner waypoints, never as solved edge
/// geometry, so every scope's wires are *reconstructed* from those corners — straight legs drawn
/// directly, only genuinely blocked/non-colinear legs routed (see
/// [`Drawing::reconstruct_routes`]). A clean document is rebuilt with zero
/// pathfinding, so persisted and hand-adjusted geometry survives unchanged.
/// This runs for *all* scopes, not just the current view: navigation does not
/// re-reconstruct, and a foreign commit can land anywhere.
///
/// Read-only — the sink it opens is local and discarded, because preparing a
/// document to be looked at has nothing to author. Call it through
/// [`Presentation::refresh_routes`](crate::presentation::Presentation::refresh_routes),
/// which owns the stamp gate.
/// Reconstruct one scope's wires, and only the ones `reconstructing` names —
/// what a commit that knows what it disturbed needs, and what a preview's next
/// borrow needs to take its supposition back. [`present_document`] is what an
/// open or a foreign commit needs, which is everything.
pub(crate) fn reconstruct_scope(
    indexed: &IndexedDocument<'_>,
    presentation: &mut crate::presentation::Presentation,
    path: &BlockPath,
    reconstructing: crate::widget::routing::Reconstructing<'_>,
) {
    presentation.keep_routes(|id| indexed.doc.route(&id).is_some());
    let mut discarded = crate::gesture::Gesture::idle();
    Drawing::new(*indexed, path, presentation, &mut discarded)
        .reconstruct_routes_reaching(reconstructing);
    debug_assert!(
        discarded.ops().is_empty(),
        "reconstruction is a read; it must author nothing"
    );
}

pub(crate) fn present_document(
    indexed: &IndexedDocument<'_>,
    presentation: &mut crate::presentation::Presentation,
) {
    // A deleted wire has no geometry, and dropping it here is what keeps
    // the map from outliving the document (the removal and the deletion were
    // one statement before the deletion became an op).
    presentation.keep_routes(|id| indexed.doc.route(&id).is_some());
    let mut discarded = crate::gesture::Gesture::idle();
    for path in wired_scopes(indexed) {
        Drawing::new(*indexed, &path, presentation, &mut discarded).reconstruct_routes();
    }
    debug_assert!(
        discarded.ops().is_empty(),
        "reconstruction is a read; it must author nothing"
    );
}

/// Every level that holds wires, as the path a drawing of it opens on.
fn wired_scopes(indexed: &IndexedDocument<'_>) -> Vec<BlockPath> {
    indexed
        .index
        .blocks
        .iter()
        .filter(|(_, entry)| !entry.routes.is_empty())
        .map(|(&id, _)| {
            let mut path = BlockPath::empty();
            if let crate::path::Scope::Block(id) = crate::path::Scope::from_wire(id) {
                path.push(id);
            }
            path
        })
        .collect()
}

/// How many solves a document may take to stop moving its corners.
const SETTLING_PASSES: usize = 8;

/// `document` with every wire's corners stored as the solve leaves them once
/// it has nothing more to promote — what the solve rider converges on over a
/// document's seals, and so what one the editor saved carries. A single solve
/// is not enough: corners promoted from a bare wire re-solve differently from
/// the wire they came from.
///
/// # Errors
/// A settling the document refuses to fold.
pub fn settle_corners(
    mut document: blockworx_doc::document::Document,
) -> Result<blockworx_doc::document::Document, blockworx_doc::document::FoldError> {
    for _ in 0..SETTLING_PASSES {
        let Some(commit) = settling_pass(&document) else {
            break;
        };
        document = document.try_apply(&commit)?;
    }
    Ok(document)
}

/// One solve of every wired level, as the commit its promoted corners make.
/// `None` when it promotes nothing new.
fn settling_pass(
    document: &blockworx_doc::document::Document,
) -> Option<blockworx_doc::commit::Commit> {
    let mut index = blockworx_doc::document::DocIndex::of(document);
    let indexed = index.view(document);
    let mut presentation = crate::presentation::Presentation::default();
    present_document(&indexed, &mut presentation);
    let mut settled = blockworx_doc::commit::CommitBuilder::new("Settled every wire's corners");
    for path in wired_scopes(&indexed) {
        crate::widget::routing::settle_scope(&indexed, &path, &presentation, &mut settled);
    }
    settled.seal()
}

#[cfg(test)]
mod settling {
    use blockworx_doc::fixtures::scale::build_scale;

    use super::{settle_corners, settling_pass};

    /// A generated grid stores no corners; settled, its turning wires carry
    /// them, and one more solve finds nothing left to store.
    #[test]
    fn a_settled_document_is_a_fixed_point_of_the_solve() {
        let generated = build_scale(3);
        assert!(
            generated
                .routes()
                .all(|(_, route)| route.waypoints.is_empty()),
            "precondition: the grid is generated without corners",
        );
        let settled = settle_corners(generated).expect("the settling folds");
        assert!(
            settled
                .routes()
                .any(|(_, route)| !route.waypoints.is_empty())
        );
        let again = settling_pass(&settled);
        assert!(
            again.is_none(),
            "the settled document still moves under the solve: {:?}",
            again.map(|commit| commit
                .ops()
                .iter()
                .map(|op| op.narrate())
                .collect::<Vec<_>>()),
        );
    }
}

impl<'a> Drawing<'a> {
    pub fn new(
        base: IndexedDocument<'a>,
        path: &'a BlockPath,
        presentation: &'a mut crate::presentation::Presentation,
        gesture: &'a mut crate::gesture::Gesture,
    ) -> Self {
        let view = gesture.view(base);
        presentation.refresh_accents(&view);
        presentation.refresh_routes(&view);
        Self {
            base,
            path,
            index: None,
            presentation,
            gesture,
            previewed: Previewed::default(),
        }
    }

    /// The document as this gesture has left it: the session's prediction
    /// with the gesture's own ops folded on. Every read goes through here,
    /// so a tool that just created a block can name it in the same frame.
    pub(super) fn indexed(&self) -> IndexedDocument<'_> {
        self.gesture.view(self.base)
    }

    /// [`Self::indexed`] and the presentation together, borrowing only the
    /// fields each reads — for a pass that fills solved geometry while
    /// reading the document it was solved from.
    pub(super) fn split(
        &mut self,
    ) -> (IndexedDocument<'_>, &mut crate::presentation::Presentation) {
        (self.gesture.view(self.base), self.presentation)
    }

    /// Whether this session may write at all — the answer the sink itself
    /// gives, so what the tools offer and what the write door accepts come
    /// from one value.
    pub fn writability(&self) -> blockworx_store::doc::Writability {
        self.gesture.writability()
    }

    /// Whether the add-affordances that belong to no particular shape — the
    /// route-start targets, a wire's handles — are on offer this frame.
    pub fn authoring(&self) -> Authoring {
        self.writability().into()
    }

    /// Whether `shape`'s own add-affordances are on offer: the session must
    /// be writable *and* the shape's interface unlocked.
    pub fn authoring_of(&self, shape: ShapeId) -> Authoring {
        Authoring::of(self.writability(), self.shape_owner_locked(shape).into())
    }

    /// The proof a material interface edit needs on `block`, or `None` when
    /// the lock refuses one — the read half of `crate::edit::lock`, for a
    /// tool that must decide before it commits.
    pub fn unlocked_scope(&self, block: BlockId) -> Option<edit::lock::UnlockedScope> {
        edit::lock::UnlockedScope::of(&self.indexed(), crate::path::Scope::Block(block))
    }

    /// A fresh document-global id, taken from the document's marks as this
    /// gesture has left them. The tools take the minted id back, so a
    /// gesture can anchor to what it just made.
    pub fn mint<K: IdKind>(&mut self) -> Id<K> {
        self.gesture.mint(self.base.doc)
    }

    /// The allocator an emitter mints a data-dependent number of ids from
    /// (paste). Every other creating emitter takes its ids pre-minted.
    pub(super) fn ids(&self) -> Allocator {
        self.gesture.ids(self.base.doc)
    }

    /// Author into the gesture. The one write door in the waist: `emit`
    /// receives the document as [`Self::indexed`] would report it and the
    /// sink to push into, and the prediction advances before it returns.
    pub(super) fn author(
        &mut self,
        what: &'static str,
        emit: impl FnOnce(&IndexedDocument<'_>, &mut CommitBuilder),
    ) {
        self.gesture.author(self.base, what, emit);
    }

    /// Like [`Self::new`], but with a spatial index (see the `index` field) so
    /// broad-phase queries (culling, hit-testing) skip the full linear scan.
    pub fn new_indexed(
        base: IndexedDocument<'a>,
        path: &'a BlockPath,
        index: &'a SpatialIndex,
        presentation: &'a mut crate::presentation::Presentation,
        gesture: &'a mut crate::gesture::Gesture,
    ) -> Self {
        let view = gesture.view(base);
        presentation.refresh_accents(&view);
        presentation.refresh_routes(&view);
        Self {
            base,
            path,
            index: Some(index),
            presentation,
            gesture,
            previewed: Previewed::default(),
        }
    }

    /// The scope being drawn: the path's last segment, or the document
    /// root, which is a scope like any other.
    pub fn current_scope(&self) -> crate::path::Scope {
        self.path.scope()
    }

    /// What the current scope holds. `None` only when the scope's block
    /// has been deleted under the path.
    pub(super) fn scope(&self) -> Option<&BlockIndex> {
        self.indexed().index.scope(self.current_scope().wire_id())
    }

    /// The block whose interior is being drawn, or `None` at the document
    /// root — which has a scope but no block entity behind it.
    pub(super) fn current(&self) -> Option<&Block> {
        self.current_scope()
            .block()
            .and_then(|id| self.held_block(id))
    }

    pub(super) fn held_block(&self, id: BlockId) -> Option<&Block> {
        self.indexed().doc.block(&id)
    }

    pub fn held_pin(&self, id: PinId) -> Option<&Pin> {
        self.indexed().doc.pin(&id)
    }

    /// Which shape draws `pin` in this scope: the scope's own boundary port,
    /// or a stub on the child block that owns it. The port-vs-pin split is
    /// resolved here, once, from the ownership the document records.
    pub fn pin_shape(&self, pin: PinId) -> Option<ShapeId> {
        let owner = self.held_pin(pin)?.owner;
        Some(
            if crate::path::Scope::from_wire(owner) == self.current_scope() {
                ShapeId::Port(pin)
            } else {
                ShapeId::Rect(owner)
            },
        )
    }

    /// A child block as the geometry layer draws it — body plus the pins that
    /// hang off it. The one unwrap of [`Self::shape`]'s block arm, so callers
    /// reaching for `BaseShape`'s block-only methods do not each spell it.
    pub fn block_shape(&self, id: BlockId) -> Option<BlockShape<'_>> {
        match self.shape(ShapeId::Rect(id))? {
            ShapeRef::Block(block) => Some(block),
            _ => None,
        }
    }

    /// The shape drawing `pin` here, paired with the pin entity: the stub's
    /// geometry hangs off the shape, its labels off the pin, and every
    /// pin-level read wants both.
    pub fn pin_on_shape(&self, pin: PinId) -> Option<(ShapeRef<'_>, &Pin)> {
        Some((self.shape(self.pin_shape(pin)?)?, self.held_pin(pin)?))
    }

    /// Whether the block that owns `pin` is locked. A locked block keeps
    /// its pin/port interface frozen, so callers consult this before any
    /// material pin edit.
    pub fn pin_owner_locked(&self, pin: PinId) -> bool {
        self.held_pin(pin)
            .and_then(|pin| self.held_block(pin.owner))
            .is_some_and(|owner| owner.locked)
    }

    /// Whether the current block (whose ports these are) is locked. The
    /// document root is never locked — there is no block to freeze.
    pub fn current_locked(&self) -> bool {
        self.current().is_some_and(|b| b.locked)
    }

    /// Whether the block that owns `id`'s pins is locked: a child block by its own
    /// flag, a port by the current block's flag. Shapes without a pin interface
    /// (text, area, image) are never locked.
    pub fn shape_owner_locked(&self, id: ShapeId) -> bool {
        match id {
            ShapeId::Rect(rid) => self.held_block(rid).is_some_and(|b| b.locked),
            ShapeId::Port(_) => self.current_locked(),
            ShapeId::Text(_) | ShapeId::Area(_) | ShapeId::Image(_) | ShapeId::Icon(_) => false,
        }
    }

    /// The derived pin-accent lookup for the shapes of this scope: every
    /// stub drawn here takes its color from the wires routed here, whether
    /// it belongs to a child block or to the scope's own boundary.
    pub fn shape_accents(&self) -> crate::presentation::ShapeAccents<'_> {
        crate::presentation::ShapeAccents::new(self.current_scope(), &self.presentation.pin_accents)
    }

    // ── Scope reads ──────────────────────────────────────────────────────────
    //
    // What this scope holds, resolved out of the index and handed to the
    // geometry layer, which never looks anything up itself.

    /// `ids` resolved to their entities in `chronological` order — the
    /// doc crate's one draw-order policy, so painting, hit-testing, and the
    /// router cannot disagree about which shape is on top.
    fn ordered<'s, K, T>(
        &'s self,
        ids: impl IntoIterator<Item = Id<K>>,
        lookup: impl Fn(&'s DocDocument, &Id<K>) -> Option<&'s T>,
    ) -> Vec<(Id<K>, &'s T)>
    where
        K: IdKind + Ord + Copy,
        T: Entity + 's,
    {
        let doc = self.indexed().doc;
        let held = |id: &Id<K>| lookup(doc, id);
        let entries: Vec<(Id<K>, &T)> = ids
            .into_iter()
            .filter_map(|id| Some((id, held(&id)?)))
            .collect();
        chronological(entries.iter().copied())
            .into_iter()
            .filter_map(|id| Some((id, held(&id)?)))
            .collect()
    }

    /// The scope's child blocks, in draw order.
    pub fn child_blocks(&self) -> Vec<(BlockId, &Block)> {
        crate::path::child_blocks(&self.indexed(), self.current_scope())
            .into_iter()
            .filter_map(|id| Some((id, self.held_block(id)?)))
            .collect()
    }

    /// One child block of this scope. A block the scope does not hold is not
    /// this drawing's to read, even though the document holds it.
    pub fn block(&self, id: BlockId) -> Option<&Block> {
        self.scope()?
            .children
            .contains(&id)
            .then(|| self.held_block(id))
            .flatten()
    }

    /// A scope's own pins, in draw order — the set the geometry layer is
    /// handed alongside the block (or, at the root, the document's own
    /// boundary), since a pin is its own entity.
    pub(super) fn block_pins(&self, scope: crate::path::Scope) -> Vec<(PinId, &Pin)> {
        let Some(entry) = self.indexed().index.scope(scope.wire_id()) else {
            return Vec::new();
        };
        self.ordered(entry.pins.iter().copied(), |doc, id| doc.pin(id))
    }

    fn scope_texts(&self) -> Vec<(TextId, &Text)> {
        let Some(scope) = self.scope() else {
            return Vec::new();
        };
        self.ordered(scope.texts.iter().copied(), |doc, id| doc.text(id))
    }

    fn scope_areas(&self) -> Vec<(AreaId, &Area)> {
        let Some(scope) = self.scope() else {
            return Vec::new();
        };
        self.ordered(scope.areas.iter().copied(), |doc, id| doc.area(id))
    }

    fn scope_images(&self) -> Vec<(ImageId, &Image)> {
        let Some(scope) = self.scope() else {
            return Vec::new();
        };
        self.ordered(scope.images.iter().copied(), |doc, id| doc.image(id))
    }

    /// Whether this scope holds what `owner` names. A scope whose block has
    /// been deleted under the path holds nothing, which is what keeps a
    /// single lookup agreeing with a walk of the index's per-scope sets.
    fn scope_owns(&self, owner: BlockId) -> bool {
        self.scope().is_some() && crate::path::Scope::from_wire(owner) == self.current_scope()
    }

    /// An entity, iff this scope owns it. Ownership is the `owner`
    /// register, which is what the index's per-scope sets are built from —
    /// so this answers the same question as a scan of them, in one lookup.
    fn scope_owned<'s, T: Entity>(
        &'s self,
        entity: Option<&'s T>,
        owner: impl Fn(&T) -> BlockId,
    ) -> Option<&'s T> {
        entity.filter(|entity| self.scope_owns(owner(entity)))
    }

    /// The bytes an asset hash names, or `None` when the document does not
    /// hold them — which the zero icon's null hash also reads as.
    fn asset(&self, hash: &AssetHash) -> Option<&Asset> {
        self.indexed().doc.asset(hash)
    }

    /// Delete a shape or route. The cascade — a block's subtree, the wires
    /// landing on any pin it carries, each wire's labels — is the delete
    /// emitter's own closure, so one selection is one commit however deep
    /// it reaches.
    pub fn delete(&mut self, what: Deletable) {
        let targets: Vec<edit::delete::Target> = match what {
            Deletable::Shape(id) => self.shape_targets(&[id]),
            Deletable::Shapes(ids) => self.shape_targets(&ids),
            Deletable::Route(rid) => vec![edit::delete::Target::Route(rid)],
            Deletable::Pins(pins) => pins.into_iter().map(edit::delete::Target::Pin).collect(),
        };
        self.author("delete", |indexed, sink| {
            edit::delete::selection(indexed, &targets, sink);
        });
    }

    /// The entities `shapes` name, zeroing every icon among them on the way:
    /// an icon is a value on its block, so it has no id for the cascade to
    /// delete and its own emitter clears it instead.
    fn shape_targets(&mut self, shapes: &[ShapeId]) -> Vec<edit::delete::Target> {
        for &id in shapes {
            if let ShapeId::Icon(block) = id {
                self.author("shape_targets", |indexed, sink| {
                    edit::assets::delete_icon(indexed.doc, block, sink);
                });
            }
        }
        shapes.iter().filter_map(|&id| delete_target(id)).collect()
    }

    // ── Route accessors ──────────────────────────────────────────────────────

    /// The scope's wires, in draw order — the doc crate's one
    /// `chronological` policy, so painting, hit-testing, and the crossing
    /// pass all walk the same sequence.
    #[tracing::instrument(level = "info", skip_all)]
    pub(super) fn scope_route_ids(&self) -> Vec<RouteId> {
        let Some(scope) = self.scope() else {
            return Vec::new();
        };
        let doc = self.indexed().doc;
        let held: Vec<(RouteId, &Route)> = scope
            .routes
            .iter()
            .filter_map(|&id| Some((id, doc.route(&id)?)))
            .collect();
        chronological(held.iter().copied())
    }

    pub(super) fn route(&self, id: RouteId) -> Option<&Route> {
        self.indexed().doc.route(&id)
    }

    pub fn auto_routes(&self) -> impl Iterator<Item = (RouteId, Wire<'_>)> {
        self.scope_route_ids()
            .into_iter()
            .filter_map(|id| Some((id, self.auto_route(id)?)))
            .collect::<Vec<_>>()
            .into_iter()
    }

    /// One wire of this scope: the authored route bundled with the labels
    /// the index hangs off it. A route the scope does not hold is not this
    /// drawing's to read, even though the document holds it.
    pub fn auto_route(&self, id: RouteId) -> Option<Wire<'_>> {
        let route = self
            .route(id)
            .filter(|route| self.scope_owns(route.owner))?;
        Some(Wire {
            route,
            labels: route_labels(&self.indexed(), id),
        })
    }
    /// Wire `from` to `to` along the solved `waypoints`, in this scope. A
    /// destination the gesture drew onto a free slot arrives as
    /// [`RouteEnd::Fresh`](crate::edit::create::RouteEnd::Fresh) and is
    /// stamped in the same commit; an owner that refuses it takes the wire
    /// with it.
    pub fn add_route(
        &mut self,
        from: PinId,
        to: crate::edit::create::RouteEnd,
        waypoints: Vec<Waypoint>,
    ) -> RouteId {
        let id = self.mint();
        let owner = self.current_scope();
        self.author("add_route", |indexed, sink| {
            edit::create::route(
                indexed,
                edit::create::NewRoute {
                    id,
                    owner,
                    from,
                    to,
                    waypoints,
                },
                sink,
            );
        });
        id
    }
    /// The solved geometry beside `id`, or `None` for a route that has not
    /// been reconstructed — nothing to draw or hit-test yet.
    pub fn route_geometry(&self, id: RouteId) -> Option<&RouteGeometry> {
        self.presentation.routes.get(&id)
    }

    // ── Image (background image) accessors ───────────────────────────────────

    /// Create a free-floating background image with `asset` as its content,
    /// boxed by `placement`, returning its id as a `ShapeId`.
    pub fn add_image(&mut self, placement: edit::assets::Placement, asset: &Asset) -> ShapeId {
        let id: ImageId = self.mint();
        let owner = self.current_scope();
        self.author("add_image", |indexed, sink| {
            edit::assets::image(
                indexed.doc,
                edit::assets::NewImage {
                    id,
                    owner,
                    placement,
                },
                asset,
                sink,
            );
        });
        ShapeId::Image(id)
    }
    #[cfg_attr(not(test), allow(dead_code))]
    pub fn image(&self, id: ImageId) -> Option<&Image> {
        self.scope_owned(self.indexed().doc.image(&id), |i| i.owner)
    }

    // ── Icon (block foreground image) accessors ───────────────────────────────

    /// The artwork block `id` carries, or `None` for the zero icon — an
    /// empty box with the null asset is "no image", not a blank picture.
    pub fn icon(&self, id: BlockId) -> Option<&Icon> {
        self.block(id)
            .and_then(|b| crate::edit::geometry::artwork(&b.icon))
    }
    /// Attach (or replace) block `id`'s icon with `asset`, sized to a default
    /// box centered on the block.
    pub fn set_icon(&mut self, id: BlockId, asset: &Asset) {
        self.author("set_icon", |indexed, sink| {
            edit::assets::set_icon(indexed.doc, id, asset, sink);
        });
    }

    // ── Block (rect) accessors ────────────────────────────────────────────────

    pub fn add_block(&mut self, start: Pos2, end: Pos2) -> BlockId {
        let id = self.mint();
        let scope = self.current_scope();
        self.author("add_block", |indexed, sink| {
            edit::create::block(
                indexed.doc,
                edit::create::NewBlock {
                    id,
                    scope,
                    start,
                    end,
                },
                sink,
            );
        });
        id
    }
    /// Alias kept for callers that haven't been updated yet.
    pub fn add_rect_box(&mut self, start: Pos2, end: Pos2) -> BlockId {
        self.add_block(start, end)
    }

    // ── Text box accessors ────────────────────────────────────────────────────

    /// Create an empty, default-sized text box with its top-left corner at
    /// `pos`, returning its freshly assigned id. The caller typically follows up
    /// by opening the text editor on the returned box.
    pub fn add_text_box(&mut self, pos: Pos2) -> TextId {
        let id = self.mint();
        let scope = self.current_scope();
        self.author("add_text_box", |_indexed, sink| {
            edit::create::text_box(id, scope, pos, sink);
        });
        id
    }
    pub fn text_box(&self, id: TextId) -> Option<&Text> {
        self.scope_owned(self.indexed().doc.text(&id), |t| t.owner)
    }

    // ── Area accessors ─────────────────────────────────────────────────────

    /// Create a boundary area covering the drag rectangle `start..end`,
    /// returning its id as a `ShapeId`. The caller (the `NewArea` tool)
    /// typically selects it afterwards.
    pub fn add_area(&mut self, start: Pos2, end: Pos2) -> ShapeId {
        let id: AreaId = self.mint();
        let scope = self.current_scope();
        self.author("add_area", |_indexed, sink| {
            edit::create::area(id, scope, start, end, sink);
        });
        ShapeId::Area(id)
    }
    /// Iterate the current level's areas — the top layer, drawn above the
    /// blocks and routes. Kept separate from [`Self::shapes`] so areas neither
    /// render in the base layer nor act as routing obstacles.
    pub fn areas(&self) -> impl Iterator<Item = (ShapeId, ShapeRef<'_>)> {
        self.scope_areas()
            .into_iter()
            .map(|(id, c)| (ShapeId::Area(id), ShapeRef::Area(c)))
    }

    // ── Port accessors ───────────────────────────────────────────────────────

    /// Insert a port whose name is auto-derived from its freshly assigned id
    /// (`"Port N"`). The id is only known after insertion, hence the two-step
    /// insert-then-rename. The boundary `side`+`offset` is picked from the
    /// first entry of `current().new_pin_locations()`; the current block is
    /// grown by one pin slot (one [`PIN_PITCH`](crate::grid::PIN_PITCH)) in height if no boundary
    /// location is available.
    pub fn add_port_auto_named(&mut self, inner: Rect) -> PinId {
        let id = self.mint();
        let scope = self.current_scope();
        self.author("add_port_auto_named", |indexed, sink| {
            // A port is a material edit, so the scope has to accept one.
            let Some(owner) = edit::lock::UnlockedScope::of(indexed, scope) else {
                return;
            };
            edit::create::port(
                indexed,
                edit::create::NewPort {
                    id,
                    owner,
                    start: inner.min,
                    end: inner.max,
                },
                sink,
            );
        });
        id
    }

    // ── Combined shape accessors ──────────────────────────────────────────────

    /// Generic lookup: returns a `ShapeRef` regardless of kind.
    pub fn shape(&self, id: ShapeId) -> Option<ShapeRef<'_>> {
        match id {
            ShapeId::Rect(rid) => Some(ShapeRef::Block(self.shape_of_block(rid, self.block(rid)?))),
            // A port body is the scope's *own* pin; the same pin seen from the
            // parent is a stub on this block's rect instead (`pin_shape`).
            ShapeId::Port(pid) => {
                let pin = self
                    .held_pin(pid)
                    .filter(|pin| self.scope_owns(pin.owner))?;
                Some(ShapeRef::Port(PortShape { id: pid, pin }))
            }
            ShapeId::Text(tid) => {
                let text = self.scope_owned(self.indexed().doc.text(&tid), |t| t.owner)?;
                let extent = self.presentation.text_extents.valid_for(tid, text);
                Some(ShapeRef::text(text, extent))
            }
            ShapeId::Area(cid) => self
                .scope_owned(self.indexed().doc.area(&cid), |c| c.owner)
                .map(ShapeRef::Area),
            ShapeId::Image(sid) => {
                let image = self.scope_owned(self.indexed().doc.image(&sid), |i| i.owner)?;
                Some(ShapeRef::artwork(
                    artwork_rect(image.rect),
                    self.asset(&image.asset),
                ))
            }
            ShapeId::Icon(rid) => {
                let icon = crate::edit::geometry::artwork(&self.block(rid)?.icon)?;
                Some(ShapeRef::artwork(
                    artwork_rect(icon.rect),
                    self.asset(&icon.asset),
                ))
            }
        }
    }
    /// The pin-tag visibility of a selected port, for the selection bar's toggle.
    /// `None` for shapes that carry no such tag (blocks, text boxes, areas,
    /// images).
    pub fn shape_tag_hidden(&self, id: ShapeId) -> Option<bool> {
        match id {
            // A port body *is* one pin, so the port's own id is the pin's.
            ShapeId::Port(pid) => Some(self.shape(id)?.pin(pid)?.tag_hidden),
            ShapeId::Rect(_)
            | ShapeId::Text(_)
            | ShapeId::Area(_)
            | ShapeId::Image(_)
            | ShapeId::Icon(_) => None,
        }
    }

    /// Set the pin-tag visibility of a port — the counterpart to
    /// [`shape_tag_hidden`](Self::shape_tag_hidden). No-op for other shapes.
    pub fn set_shape_tag_hidden(&mut self, id: ShapeId, tag: TagVisibility) {
        // A port body *is* one pin, so the port's own id is the pin's.
        if let ShapeId::Port(pid) = id {
            self.author("set_shape_tag_hidden", |indexed, sink| {
                edit::naming::set_tag_visibility(indexed.doc, &[pid], tag, sink);
            });
        }
    }

    /// Give `target` the accent role `role` (`None` clears it). A route's
    /// role repropagates the derived pin accents when the commit lands.
    pub fn set_role(&mut self, target: RoleTarget, role: Option<u8>) {
        let target = match target {
            RoleTarget::Block(id) => edit::naming::AccentTarget::Block(id),
            RoleTarget::Port(id) => edit::naming::AccentTarget::Port(id),
            RoleTarget::Route(id) => edit::naming::AccentTarget::Route(id),
            RoleTarget::Area(id) => edit::naming::AccentTarget::Area(id),
            RoleTarget::Text(id) => edit::naming::AccentTarget::Text(id),
        };
        self.author("set_role", |indexed, sink| {
            edit::naming::set_accent(indexed.doc, target, role, sink);
        });
    }

    /// Set the I/O direction on every pin in the group whose owner is
    /// unlocked — a locked block keeps its pin interface frozen.
    pub fn set_pins_kind(&mut self, pins: &[PinId], dir: PinDir) {
        self.author("set_pins_kind", |indexed, sink| {
            let targets = edit::lock::MaterialPin::all(indexed.doc, pins);
            edit::naming::set_dirs(indexed.doc, &targets, dir, sink);
        });
    }

    /// Cycle one pin's I/O direction in place — the selected-stub click.
    /// A locked owner declines: direction is what a pin *is*.
    pub fn cycle_pin_kind(&mut self, pin: PinId) {
        self.author("cycle_pin_kind", |indexed, sink| {
            let Some(target) = edit::lock::MaterialPin::of(indexed.doc, pin) else {
                return;
            };
            edit::naming::cycle_dir(indexed.doc, target, sink);
        });
    }

    /// Show or hide the location tags on a pin group.
    pub fn set_pins_tag_hidden(&mut self, pins: &[PinId], tag: TagVisibility) {
        self.author("set_pins_tag_hidden", |indexed, sink| {
            edit::naming::set_tag_visibility(indexed.doc, pins, tag, sink);
        });
    }

    /// Freeze or thaw a block's pin interface.
    pub fn set_block_locked(&mut self, block: BlockId, lock: InterfaceLock) {
        self.author("set_block_locked", |indexed, sink| {
            edit::naming::set_locked(indexed.doc, block, lock, sink);
        });
    }

    /// Write `text` to `shape`'s title, if it carries one — a block or a
    /// area.
    pub fn set_title_text(&mut self, shape: ShapeId, text: &str) {
        let Some(target) = title_target(shape) else {
            return;
        };
        self.author("set_title_text", |indexed, sink| {
            edit::naming::rename_title(indexed.doc, target, text, sink);
        });
    }

    /// Commit a dragged title's placement.
    pub fn place_title(&mut self, shape: ShapeId, placement: LabelPlacement) {
        let target = match shape {
            ShapeId::Rect(id) => edit::naming::LabelTarget::BlockTitle(id),
            ShapeId::Area(id) => edit::naming::LabelTarget::AreaTitle(id),
            _ => return,
        };
        self.author("place_title", |indexed, sink| {
            edit::naming::place_label(indexed.doc, target, placement.into(), sink);
        });
    }

    /// Write `text` to block `rect`'s type label.
    pub fn set_type_label_text(&mut self, rect: BlockId, text: &str) {
        self.author("set_type_label_text", |indexed, sink| {
            edit::naming::rename_type(indexed.doc, rect, text, sink);
        });
    }

    /// Commit a dragged type label's placement.
    pub fn place_type_label(&mut self, rect: BlockId, placement: LabelPlacement) {
        self.author("place_type_label", |indexed, sink| {
            edit::naming::place_label(
                indexed.doc,
                edit::naming::LabelTarget::BlockType(rect),
                placement.into(),
                sink,
            );
        });
    }

    /// The width pin `pin`'s port body must reach to hold its labels, with
    /// `name`/`type_name` overriding what it holds now — the measurement a
    /// rename or retype owes its emitter, which cannot make one for itself.
    pub fn label_fit(
        &self,
        pin: PinId,
        name: Option<&str>,
        type_name: Option<&str>,
    ) -> LabelFitWidth {
        let held = self.held_pin(pin);
        let name = name.unwrap_or_else(|| held.map_or("", |pin| &pin.name));
        let type_name = type_name.unwrap_or_else(|| held.map_or("", |pin| &pin.type_name));
        LabelFitWidth::new(crate::shape::port::width_for_labels(name, type_name))
    }

    /// Rename a pin, widening the port body to fit its labels. A locked
    /// block keeps its pin interface frozen — the commit is dropped.
    pub fn rename_pin(&mut self, pin: PinId, text: &str, fit: LabelFitWidth) {
        self.author("rename_pin", |indexed, sink| {
            let Some(target) = edit::lock::MaterialPin::of(indexed.doc, pin) else {
                return;
            };
            edit::naming::rename_pin(indexed.doc, target, text, fit, sink);
        });
    }

    /// Set a pin's location tag. Tags extend outward over the stub, so
    /// no widening. Locked owners drop the commit, as with renames.
    pub fn set_pin_tag(&mut self, pin: PinId, text: &str) {
        self.author("set_pin_tag", |indexed, sink| {
            let Some(target) = edit::lock::MaterialPin::of(indexed.doc, pin) else {
                return;
            };
            edit::naming::set_tag(indexed.doc, target, text, sink);
        });
    }

    /// Set a pin's type label, widening the port body to fit. Locked
    /// owners drop the commit.
    pub fn retype_pin(&mut self, pin: PinId, text: &str, fit: LabelFitWidth) {
        self.author("retype_pin", |indexed, sink| {
            let Some(target) = edit::lock::MaterialPin::of(indexed.doc, pin) else {
                return;
            };
            edit::naming::retype_pin(indexed.doc, target, text, fit, sink);
        });
    }

    /// Add a pin at `loc` on `block`, auto-named "Port N" from its ordinal.
    /// Returns the id so the caller can anchor a route to it. A locked
    /// block keeps its pin interface frozen — `None`.
    pub fn add_named_pin(&mut self, block: BlockId, loc: PinLocation) -> Option<PinId> {
        // Asked here as well as inside, because the caller needs the answer:
        // a declined stamp has no id to hand back.
        if edit::lock::UnlockedScope::of(&self.indexed(), crate::path::Scope::Block(block))
            .is_none()
        {
            tracing::debug!(target: "edit", edit = "add_named_pin", "declined");
            return None;
        }
        let id = self.mint();
        self.author("add_named_pin", |indexed, sink| {
            let Some(owner) =
                edit::lock::UnlockedScope::of(indexed, crate::path::Scope::Block(block))
            else {
                return;
            };
            edit::create::pin(
                indexed,
                edit::create::NewPin {
                    id,
                    owner,
                    slot: slot_at(loc),
                },
                sink,
            );
        });
        Some(id)
    }

    /// Commit a handle-drag resize: the caller resolved the final rect
    /// (constraints, snapping, magnetism, which corner moved), this writes
    /// it — geometry, carried pins, and icon box.
    pub fn apply_resize(&mut self, shape: ShapeId, new_rect: Rect) {
        let target = match shape {
            ShapeId::Rect(id) => edit::geometry::ResizeTarget::Block(id),
            ShapeId::Port(id) => edit::geometry::ResizeTarget::Port(id),
            ShapeId::Area(id) => edit::geometry::ResizeTarget::Area(id),
            ShapeId::Image(id) => edit::geometry::ResizeTarget::Image(id),
            ShapeId::Icon(id) => edit::geometry::ResizeTarget::Icon(id),
            ShapeId::Text(id) => edit::geometry::ResizeTarget::Text(id),
        };
        self.author("apply_resize", |indexed, sink| {
            edit::geometry::resize(indexed, target, new_rect, sink);
        });
    }

    /// Move a pin to `to`, which the gesture already resolved against the
    /// live preview ([`BaseShape::pin_drop_candidate`](crate::shape::BaseShape::pin_drop_candidate))
    /// — so the drop lands exactly where the drag promised. A destination
    /// another pin holds writes nothing.
    pub fn move_pin_snapped(&mut self, pin: PinId, to: PinSlot) {
        self.author("move_pin_snapped", |indexed, sink| {
            edit::geometry::move_pin(indexed, pin, to, sink);
        });
    }

    /// Name a wire. An empty/whitespace name removes `label` entirely and
    /// clears the shared name, so the wire goes back to unlabeled rather
    /// than carrying a blank slot.
    pub fn set_route_name(&mut self, route: RouteId, label: RouteLabelId, text: &str) {
        if text.trim().is_empty() {
            self.author("set_route_name", |indexed, sink| {
                edit::naming::clear_wire_label(indexed.doc, label, sink);
            });
        } else {
            self.author("set_route_name", |indexed, sink| {
                edit::naming::rename_route(indexed.doc, route, text, sink);
            });
        }
    }

    /// Commit a text box's content. Emptying the box discards it rather than
    /// leaving it invisible.
    ///
    /// The extent is not written here: it is measured on demand by
    /// [`Self::refresh_text_extents`], because the text can change without an
    /// editor being involved and a cache only filled by the editor goes
    /// stale the moment it does.
    pub fn set_text_box_content(&mut self, id: TextId, text: &str) {
        self.author("set_text_box_content", |indexed, sink| {
            edit::naming::edit_text(indexed.doc, id, text, sink);
        });
    }

    /// Measure any text box in this scope whose cached extent no longer
    /// matches its text, so the box draws and hit-tests at its real size.
    ///
    /// On demand rather than on commit. A box's text changes under the cache
    /// whenever the editor was not what changed it — an undo, a redo — and an
    /// extent written only by the editor would leave those boxes on the
    /// character-count estimate until someone re-opened them. Cheap by
    /// construction: an entry that
    /// still matches its text is not measured again, so a frame that changed
    /// no text measures nothing.
    pub fn refresh_text_extents(&mut self, painter: &Style<'_, impl Renderer>) {
        let stale: Vec<(TextId, Text)> = self
            .scope_texts()
            .into_iter()
            .filter(|(id, text)| {
                self.presentation
                    .text_extents
                    .valid_for(*id, text)
                    .is_none()
            })
            .map(|(id, text)| (id, text.clone()))
            .collect();
        for (id, text) in stale {
            let width = crate::render::text_box::BoxWidth::of(&text);
            let size = crate::render::text_box::measure_box_size(painter, &text.text, width);
            self.presentation.text_extents.set(id, &text, size);
        }
    }

    /// Drop a name label on `route` at the projection of `pos` onto its
    /// polyline. `None` for a wire with no solved geometry to project onto.
    pub fn add_route_label(&mut self, route: RouteId, pos: Pos2) -> Option<RouteLabelId> {
        let distance = self.route_geometry(route)?.distance_along(pos);
        let id = self.mint();
        self.author("add_route_label", |indexed, sink| {
            edit::create::wire_label(indexed.doc, id, route, distance, sink);
        });
        Some(id)
    }

    /// Place a wire's name label at an arc length along its route — the label
    /// drag's one document write, of the distance the preview settled on.
    pub fn place_route_label(
        &mut self,
        label: RouteLabelId,
        dist: blockworx_doc::geometry::FracVal,
    ) {
        self.author("place_route_label", |indexed, sink| {
            edit::geometry::place_wire_label(indexed.doc, label, dist, sink);
        });
    }

    /// Mirror a selected shape left/right. No-op for shapes without pins; the
    /// caller re-routes afterwards.
    ///
    /// A **port** flips only its `port_orientation` (the way its stub faces), so
    /// the pin it represents on the parent block doesn't move. A **block** flips
    /// the edge `side` of all its pins, but first freezes each pin's
    /// `port_orientation` to its current value — so descending into the block
    /// shows the same boundary ports as before and its internal routes are left
    /// intact.
    pub fn flip_shape_pins(&mut self, id: ShapeId) {
        let target = match id {
            ShapeId::Rect(rid) => edit::geometry::FlipTarget::Block(rid),
            ShapeId::Port(pid) => edit::geometry::FlipTarget::Port(pid),
            ShapeId::Text(_) | ShapeId::Area(_) | ShapeId::Image(_) | ShapeId::Icon(_) => return,
        };
        self.author("flip_shape_pins", |indexed, sink| {
            edit::geometry::flip_pins(indexed, target, sink);
        });
    }

    /// Add a level above the whole document: a fresh root whose sole child
    /// is the old one, which demotes to a child rect.
    ///
    /// Reachable from nothing on screen: a navigation button that quietly
    /// writes a block is the wrong door for it (docs/ui-issues-2.md, item 8),
    /// and the right one has not been chosen.
    pub fn wrap_top(&mut self) {
        let id = self.mint();
        self.author("wrap_top", |indexed, sink| {
            edit::create::wrap_top(indexed, id, sink);
        });
    }

    /// Vertically mirror a block's pins about its center: a pin in slot `offset`
    /// moves to slot `h - offset`, where `h` ([`crate::grid::max_pin_slot`]) is
    /// the block's
    /// height in slots. Each pin keeps its `side`; only its vertical slot moves.
    /// A double flip is an exact identity. The caller re-routes afterwards.
    pub fn flip_block_vertical(&mut self, block: BlockId) {
        self.author("flip_block_vertical", |indexed, sink| {
            edit::geometry::flip_vertical(indexed, block, sink);
        });
    }

    /// The current level's child blocks paired with their ids, for callers that
    /// need the `Block` directly rather than as a `ShapeRef`.
    pub fn current_blocks(&self) -> impl Iterator<Item = (BlockId, &Block)> {
        self.child_blocks().into_iter()
    }

    /// A block as the renderer sees it: its pins, and whether it opens a scope
    /// of its own. The one place a `Block` becomes a [`BlockShape`], so no
    /// caller can hand the renderer a block whose interior it never asked about.
    fn shape_of_block<'s>(&'s self, id: BlockId, block: &'s Block) -> BlockShape<'s> {
        BlockShape::new(
            block,
            self.block_pins(crate::path::Scope::Block(id)),
            crate::path::structure(&self.indexed(), id),
        )
    }

    /// The child blocks of the current level, as renderable shapes — each
    /// bundled with the pins that hang off it.
    pub fn blocks_layer(&self) -> impl Iterator<Item = (ShapeId, ShapeRef<'_>)> {
        self.child_blocks().into_iter().map(|(id, block)| {
            (
                ShapeId::Rect(id),
                ShapeRef::Block(self.shape_of_block(id, block)),
            )
        })
    }
    /// The current level's boundary ports, as renderable shapes: the scope's
    /// own pins, drawn as the port bodies their `rect` register places.
    pub fn ports_layer(&self) -> impl Iterator<Item = (ShapeId, ShapeRef<'_>)> {
        self.block_pins(self.current_scope())
            .into_iter()
            .map(|(id, pin)| (ShapeId::Port(id), ShapeRef::Port(PortShape { id, pin })))
    }
    /// The current level's text boxes, as renderable shapes.
    pub fn texts_layer(&self) -> impl Iterator<Item = (ShapeId, ShapeRef<'_>)> {
        self.scope_texts().into_iter().map(|(id, text)| {
            let extent = self.presentation.text_extents.valid_for(id, text);
            (ShapeId::Text(id), ShapeRef::text(text, extent))
        })
    }
    /// The current level's free-floating background images, as renderable shapes.
    pub fn images_layer(&self) -> impl Iterator<Item = (ShapeId, ShapeRef<'_>)> {
        self.scope_images().into_iter().map(|(id, image)| {
            (
                ShapeId::Image(id),
                ShapeRef::artwork(artwork_rect(image.rect), self.asset(&image.asset)),
            )
        })
    }
    /// The current level's block icons, as renderable shapes — the foreground
    /// layer, drawn on top of everything (see
    /// [`DrawingPasses`](crate::widget::DrawingPasses)).
    pub fn icons(&self) -> impl Iterator<Item = (ShapeId, ShapeRef<'_>)> {
        self.child_blocks().into_iter().filter_map(|(id, block)| {
            let icon = crate::edit::geometry::artwork(&block.icon)?;
            Some((
                ShapeId::Icon(id),
                ShapeRef::artwork(artwork_rect(icon.rect), self.asset(&icon.asset)),
            ))
        })
    }
    /// Iterate over all shapes (blocks first, then ports, then text boxes, then
    /// images). This order is for non-render uses (hit-testing, copy); the
    /// painted layer order lives in [`DrawingPasses`](crate::widget::DrawingPasses).
    pub fn shapes(&self) -> impl Iterator<Item = (ShapeId, ShapeRef<'_>)> {
        self.blocks_layer()
            .chain(self.ports_layer())
            .chain(self.texts_layer())
            .chain(self.images_layer())
    }

    /// Whether every destination is free and in bounds — the gate a group
    /// pin move's *preview* asks before drawing it as valid. The same
    /// predicate the commit runs, so the preview cannot promise a move the
    /// emitter will refuse.
    pub fn can_relocate_pins(&self, moves: &[PinMove]) -> bool {
        crate::edit::geometry::relocation_fits(&self.indexed(), moves)
    }

    /// Apply a group pin move iff [`Self::can_relocate_pins`] holds; returns
    /// whether it was applied. On success each pin takes its new slot.
    pub fn relocate_pins(&mut self, moves: &[PinMove]) -> bool {
        let applied = self.can_relocate_pins(moves);
        self.author("relocate_pins", |indexed, sink| {
            edit::geometry::relocate_pins(indexed, moves, sink);
        });
        applied
    }

    /// Shift `anchors` rigidly by `slot_delta` slots (negative = up), keeping
    /// each pin's side. The shift is clamped to the tightest range that keeps
    /// every pin on its block — like a multi-pin drag — so a
    /// group moves as one and never runs off an edge.
    pub fn nudge_pins(&mut self, pins: &[PinId], slot_delta: i32) {
        self.author("nudge_pins", |indexed, sink| {
            edit::geometry::nudge_pins(
                indexed,
                pins,
                edit::geometry::SlotDelta::new(slot_delta),
                sink,
            );
        });
    }

    /// World-space bounding box of everything this scope *draws* — the whole
    /// diagram, wires, labels and waypoints included, not just the shapes that
    /// hold them. Taken by running the real draw passes into a measuring
    /// backend, so a shape kind added later joins the extent the moment it is
    /// drawn. `None` when the scope draws nothing.
    pub fn content_bounds(&self, painter: &Style<'_, impl Renderer>) -> Option<Rect> {
        let mut extent = blockworx_paint::Extent::measuring_through(painter.renderer());
        crate::widget::DrawingPasses::new(self).draw(&mut Style::new(painter.theme(), &mut extent));
        extent.finish()
    }

    // ── Broad-phase candidate selection ─────────────────────────────────────
    //
    // Shared by hit-testing (query rect = the cursor neighborhood) and, via the
    // same index, viewport culling. With an index only nearby candidates are
    // returned; without one, the full collection in its usual order — so the
    // no-index paths (SVG export, tests) behave exactly as before.

    /// Where `id` sits in the draw order: its paint layer, then the
    /// document's one chronological order — ascending id — within that
    /// layer. Sorting the index's (unordered) hits by this reproduces the
    /// linear [`Self::shapes`] walk exactly, so the two broad phases
    /// cannot disagree about which shape is on top.
    fn draw_key(id: ShapeId) -> (u8, ShapeId) {
        (shape_layer_rank(id), id)
    }

    /// Shapes (blocks/ports/texts/images — **not** areas) whose coarse bounds
    /// fall near `query`, in draw order. Index-limited when available;
    /// otherwise every shape in [`Self::shapes`] order, which is the same
    /// order. Areas are queried by their own (short) linear scan, so they
    /// are excluded here.
    pub fn shape_candidates(&self, query: Rect) -> Vec<(ShapeId, ShapeRef<'_>)> {
        match self.index {
            Some(idx) => {
                let mut v: Vec<(ShapeId, ShapeRef<'_>)> = idx
                    .in_rect(query)
                    .filter_map(|hit| match hit {
                        // Areas run their own linear scan; icons are hit-tested
                        // only in their block's context (see `icon_at_pos`), never
                        // as free candidates — but both stay in the index for
                        // culling. Excluding them here keeps the indexed hit-test and
                        // marquee identical to the no-index `shapes()` path.
                        HitId::Shape(id) if !matches!(id, ShapeId::Area(_) | ShapeId::Icon(_)) => {
                            self.shape(id).map(|s| (id, s))
                        }
                        _ => None,
                    })
                    .collect();
                v.sort_by_key(|(id, _)| Self::draw_key(*id));
                v
            }
            None => self.shapes().collect(),
        }
    }

    /// [`Self::shape_candidates`] back-to-front: the shape painted last —
    /// the one on top — comes first, so a top-down hit test takes the first
    /// match. Hit order is the reverse of draw order, and this is the only
    /// place that says so.
    pub fn hit_candidates(&self, query: Rect) -> Vec<(ShapeId, ShapeRef<'_>)> {
        let mut v = self.shape_candidates(query);
        v.reverse();
        v
    }

    /// Record where this frame's preview puts each shape. A block's icon rides
    /// inside its block, so the block's previewed rect is where the icon goes
    /// too — recorded here rather than by each tool that draws them together.
    pub(super) fn preview_shapes(&mut self, previews: &[(ShapeId, Rect)]) {
        self.previewed.shapes.clear();
        for &(id, rect) in previews {
            self.previewed.shapes.push((id, rect));
            if let Some(icon) = id.block().map(ShapeId::Icon)
                && self.shape(icon).is_some()
            {
                self.previewed.shapes.push((icon, rect));
            }
        }
    }

    /// The scope this drawing is over, for a caller that has to say *where*
    /// something happened as well as what.
    pub(super) fn scope_path(&self) -> &BlockPath {
        self.path
    }

    /// Record the wires this frame's preview re-solved — the ones now drawn
    /// somewhere the document does not put them.
    pub(super) fn preview_routes(&mut self, routes: Vec<RouteId>) {
        self.previewed.routes = routes;
    }

    /// Ids to draw when culling the scene to `viewport` (world space): the
    /// hittables whose bounds are on screen. `None` means "no index — draw
    /// everything", which is what the SVG export and tests want (they must not
    /// cull). Shares the one index with the hit-test broad phase.
    ///
    /// The index is keyed by the document value, so it answers for *committed*
    /// geometry only. A live preview moves where a shape paints without moving
    /// its rect, so this frame's preview is asked too and its answers are
    /// unioned in — that set is the dragged shapes and the wires re-solved
    /// against them, never the document.
    pub(crate) fn visible_ids(&self, viewport: Rect) -> Option<std::collections::HashSet<HitId>> {
        let idx = self.index?;
        let mut ids: std::collections::HashSet<HitId> = idx.in_rect(viewport).collect();
        for &(id, rect) in &self.previewed.shapes {
            if self.shape(id).is_some_and(|shape| {
                crate::render::bounds::shape_bounds_at(&shape, rect).intersects(viewport)
            }) {
                ids.insert(HitId::Shape(id));
            }
        }
        for &id in &self.previewed.routes {
            if self
                .auto_route(id)
                .zip(self.route_geometry(id))
                .is_some_and(|(wire, geometry)| {
                    crate::render::bounds::route_bounds(&wire, geometry).intersects(viewport)
                })
            {
                ids.insert(HitId::Route(id));
            }
        }
        Some(ids)
    }

    /// The hops each of `among` draws. `among` is in draw order and holds every wire through any
    /// point whose hop is wanted — what the index reports for a rectangle, or
    /// the whole scope ([`route_hops`](super::auto_route::route_hops)).
    pub fn hops(&self, among: &[RouteId]) -> Hops {
        let _s = tracing::info_span!("hops", routes = among.len()).entered();
        let drawn: Vec<(RouteId, &RouteGeometry)> = among
            .iter()
            .filter_map(|&id| Some((id, self.route_geometry(id)?)))
            .collect();
        let hops = super::auto_route::route_hops(drawn.iter().map(|&(_, geometry)| geometry));
        let hops = drawn
            .into_iter()
            .zip(hops)
            .filter(|(_, hops)| !hops.is_empty())
            .map(|((id, _), hops)| (id, hops))
            .collect();
        Hops(hops)
    }

    /// How to draw `id`: its geometry and `hops`. `None` for a wire with no
    /// solved geometry, which draws nothing.
    pub fn course<'h>(&'h self, id: RouteId, hops: &'h [Crossing]) -> Option<Course<'h>> {
        Some(Course {
            geometry: self.route_geometry(id)?,
            hops,
        })
    }

    /// The standing conflicts `shapes` are party to: where two routing shapes
    /// overlap, and each illegal stretch of a wire that settled on its
    /// fallback L through one — the same crossing the router refuses a leg
    /// for, so the mark and the refusal cannot disagree. Each is found by
    /// asking the spatial index what lies near the shape; a shape a preview
    /// is dragging counts where the preview draws it, as does every wire the
    /// preview re-solved, since the index holds only committed geometry. With
    /// no index (an export), one is built for the ask.
    pub(crate) fn standing_conflicts(&self, shapes: &[ShapeId]) -> Conflicts {
        let built;
        let index = if let Some(index) = self.index {
            index
        } else {
            built = SpatialIndex::from_drawing(self);
            &built
        };
        let doc = self.indexed().doc;
        let cells = |id: ShapeId| {
            self.previewed
                .shapes
                .iter()
                .find(|&&(shape, _)| shape == id)
                .map(|&(_, rect)| crate::grid::grid_rect(rect.min, rect.max))
                .or_else(|| {
                    crate::edit::geometry::placement(doc, crate::edit::geometry::Shape::from(id))
                        .map(|(_, cells)| cells)
                })
        };
        let previewed = |hit: &HitId| match *hit {
            HitId::Shape(id) => self.previewed.shapes.iter().any(|&(shape, _)| shape == id),
            HitId::Route(id) => self.previewed.routes.contains(&id),
        };
        let from_preview = self
            .previewed
            .shapes
            .iter()
            .map(|&(id, _)| HitId::Shape(id))
            .chain(self.previewed.routes.iter().map(|&id| HitId::Route(id)));
        // A pair is found from both of its shapes when both are asked about;
        // it is kept from the lesser.
        let asked: std::collections::HashSet<ShapeId> = shapes.iter().copied().collect();
        let mut conflicts = Conflicts::default();
        for &one in shapes {
            let Some(own) = cells(one) else {
                continue;
            };
            let rect = crate::grid::px_rect(own);
            let block = super::routing::obstacle_rect(rect);
            let near = index
                .in_rect(rect)
                .filter(|hit| !previewed(hit))
                .chain(from_preview.clone());
            for hit in near {
                match hit {
                    HitId::Shape(other)
                        if other != one
                            && is_routing(other)
                            && (other > one || !asked.contains(&other)) =>
                    {
                        let overlap = cells(other).and_then(|other| own.intersection(other));
                        conflicts.overlaps.extend(overlap.map(crate::grid::px_rect));
                    }
                    HitId::Route(id) => {
                        let Some(geometry) = self.route_geometry(id) else {
                            continue;
                        };
                        conflicts.crossings.extend(
                            geometry
                                .iter_edges()
                                .filter_map(|(_, edge)| block.edge_crossing(edge.start, edge.end))
                                .map(|(from, to)| {
                                    let (from, to) = (
                                        crate::grid::px_point(from.into()),
                                        crate::grid::px_point(to.into()),
                                    );
                                    Rect::from_min_max(from.min(to), from.max(to))
                                        .expand(crate::grid::GRID_SIZE / 2.0)
                                }),
                        );
                    }
                    HitId::Shape(_) => {}
                }
            }
        }
        conflicts
    }

    /// The hops one wire draws, against the wires the index finds near it —
    /// for a caller redrawing it alone, over the scene.
    pub fn hops_of(&self, id: RouteId) -> Vec<Crossing> {
        let Some(bounds) = self
            .auto_route(id)
            .zip(self.route_geometry(id))
            .map(|(wire, geometry)| crate::render::bounds::route_bounds(&wire, geometry))
        else {
            return Vec::new();
        };
        let near: Vec<RouteId> = self
            .route_candidates(bounds)
            .into_iter()
            .map(|(id, _)| id)
            .collect();
        self.hops(&near).0.remove(&id).unwrap_or_default()
    }

    /// Routes whose coarse bounds fall near `query`. Index-limited when available,
    /// sorted back into `auto_routes()` (insertion) order so that when wires
    /// overlap — e.g. at a crossing — the same one wins as in the linear scan;
    /// otherwise every route in `auto_routes()` order.
    pub(crate) fn route_candidates(&self, query: Rect) -> Vec<(RouteId, Wire<'_>)> {
        match self.index {
            Some(idx) => {
                let order = self.scope_route_ids();
                let mut v: Vec<(RouteId, Wire<'_>)> = idx
                    .in_rect(query)
                    .filter_map(|hit| match hit {
                        HitId::Route(id) => self.auto_route(id).map(|r| (id, r)),
                        HitId::Shape(_) => None,
                    })
                    .collect();
                v.sort_by_key(|(id, _)| {
                    order
                        .iter()
                        .position(|other| other == id)
                        .unwrap_or(usize::MAX)
                });
                v
            }
            None => self.auto_routes().collect(),
        }
    }
}

/// The hops a pass's wires draw, from [`Drawing::hops`].
pub struct Hops(ahash::HashMap<RouteId, Vec<Crossing>>);

impl Hops {
    /// Where `id` jumps the wires it crosses — nothing, for a wire that
    /// crosses none or was not among those the hops were computed over.
    pub fn of(&self, id: RouteId) -> &[Crossing] {
        self.0.get(&id).map_or(&[], Vec::as_slice)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::{
        edit::lower::slot_capacity,
        grid::GRID_SIZE,
        shape::Deletable,
        widget::test_fixtures::{self as fx, Scene},
    };
    use blockworx_doc::{
        fixtures::{block_id, pin_id, route_id},
        values::PinSide as DocPinSide,
    };
    use blockworx_geom::{pos2, vec2};
    use blockworx_paint::FontChoice;
    use blockworx_text::measure::Measured;

    /// Two blocks four cells square, `x` cells from the origin each.
    fn two_blocks(one: i32, other: i32) -> Scene {
        Scene::new(vec![
            fx::block_in(1, Scope::Root, fx::cells(one, 0, 4, 4)),
            fx::block_in(2, Scope::Root, fx::cells(other, 0, 4, 4)),
        ])
    }

    fn both() -> [ShapeId; 2] {
        [ShapeId::Rect(block_id(1)), ShapeId::Rect(block_id(2))]
    }

    /// An overlap the document holds is marked once, over the cells the two
    /// share.
    #[test]
    fn an_overlap_is_marked_once_over_the_shared_cells() {
        let mut scene = two_blocks(0, 2);
        let conflicts = scene.drawing().standing_conflicts(&both());
        assert_eq!(conflicts.overlaps, vec![fx::cells(2, 0, 2, 4)]);
    }

    /// The index holds committed rects, so a dragged block is asked about
    /// where the preview draws it: dragged onto a neighbour it is marked
    /// there, and dragged off one the mark it stood in goes with it.
    #[test]
    fn a_dragged_block_is_marked_where_the_preview_draws_it() {
        let mut scene = two_blocks(0, 10);
        let mut drawing = scene.drawing();
        assert!(
            drawing.standing_conflicts(&both()).overlaps.is_empty(),
            "precondition: the committed blocks stand clear"
        );
        drawing.preview_shapes(&[(ShapeId::Rect(block_id(2)), fx::cells(3, 0, 4, 4))]);
        assert_eq!(
            drawing.standing_conflicts(&both()).overlaps,
            vec![fx::cells(3, 0, 1, 4)]
        );

        let mut scene = two_blocks(0, 2);
        let mut drawing = scene.drawing();
        assert!(
            !drawing.standing_conflicts(&both()).overlaps.is_empty(),
            "precondition: the committed blocks overlap"
        );
        drawing.preview_shapes(&[(ShapeId::Rect(block_id(2)), fx::cells(10, 0, 4, 4))]);
        assert!(drawing.standing_conflicts(&both()).overlaps.is_empty());
    }

    /// The scene asks only about what is on screen, and a neighbour off it is
    /// still found through the index: an overlap is one fact, whichever of
    /// the two is asked about.
    #[test]
    fn an_overlap_is_found_from_either_block() {
        let mut scene = two_blocks(0, 2);
        let drawing = scene.drawing();
        for one in both() {
            assert_eq!(
                drawing.standing_conflicts(&[one]).overlaps,
                vec![fx::cells(2, 0, 2, 4)],
                "asked about {one:?}"
            );
        }
    }

    /// The whole minting path, through the waist the tools hold: a document
    /// loaded with blocks up to `b7` mints `b8` next, per kind, and a deleted
    /// entity keeps its number out of circulation.
    #[test]
    fn a_tool_mints_one_past_the_highest_id_the_document_holds() {
        let mut scene = Scene::new(vec![fx::block(7, 0.0), fx::pin(2, 7, DocPinSide::East, 0)]);
        assert!(
            scene.drawing().held_block(block_id(8)).is_none(),
            "precondition: b8 is free before the gesture",
        );

        let (made, _) = scene.authored(|drawing| {
            (
                drawing.add_block(pos2(200.0, 0.0), pos2(240.0, 40.0)),
                drawing.add_text_box(pos2(300.0, 0.0)),
            )
        });
        assert_eq!(
            made,
            (block_id(8), blockworx_doc::fixtures::text_id(1)),
            "the block counts on from b7 while the texts start their own space at 1",
        );

        scene.authored(|drawing| drawing.delete(Deletable::Shape(ShapeId::Rect(block_id(8)))));
        assert!(
            scene.drawing().held_block(block_id(8)).is_none(),
            "precondition: b8 is deleted",
        );
        let (again, _) =
            scene.authored(|drawing| drawing.add_block(pos2(0.0, 200.0), pos2(40.0, 240.0)));
        assert_eq!(
            again,
            block_id(9),
            "the marks never fall, so the next block cannot land on a departed id",
        );
    }

    /// A scene whose wire is dragged well clear of both blocks by a locked
    /// waypoint — the shape of the user report "fit to extent does not
    /// include the routes".
    fn wire_outside_the_blocks() -> Scene {
        Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, 120.0),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::pin(4, 2, DocPinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[(8, -30), (8, -30)]),
        ])
    }

    /// What a fit frames is the whole diagram, not the shapes that hold it:
    /// a wire routed far above every block is still part of the drawing, and
    /// a view that leaves it out has cropped the document.
    #[test]
    fn the_content_bounds_hold_the_wires_too() {
        let mut scene = wire_outside_the_blocks();
        let theme = crate::theme::Theme::default();
        let canvas = Measured::new(FontChoice::default(), theme.palette().clone());
        let drawing = scene.drawing();

        let blocks = drawing
            .blocks_layer()
            .map(|(_, shape)| shape.gui_rect())
            .reduce(Rect::union)
            .expect("the scene holds blocks");
        let wire = drawing
            .auto_routes()
            .filter_map(|(id, _)| drawing.route_geometry(id))
            .flat_map(|geometry| geometry.points())
            .fold(Rect::NOTHING, |acc, p| acc.union(Rect::from_min_max(p, p)));
        assert!(
            wire.is_positive() && !blocks.contains_rect(wire),
            "precondition: the wire must escape the blocks it joins \
             (wire {wire:?}, blocks {blocks:?})",
        );

        let bounds = canvas
            .frame(|painter| drawing.content_bounds(&Style::new(&theme, painter)))
            .expect("the scene draws something");
        assert!(
            bounds.contains_rect(wire),
            "the fit cropped the wire: {bounds:?} does not hold {wire:?}",
        );
    }

    /// A gesture reads the session's prediction, which only advances at
    /// submit — so without the write door staging the sink, a block created
    /// mid-gesture would be invisible to the rest of that gesture.
    ///
    /// The claim is not just "something is there": what the gesture reads is
    /// what the sealed commit produces, so a tool seeding an editor from the
    /// prediction cannot be seeded from a different document than the one the
    /// user ends up with.
    #[test]
    fn a_gesture_reads_the_block_it_just_created() {
        let mut scene = Scene::new(vec![]);
        let (created, staged) = scene.commit(|drawing| {
            let created = drawing.add_rect_box(pos2(0.0, 0.0), pos2(40.0, 40.0));
            let seen = drawing
                .shape(ShapeId::Rect(created))
                .expect("the gesture's own block is in the document it reads");
            assert!(
                seen.title().is_some(),
                "including the title an editor would be seeded from",
            );
            (created, seen.gui_rect())
        });
        let settled = scene
            .drawing()
            .shape(ShapeId::Rect(created))
            .expect("the sealed commit folded")
            .gui_rect();
        assert_eq!(
            staged, settled,
            "the geometry read mid-gesture is the geometry the commit lands",
        );
        assert!(
            staged.area() > 0.0,
            "and it is a real rect, so the comparison is not two empties",
        );
    }

    /// The other half: what the gesture has *not* written is not there. A
    /// staged prediction that invented rows would hide the errors the fold
    /// exists to catch.
    #[test]
    fn a_gesture_reads_nothing_it_did_not_write() {
        let mut scene = Scene::new(vec![tall_block(1)]);
        scene.commit(|drawing| {
            assert!(
                drawing.shape(ShapeId::Rect(block_id(1))).is_some(),
                "the scene's own block is there",
            );
            assert!(
                drawing.shape(ShapeId::Rect(block_id(2))).is_none(),
                "a block no one authored is not",
            );
        });
    }

    /// A text box's bounds go stale whenever the editor was not what changed
    /// its text: an extent written only by the editor's commit would leave an
    /// undone box drawn and hit-tested at its character-count estimate until
    /// someone double-clicked it to start another edit cycle.
    ///
    /// Measured on demand, so the frame that shows the changed text is
    /// the frame that measures it.
    #[test]
    fn a_text_boxs_extent_is_measured_for_whatever_text_it_holds() {
        /// One frame's worth: measure what is stale, then read back the
        /// extent for the text the box actually holds.
        fn frame(
            canvas: &Measured,
            scene: &mut Scene,
            id: TextId,
        ) -> Option<blockworx_doc::geometry::GridSize> {
            canvas.frame(|painter| {
                let theme = crate::theme::Theme::default();
                let style = crate::theme::Style::new(&theme, painter);
                let mut drawing = scene.drawing();
                drawing.refresh_text_extents(&style);
                let text = drawing.text_box(id).cloned()?;
                drawing.presentation.text_extents.valid_for(id, &text)
            })
        }

        let id = blockworx_doc::fixtures::text_id(1);
        let mut scene = Scene::new(vec![fx::text(1, Scope::Root, "short", pos2(0.0, 0.0))]);
        let canvas = Measured::new(
            FontChoice::default(),
            crate::theme::Theme::default().palette().clone(),
        );

        // Nothing has typed into this box, so nothing ever wrote its extent —
        // the state a freshly opened document is in, and the one an undo
        // leaves behind.
        assert!(
            {
                let drawing = scene.drawing();
                let text = drawing
                    .text_box(id)
                    .cloned()
                    .expect("the box is in the scene");
                drawing
                    .presentation
                    .text_extents
                    .valid_for(id, &text)
                    .is_none()
            },
            "precondition: no extent has been measured yet",
        );
        let short = frame(&canvas, &mut scene, id).expect("the frame measured the box it found");

        // The text changes with no editor involved: what an undo does.
        scene.apply(vec![fx::text_content(
            1,
            "a much longer line of text than the box was measured for",
        )]);
        let grown = frame(&canvas, &mut scene, id).expect("the next frame measured the new text");

        assert!(
            grown.w > short.w,
            "the box grew to fit the longer text ({short:?} -> {grown:?}) with no \
             edit cycle to trigger it",
        );
    }

    /// A block tall enough to offer several pin slots, so the slot arithmetic
    /// under test has room to move.
    fn tall_block(n: u32) -> blockworx_doc::opcode::OpCodes {
        fx::block_in(
            n,
            Scope::Root,
            Rect::from_min_max(pos2(0.0, 0.0), pos2(40.0, 150.0)),
        )
    }

    fn slot(scene: &mut Scene, pin: PinId) -> PinSlot {
        scene
            .drawing()
            .held_pin(pin)
            .expect("the pin is in the document")
            .slot
    }

    /// The highest slot the block `n` can hold — the clamp every pin move
    /// is bounded by.
    fn capacity(scene: &mut Scene, block: BlockId) -> u32 {
        slot_capacity(
            scene
                .drawing()
                .held_block(block)
                .expect("the block is in the document")
                .rect
                .size
                .h,
        )
    }

    #[test]
    fn add_port_auto_named_adds_a_boundary_port() {
        // Both doors onto a boundary port — a click with the tool and a cell
        // dropped on the canvas — do nothing but call this, so it must
        // actually produce a port on the current scope.
        let mut scene = Scene::new(vec![]);
        assert!(
            scene.drawing().ports_layer().next().is_none(),
            "precondition: the root scope starts with no ports"
        );

        let rect = Rect::from_min_size(pos2(10.0, 10.0), vec2(4.0 * GRID_SIZE, GRID_SIZE));
        let id = scene.commit(|drawing| drawing.add_port_auto_named(rect));

        let ports: Vec<PinId> = scene.drawing().ports_layer().map(|(_, _)| id).collect();
        assert_eq!(ports, vec![id], "exactly the stamped port is drawn");
        assert_eq!(
            scene
                .drawing()
                .held_pin(id)
                .expect("the port was inserted")
                .name,
            "Port 1",
        );
    }

    /// Editing a pin's tag is a register write: the pin keeps its id, so the
    /// wires anchored to it stay anchored.
    #[test]
    fn editing_a_tag_keeps_the_route_anchors() {
        let (a, b, rid) = (pin_id(3), pin_id(4), route_id(5));
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, 80.0),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::pin(4, 2, DocPinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[]),
        ]);

        scene.commit(|drawing| drawing.set_pin_tag(a, "A1"));

        let drawing = scene.drawing();
        assert_eq!(drawing.held_pin(a).expect("the pin survives").tag, "A1");
        let wire = drawing.auto_route(rid).expect("the wire survives");
        assert_eq!((wire.route.from, wire.route.to), (a, b));
    }

    #[test]
    fn deleting_a_block_drops_its_whole_subtree() {
        let (parent, grandchild) = (block_id(1), block_id(2));
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block_in(
                2,
                Scope::Block(parent),
                Rect::from_min_max(pos2(8.0, 8.0), pos2(48.0, 48.0)),
            ),
        ]);
        assert!(
            scene.drawing().block(parent).is_some()
                && scene.drawing().held_block(grandchild).is_some(),
            "precondition: both blocks are in the document"
        );

        scene.commit(|drawing| drawing.delete(Deletable::Shape(ShapeId::Rect(parent))));

        let drawing = scene.drawing();
        assert!(
            drawing.held_block(parent).is_none(),
            "deleted block is gone"
        );
        assert!(
            drawing.held_block(grandchild).is_none(),
            "descendant subtree is gone too (no orphans)"
        );
        assert!(
            drawing.child_blocks().is_empty(),
            "the block is unlinked from the scope that held it"
        );
    }

    // Arrow-key pin moves: one slot per nudge, clamped at the block's top and
    // bottom slots.
    #[test]
    fn nudge_pins_shifts_one_slot_and_clamps_at_the_edges() {
        let (a, pa) = (block_id(1), pin_id(3));
        let mut scene = Scene::new(vec![tall_block(1), fx::pin(3, 1, DocPinSide::East, 1)]);
        let max = capacity(&mut scene, a);
        assert!(max >= 2, "the tall block must hold at least slots 0..=2");

        assert_eq!(slot(&mut scene, pa).offset, 1);
        scene.commit(|d| d.nudge_pins(&[pa], 1));
        assert_eq!(slot(&mut scene, pa).offset, 2);
        scene.commit(|d| d.nudge_pins(&[pa], -1));
        assert_eq!(slot(&mut scene, pa).offset, 1);
        // Clamp at the top.
        scene.commit(|d| d.nudge_pins(&[pa], -1));
        assert_eq!(slot(&mut scene, pa).offset, 0);
        scene.commit(|d| d.nudge_pins(&[pa], -1));
        assert_eq!(slot(&mut scene, pa).offset, 0);
        // Clamp at the bottom.
        scene.commit(|d| d.nudge_pins(&[pa], max as i32 + 5));
        assert_eq!(slot(&mut scene, pa).offset, max);
        scene.commit(|d| d.nudge_pins(&[pa], 1));
        assert_eq!(slot(&mut scene, pa).offset, max);
    }

    // A group of pins shifts rigidly, and is held in place when any member is
    // already at the boundary in the nudge direction.
    #[test]
    fn nudge_pins_moves_a_group_rigidly_and_stops_at_a_member_boundary() {
        let (p0, p1) = (pin_id(3), pin_id(4));
        let mut scene = Scene::new(vec![
            tall_block(1),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::pin(4, 1, DocPinSide::East, 1),
        ]);

        // p0 is at the top, so the whole group can't move up.
        scene.commit(|d| d.nudge_pins(&[p0, p1], -1));
        assert_eq!(
            (slot(&mut scene, p0).offset, slot(&mut scene, p1).offset),
            (0, 1)
        );
        // Down by one: both shift together.
        scene.commit(|d| d.nudge_pins(&[p0, p1], 1));
        assert_eq!(
            (slot(&mut scene, p0).offset, slot(&mut scene, p1).offset),
            (1, 2)
        );
    }

    // Deleting a multi-selection drops every shape in it.
    #[test]
    fn delete_shapes_removes_all_of_them() {
        let (a, b) = (block_id(1), block_id(2));
        let mut scene = Scene::new(vec![fx::block(1, 0.0), fx::block(2, 80.0)]);

        scene.commit(|d| d.delete(Deletable::Shapes(vec![ShapeId::Rect(a), ShapeId::Rect(b)])));

        let drawing = scene.drawing();
        assert!(drawing.block(a).is_none());
        assert!(drawing.block(b).is_none());
    }

    #[test]
    fn delete_pins_drops_the_pins_and_their_routes() {
        let (pa, pb, rid) = (pin_id(3), pin_id(4), route_id(5));
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, 120.0),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::pin(4, 2, DocPinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[]),
        ]);
        assert!(
            scene.drawing().auto_route(rid).is_some(),
            "precondition: the wire is in this scope"
        );

        scene.commit(|d| d.delete(Deletable::Pins(vec![pa])));

        let drawing = scene.drawing();
        assert!(drawing.held_pin(pa).is_none(), "the pin is gone");
        assert!(drawing.auto_route(rid).is_none(), "and the wire with it");
        assert!(drawing.held_pin(pb).is_some(), "the far endpoint survives");
    }

    #[test]
    fn relocate_pins_moves_a_free_group_but_rejects_a_collision() {
        // A tall block so several pin slots fit.
        let (p0, p1, blocker) = (pin_id(3), pin_id(4), pin_id(5));
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(40.0, 240.0)),
            ),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::pin(4, 1, DocPinSide::East, 1),
            fx::pin(5, 1, DocPinSide::East, 4),
        ]);
        let to = |pin, offset| PinMove {
            pin,
            to: PinSlot {
                side: DocPinSide::East,
                offset,
            },
        };

        // Shift the group {slot0, slot1} down by two slots → {2, 3}: free.
        let ok = [to(p0, 2), to(p1, 3)];
        assert!(scene.drawing().can_relocate_pins(&ok));
        assert!(scene.commit(|d| d.relocate_pins(&ok)));
        assert_eq!(slot(&mut scene, p0).offset, 2);
        assert_eq!(slot(&mut scene, p1).offset, 3);

        // Now shifting onto the blocker's slot (4) collides → rejected, no change.
        let bad = [to(p0, 3), to(p1, 4)];
        assert!(!scene.drawing().can_relocate_pins(&bad));
        assert!(!scene.commit(|d| d.relocate_pins(&bad)));
        assert_eq!(slot(&mut scene, p1).offset, 3);
        assert_eq!(slot(&mut scene, blocker).offset, 4);
    }

    // Vertical flip mirrors each pin's slot about the block center (offset →
    // h - offset), so a top pin lands at the bottom; a double flip is identity.
    #[test]
    fn flip_block_vertical_mirrors_pin_slots_and_is_an_involution() {
        let (a, top, mid, low) = (block_id(1), pin_id(3), pin_id(4), pin_id(5));
        let mut scene = Scene::new(vec![
            tall_block(1),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::pin(4, 1, DocPinSide::West, 1),
            fx::pin(5, 1, DocPinSide::East, 2),
        ]);
        let h = capacity(&mut scene, a);
        assert!(h >= 2, "the tall block must hold at least slots 0..=2");
        let before = (
            slot(&mut scene, top),
            slot(&mut scene, mid),
            slot(&mut scene, low),
        );

        scene.commit(|d| d.flip_block_vertical(a));

        // The top pin lands at the bottom slot; each pin keeps its side.
        assert_eq!(slot(&mut scene, top).offset, h);
        assert_eq!(slot(&mut scene, mid).offset, h - 1);
        assert_eq!(slot(&mut scene, low).offset, h - 2);
        assert_eq!(slot(&mut scene, top).side, before.0.side);
        assert_eq!(slot(&mut scene, mid).side, before.1.side);
        assert_eq!(slot(&mut scene, low).side, before.2.side);

        // Flipping again restores the original layout exactly.
        scene.commit(|d| d.flip_block_vertical(a));
        assert_eq!(slot(&mut scene, top).offset, before.0.offset);
        assert_eq!(slot(&mut scene, mid).offset, before.1.offset);
        assert_eq!(slot(&mut scene, low).offset, before.2.offset);
    }

    // ── Locked blocks ─────────────────────────────────────────────────────────

    #[test]
    fn pin_owner_locked_reads_the_pins_owning_block() {
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, 80.0),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::pin(4, 2, DocPinSide::East, 0),
            fx::locked(1),
        ]);
        let drawing = scene.drawing();
        assert!(drawing.pin_owner_locked(pin_id(3)));
        assert!(!drawing.pin_owner_locked(pin_id(4)));
        // A pin the document does not hold cannot be frozen by anything.
        assert!(!drawing.pin_owner_locked(pin_id(9)));
    }

    #[test]
    fn shape_owner_locked_covers_blocks_and_ports() {
        // Descend into `c` so its own pin renders as a port and the current
        // block (`c`) governs the port lock.
        let (c, g, port) = (block_id(1), block_id(2), pin_id(3));
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block_in(
                2,
                Scope::Block(c),
                Rect::from_min_max(pos2(60.0, 0.0), pos2(100.0, 40.0)),
            ),
            fx::pin_at(
                3,
                Scope::Block(c),
                "io",
                fx::slot(DocPinSide::West, 0),
                Rect::from_min_max(pos2(0.0, 0.0), pos2(40.0, 16.0)),
            ),
            fx::locked(1),
        ])
        .inside(c);
        let drawing = scene.drawing();
        // The current block `c` is locked, so its port reports locked.
        assert!(drawing.shape_owner_locked(ShapeId::Port(port)));
        assert!(drawing.current_locked());
        // The child block `g` is unlocked.
        assert!(!drawing.shape_owner_locked(ShapeId::Rect(g)));
    }

    /// The document root is a scope without a block entity behind it, so
    /// there is nothing to freeze — its ports are always editable.
    #[test]
    fn the_root_scope_is_never_locked() {
        let mut scene = Scene::new(vec![fx::pin_at(
            3,
            Scope::Root,
            "io",
            fx::slot(DocPinSide::West, 0),
            Rect::from_min_max(pos2(0.0, 0.0), pos2(40.0, 16.0)),
        )]);
        let drawing = scene.drawing();
        assert!(
            drawing.current().is_none(),
            "the root has no block entity, or this proves nothing"
        );
        assert!(!drawing.current_locked());
        assert!(!drawing.shape_owner_locked(ShapeId::Port(pin_id(3))));
    }

    #[test]
    fn delete_pin_is_a_no_op_on_a_locked_block() {
        let pa = pin_id(3);
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::locked(1),
        ]);
        let before = scene.doc.stamp();

        scene.commit(|d| d.delete(Deletable::Pins(vec![pa])));

        assert_eq!(
            scene.doc.stamp(),
            before,
            "a refused delete authors nothing"
        );
        assert!(
            scene.drawing().held_pin(pa).is_some(),
            "locked block keeps its pin"
        );
    }

    #[test]
    fn delete_port_is_a_no_op_on_a_locked_block() {
        // A port lives on the current scope's own boundary; lock that block and
        // delete one of its ports from inside.
        let (c, pc) = (block_id(1), pin_id(3));
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::pin_at(
                3,
                Scope::Block(c),
                "io",
                fx::slot(DocPinSide::West, 0),
                Rect::from_min_max(pos2(0.0, 0.0), pos2(40.0, 16.0)),
            ),
            fx::locked(1),
        ])
        .inside(c);
        let before = scene.doc.stamp();

        scene.commit(|d| d.delete(Deletable::Shape(ShapeId::Port(pc))));

        assert_eq!(
            scene.doc.stamp(),
            before,
            "a refused delete authors nothing"
        );
        assert!(
            scene.drawing().shape(ShapeId::Port(pc)).is_some(),
            "locked block keeps its port"
        );
    }

    #[test]
    fn set_block_locked_flips_the_flag() {
        let a = block_id(1);
        let mut scene = Scene::new(vec![fx::block(1, 0.0)]);
        let locked = |scene: &mut Scene| {
            scene
                .drawing()
                .held_block(a)
                .expect("the block is in the document")
                .locked
        };
        assert!(!locked(&mut scene));

        scene.commit(|d| d.set_block_locked(a, InterfaceLock::Locked));
        assert!(locked(&mut scene));
        scene.commit(|d| d.set_block_locked(a, InterfaceLock::Unlocked));
        assert!(!locked(&mut scene));
    }

    /// The lock's scope: a frozen interface is about what a pin *is*, not
    /// where it sits, so a locked block still repositions its pins.
    #[test]
    fn a_locked_block_still_repositions_its_pins() {
        let pa = pin_id(3);
        let mut scene = Scene::new(vec![
            tall_block(1),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::locked(1),
        ]);
        assert_eq!(slot(&mut scene, pa).offset, 0);
        assert!(scene.drawing().pin_owner_locked(pa), "precondition: frozen");

        scene.commit(|d| {
            d.move_pin_snapped(
                pa,
                PinSlot {
                    side: DocPinSide::East,
                    offset: 1,
                },
            );
        });

        assert_eq!(
            slot(&mut scene, pa).offset,
            1,
            "moving a pin along its block is presentation, which a lock allows",
        );
    }

    /// And the half the lock does keep: a frozen block refuses the edit that
    /// changes what its pin carries.
    #[test]
    fn a_locked_block_refuses_its_pins_direction() {
        let pa = pin_id(3);
        let mut scene = Scene::new(vec![
            tall_block(1),
            fx::pin(3, 1, DocPinSide::East, 0),
            fx::locked(1),
        ]);
        assert!(scene.drawing().pin_owner_locked(pa), "precondition: frozen");
        let before = scene.doc.stamp();

        scene.commit(|d| d.cycle_pin_kind(pa));

        assert_eq!(
            scene.doc.stamp(),
            before,
            "I/O direction is what the pin means, and a lock protects it",
        );
    }
}