blockworx/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::theme::Style;
use crate::{
    edit::{
        self,
        geometry::PinMove,
        naming::{InterfaceLock, LabelFitWidth, TagVisibility},
    },
    grid::{artwork_rect, pin_slot},
    path::BlockPath,
    shape::{BlockShape, PinLocation, PortShape, ShapeId, ShapeRef},
    tools::tool::{Deletable, RoleTarget},
    widget::{
        auto_route::{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 a preview supposes this frame that the document does not hold:
/// shapes at hypothetical rects, and the routes re-solved against them. The
/// cull set reads it — a shape whose committed rect is off screen must still
/// draw when its preview is on screen — and a [`Drawing`] is one frame, so a
/// supposition cannot outlive the frame that made it.
#[derive(Default)]
pub(crate) struct Supposed {
    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,
    supposed: Supposed,
}

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

/// Materialize the whole document for display. 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::materialize_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-materialize, and a foreign commit can land anywhere.
///
/// Read-only — the sink it opens is local and discarded, because a
/// materialization pass has nothing to author. Call it through
/// [`Presentation::refresh_routes`](crate::presentation::Presentation::refresh_routes),
/// which owns the stamp gate.
pub(crate) fn materialize_document(
    indexed: &IndexedDocument<'_>,
    presentation: &mut crate::presentation::Presentation,
) {
    let scopes: Vec<crate::path::Scope> = indexed
        .index
        .blocks
        .iter()
        .filter(|(_, entry)| !entry.routes.is_empty())
        .map(|(&id, _)| crate::path::Scope::from_wire(id))
        .collect();
    // 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
        .routes
        .retain(|id, _| indexed.doc.route(id).is_some());
    let mut discarded = crate::gesture::Gesture::idle();
    for scope in scopes {
        let mut path = BlockPath::empty();
        if let crate::path::Scope::Block(id) = scope {
            path.push(id);
        }
        Drawing::new(*indexed, &path, presentation, &mut discarded).materialize_routes();
    }
    debug_assert!(
        discarded.ops().is_empty(),
        "materialization is a read; it must author nothing"
    );
}

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,
            supposed: Supposed::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(crate) 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,
            supposed: Supposed::default(),
        }
    }

    /// The scope being drawn: the path's last segment, or the document
    /// root, which is a scope like any other (F9).
    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(crate) 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 `LineAnchor` used to encode, resolved once as the document
    /// read it always was.
    pub(crate) 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(crate) 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(crate) 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(crate) 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(crate) 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(crate) 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(super) 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.
    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 materialized — 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.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),
            // A text box's extent follows its content, so it carries no
            // handles to drag.
            ShapeId::Text(_) => return,
        };
        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 *this* client was not the one typing — an undo, a redo, a
    /// collaborator's edit — and an extent written only by the editor leaves
    /// those boxes on the character-count estimate until someone re-opens
    /// them, which is what they did. 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, String)> = self
            .scope_texts()
            .into_iter()
            .filter(|(id, text)| {
                self.presentation
                    .text_extents
                    .valid_for(*id, &text.text)
                    .is_none()
            })
            .map(|(id, text)| (id, text.text.clone()))
            .collect();
        for (id, text) in stale {
            // The same measurement the editor used to commit, so the box does
            // not change size the first time it is re-opened.
            let size = crate::render::text_box::measure_box_size(painter, &text);
            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: it used to be "Go Up" at the
    /// document root, which read as a navigation button that quietly wrote
    /// a block (docs/ui-issues-2.md, item 8). The emitter keeps working;
    /// where the user asks for it from is still open.
    #[expect(
        dead_code,
        reason = "unhooked from Go Up until it is given a home of its own"
    )]
    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.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 [`MoveMultiPin`](crate::tools) 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
    /// picture, 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(crate) 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(crate) 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 suppose_shapes(&mut self, previews: &[(ShapeId, Rect)]) {
        self.supposed.shapes.clear();
        for &(id, rect) in previews {
            self.supposed.shapes.push((id, rect));
            if let Some(icon) = id.block().map(ShapeId::Icon)
                && self.shape(icon).is_some()
            {
                self.supposed.shapes.push((icon, rect));
            }
        }
    }

    /// Record the wires this frame's preview re-solved — the ones now drawn
    /// somewhere the document does not put them.
    pub(super) fn suppose_routes(&mut self, routes: Vec<RouteId>) {
        self.supposed.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 supposition 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.supposed.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.supposed.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)
    }

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::{
        edit::lower::slot_capacity,
        grid::GRID_SIZE,
        tools::tool::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};

    /// 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 picture, 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 mut backend = crate::export::svg::SvgRenderer::new(
            theme.palette().clone(),
            blockworx_paint::FontChoice::default(),
        );
        let style = Style::new(&theme, &mut backend);
        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 = drawing
            .content_bounds(&style)
            .expect("the scene draws something");
        assert!(
            bounds.contains_rect(wire),
            "the fit cropped the wire: {bounds:?} does not hold {wire:?}",
        );
    }

    /// B1, structurally: a gesture reads the session's prediction, which only
    /// advances at submit — so before the write door staged the sink, a block
    /// created mid-gesture was invisible to the rest of that gesture, and four
    /// tools carried an `Arming` state to defer the read by a frame.
    ///
    /// 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",
            );
        });
    }

    /// B9: a text box's bounds went stale whenever this client was not the
    /// one typing. The extent was written only by the editor's commit, so an
    /// undo — or a collaborator's edit — left the box drawn and hit-tested at
    /// its character-count estimate until someone double-clicked it to start
    /// another edit cycle.
    ///
    /// Measured on demand now, 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(
            ctx: &egui::Context,
            scene: &mut Scene,
            id: TextId,
        ) -> Option<blockworx_doc::geometry::GridSize> {
            let mut out = None;
            ctx.run_ui(egui::RawInput::default(), |ui| {
                let theme = crate::theme::Theme::default();
                let mut painter =
                    crate::canvas::Painter::headless(ui.painter().clone(), theme.palette().clone());
                let style = crate::theme::Style::new(&theme, &mut painter);
                let mut drawing = scene.drawing();
                drawing.refresh_text_extents(&style);
                let Some(text) = drawing.text_box(id).map(|t| t.text.clone()) else {
                    return;
                };
                out = drawing.presentation.text_extents.valid_for(id, &text);
            })
            .drop_without_applying_deltas();
            out
        }

        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 ctx = egui::Context::default();
        ctx.set_fonts(crate::canvas::build_fonts(
            blockworx_paint::FontChoice::default(),
        ));
        // Fonts land from the next frame, and this measures text.
        ctx.run_ui(egui::RawInput::default(), |_| {})
            .drop_without_applying_deltas();

        // 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!(
            scene
                .drawing()
                .presentation
                .text_extents
                .valid_for(id, "short")
                .is_none(),
            "precondition: no extent has been measured yet",
        );
        let short = frame(&ctx, &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 that has to wrap onto several lines",
        )]);
        let grown = frame(&ctx, &mut scene, id).expect("the next frame measured the new text");

        assert!(
            grown.h > short.h,
            "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 — the tool's drag 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)));
    }

    /// F9: 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, settled 2026-08-24: a frozen interface is about what
    /// a pin *is*, not where it sits, so a locked block still repositions its
    /// pins. This asserted the opposite until then — step 10's lock
    /// unification had widened the guard past the interface and into layout.
    #[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",
        );
    }
}