blockworx/widget/

hit_target.rs

//! The canvas hit-test z-order, encoded once.
//!
//! Every pointer gesture — hover, click, double-click, drag — asks
//! [`Drawing::resolve_at_pos`] what is under the cursor and reacts to the answer.
//! Tools keep their reactions (which tool to switch to); none of them re-derives
//! *what was hit*, so hover, click and drag can never disagree about it.
//!
//! Two orders meet here. *Across kinds* the priority is editorial — labels
//! beat the bodies they sit on, a port beats a route crossing it — and
//! [`Drawing::resolve_at_pos`] is the only place it is written down.
//! *Within* a kind there is no separate hit order at all: hit order is draw
//! order back to front, so the shape painted last is tested first
//! ([`Drawing::hit_candidates`], the document's one `chronological` order
//! reversed). Every fine-phase test lives here too, so the priorities and
//! the tests they order can be read together.

use crate::{
    grid::{MOVE_HOVER_DISTANCE, PIN_PITCH, RESIZE_SHIM, ROUTE_HIT_MARGIN, TITLE_TEXT_SIZE},
    shape::{
        BaseShape, PinLocation, ShapeId, ShapeRef,
        pin::{Pin, PinSide, slot},
    },
    theme::Style,
    widget::{auto_route::hit_text_anchor, drawing::Drawing},
};
use blockworx_doc::id::{AreaId, BlockId, ImageId, PinId, RouteId, RouteLabelId};
use blockworx_geom::{Pos2, Rect, vec2};
use blockworx_paint::Renderer;

/// Which part of a pin was hit. The stub is last so a tag drawn over it (the
/// tag rises only a few pixels above the stub line) stays double-clickable.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum PinPart {
    Name,
    Type,
    Tag,
    Stub,
}

/// What sits at a point on the canvas, resolved top-down.
#[derive(Clone, Copy, Debug)]
pub enum HitTarget {
    /// A shape's title text.
    Title(ShapeId),
    /// A block's type label (or its "Add type" placeholder).
    BlockType(BlockId),
    /// A port's body, away from its own labels.
    Port(PinId),
    /// One part of a pin — on a child block or on a port (where the pin
    /// stands for the port itself).
    Pin {
        anchor: PinId,
        location: PinLocation,
        part: PinPart,
    },
    RouteLabel {
        route: RouteId,
        label: RouteLabelId,
    },
    Route(RouteId),
    /// A shape body: block, port, area, image, icon, or text box.
    Shape(ShapeId),
}

impl Drawing<'_> {
    /// What `pos` lands on, in priority order: labels first (title, block type,
    /// then a pin's name / type / tag / stub), then a port body, then routes,
    /// then any other shape body. `None` is empty canvas. A port is resolved
    /// ahead of the routes so grabbing one always moves the port, never a route
    /// crossing it; the rest of its body arrives as a plain [`HitTarget::Shape`].
    pub fn resolve_at_pos(
        &self,
        pos: Pos2,
        painter: &Style<'_, impl Renderer>,
    ) -> Option<HitTarget> {
        if let Some(shape) = self.title_at_pos(pos, painter) {
            return Some(HitTarget::Title(shape));
        }
        if let Some(rect) = self.type_at_pos(pos, painter) {
            return Some(HitTarget::BlockType(rect));
        }
        let as_part = |part| {
            move |(anchor, location)| HitTarget::Pin {
                anchor,
                location,
                part,
            }
        };
        if let Some(pin) = self
            .pin_text_at_pos(pos, painter)
            .map(as_part(PinPart::Name))
            .or_else(|| {
                self.pin_type_at_pos(pos, painter)
                    .map(as_part(PinPart::Type))
            })
            .or_else(|| self.pin_tag_at_pos(pos, painter).map(as_part(PinPart::Tag)))
            .or_else(|| self.pin_stub_at_pos(pos).map(as_part(PinPart::Stub)))
        {
            return Some(pin);
        }
        if let Some(port) = self.port_at_pos(pos) {
            return Some(HitTarget::Port(port));
        }
        if let Some((route, label)) = self.route_label_at_pos(pos, painter) {
            return Some(HitTarget::RouteLabel { route, label });
        }
        if let Some(route) = self.route_at_pos(pos) {
            return Some(HitTarget::Route(route));
        }
        self.shape_at_pos(pos).map(HitTarget::Shape)
    }
}

/// Slack added around a drawn label's text extent when hit-testing it, so small
/// text is comfortably clickable.
const LABEL_HIT_PAD: f32 = 4.0;

impl Drawing<'_> {
    pub fn port_at_pos(&self, pos: Pos2) -> Option<PinId> {
        self.ports_layer()
            .filter(|(_, shape)| shape.gui_rect().contains(pos))
            .filter_map(|(id, _)| match id {
                ShapeId::Port(pid) => Some(pid),
                _ => None,
            })
            .last()
    }

    /// Collect the child-block pins whose stub falls fully inside `marquee`.
    /// Only pins on child blocks are returned; boundary ports are
    /// marquee-selected as whole shapes, not as pins.
    pub fn pins_in_rect(&self, marquee: Rect) -> Vec<PinId> {
        let mut pins = Vec::new();
        for (id, shape) in self.shape_candidates(marquee) {
            if !id.is_block() {
                continue;
            }
            shape.with_pins(|pid, _| {
                if let Some(stub) = shape.pin_stub_rect(pid)
                    && marquee.intersects(stub)
                {
                    pins.push(pid);
                }
            });
        }
        pins
    }

    /// Find any shape at `pos`, honoring the paint layers top-down. Icons are the
    /// foreground layer, tested first. Areas are next — but by their *border*
    /// (and title), not their interior, so a click inside one falls through.
    /// Images are the next annotation layer (above the blocks), tested by their
    /// whole rect so an image drawn over a block is still selectable. Blocks,
    /// ports, and text boxes come last.
    pub fn shape_at_pos(&self, pos: Pos2) -> Option<ShapeId> {
        self.icon_at_pos(pos)
            .map(ShapeId::Icon)
            .or_else(|| self.area_at_pos(pos).map(ShapeId::Area))
            .or_else(|| self.image_at_pos(pos).map(ShapeId::Image))
            .or_else(|| {
                self.hit_candidates(Rect::from_min_max(pos, pos))
                    .into_iter()
                    .find_map(|(id, s)| match id {
                        // Already resolved above; skip so an image never shadows a
                        // block here in the wrong order.
                        ShapeId::Image(_) => None,
                        _ => s.gui_rect().contains(pos).then_some(id),
                    })
            })
    }

    /// Find the top-most free-floating image whose rect contains `pos`. Images
    /// are an annotation layer above the blocks, so they are hit-tested before
    /// blocks/ports (see [`Self::shape_at_pos`]). Later images (drawn on top) win
    /// ties.
    pub fn image_at_pos(&self, pos: Pos2) -> Option<ImageId> {
        self.images_layer()
            .filter(|(_, shape)| shape.gui_rect().contains(pos))
            .filter_map(|(id, _)| match id {
                ShapeId::Image(iid) => Some(iid),
                _ => None,
            })
            .last()
    }

    /// The block whose icon contains `pos`, if any. Icons are the foreground
    /// layer (drawn above everything), so they are hit-tested before any other
    /// shape (see [`Self::shape_at_pos`]). Later child blocks (drawn on top) win
    /// ties.
    pub fn icon_at_pos(&self, pos: Pos2) -> Option<BlockId> {
        self.icons()
            .filter(|(_, shape)| shape.gui_rect().contains(pos))
            .filter_map(|(id, _)| match id {
                ShapeId::Icon(bid) => Some(bid),
                _ => None,
            })
            .last()
    }

    /// Find an area whose *border* (within [`RESIZE_SHIM`] of the outline) or
    /// title text contains `pos`. The interior is deliberately not hit-testable
    /// so clicks pass through to shapes beneath the area. Later areas (drawn
    /// on top) win ties.
    pub fn area_at_pos(&self, pos: Pos2) -> Option<AreaId> {
        let mut hit = None;
        for (id, area) in self.areas() {
            let ShapeId::Area(cid) = id else { continue };
            let rect = area.gui_rect();
            let on_border =
                rect.expand(RESIZE_SHIM).contains(pos) && !rect.shrink(RESIZE_SHIM).contains(pos);
            let on_title = area
                .title_anchor()
                .is_some_and(|a| pos.distance(a) < MOVE_HOVER_DISTANCE);
            if on_border || on_title {
                hit = Some(cid);
            }
        }
        hit
    }

    pub fn anchor_at_pos(&self, pos: Pos2) -> Option<PinId> {
        for (_, shape) in self.hit_candidates(Rect::from_min_max(pos, pos)) {
            let rect = shape.gui_rect();
            let mut found: Option<PinId> = None;
            shape.with_pins(|pin_id, _pin| {
                if found.is_some() {
                    return;
                }
                // Snap to a pin anywhere near its end or along its stub, so the
                // route tool registers without precise aim at the connection point.
                let near_end = shape
                    .anchor_point_with_rect(rect, pin_id)
                    .is_some_and(|end| end.distance(pos) < ROUTE_HIT_MARGIN.get());
                let near_stub = shape
                    .pin_stub_rect(pin_id)
                    .is_some_and(|stub| stub.expand(ROUTE_HIT_MARGIN.get()).contains(pos));
                if near_end || near_stub {
                    found = Some(pin_id);
                }
            });
            if found.is_some() {
                return found;
            }
        }
        None
    }

    /// Every pin/port anchor in the current view paired with its stub-end point.
    /// The all-anchors generalization of [`Self::anchor_at_pos`], used to drive the
    /// route-start/end hover targets.
    pub fn anchor_targets(&self) -> Vec<(PinId, Pos2)> {
        let mut out = Vec::new();
        for (_, shape) in self.shapes() {
            let rect = shape.gui_rect();
            shape.with_pins(|pin_id, _pin| {
                if let Some(end) = shape.anchor_point_with_rect(rect, pin_id) {
                    out.push((pin_id, end));
                }
            });
        }
        out
    }

    /// The block side (East/West) `anchor`'s pin sits on — i.e. the direction its
    /// stub, and a route leaving it, extend. Used to point the drag-to-route hint.
    pub fn anchor_side(&self, anchor: PinId) -> Option<PinSide> {
        Some(slot(self.held_pin(anchor)?).side)
    }

    pub fn route_label_at_pos(
        &self,
        pos: Pos2,
        painter: &Style<'_, impl Renderer>,
    ) -> Option<(RouteId, RouteLabelId)> {
        self.route_candidates(Rect::from_min_max(pos, pos))
            .into_iter()
            .find_map(|(route_id, wire)| {
                hit_text_anchor(
                    &wire.route.name,
                    &wire.labels,
                    self.route_geometry(route_id)?,
                    pos,
                    painter,
                )
                .map(|label_id| (route_id, label_id))
            })
    }

    pub fn route_at_pos(&self, pos: Pos2) -> Option<RouteId> {
        self.route_candidates(Rect::from_min_max(pos, pos))
            .into_iter()
            .filter_map(|(route_id, _)| {
                self.route_geometry(route_id)?
                    .hovered_edge_distance(pos)
                    .map(|d| (route_id, d))
            })
            .min_by(|(_, a), (_, b)| a.total_cmp(b))
            .map(|(route_id, _)| route_id)
    }

    /// The first pin whose `hit_rect` contains `pos`, scanning pin-bearing
    /// candidates in layer order. `hit_rect` yields the already-padded rect for
    /// the part of the pin being tested, or `None` for a pin that doesn't draw
    /// that part.
    fn pin_part_at_pos(
        &self,
        pos: Pos2,
        hit_rect: impl Fn(&ShapeRef<'_>, PinId, &Pin) -> Option<Rect>,
    ) -> Option<(PinId, PinLocation)> {
        for (_, shape) in self.hit_candidates(Rect::from_min_max(pos, pos)) {
            let mut found: Option<(PinId, PinLocation)> = None;
            shape.with_pins(|pid, pin| {
                if found.is_none()
                    && hit_rect(&shape, pid, pin).is_some_and(|rect| rect.contains(pos))
                {
                    let slot = slot(pin);
                    found = Some((
                        pid,
                        PinLocation {
                            side: slot.side,
                            offset: slot.offset as f32 * PIN_PITCH,
                        },
                    ));
                }
            });
            if found.is_some() {
                return found;
            }
        }
        None
    }

    pub fn pin_text_at_pos(
        &self,
        pos: Pos2,
        painter: &Style<'_, impl Renderer>,
    ) -> Option<(PinId, PinLocation)> {
        self.pin_part_at_pos(pos, |shape, pid, _| {
            Some(shape.pin_text_rect(pid, painter)?.expand(LABEL_HIT_PAD))
        })
    }

    /// Like [`Self::pin_text_at_pos`], but hit-tests each pin's `type` label
    /// (the smaller second line) instead of its `name`.
    pub fn pin_type_at_pos(
        &self,
        pos: Pos2,
        painter: &Style<'_, impl Renderer>,
    ) -> Option<(PinId, PinLocation)> {
        self.pin_part_at_pos(pos, |shape, pid, _| {
            Some(shape.pin_type_rect(pid, painter)?.expand(LABEL_HIT_PAD))
        })
    }

    /// Like [`Self::pin_text_at_pos`], but hit-tests each pin's stub (the red
    /// line) instead of its `name`. Used by tools that act on the stub.
    pub fn pin_stub_at_pos(&self, pos: Pos2) -> Option<(PinId, PinLocation)> {
        self.pin_part_at_pos(pos, |shape, pid, _| shape.pin_stub_rect(pid))
    }

    /// Like [`Self::pin_text_at_pos`], but hit-tests each pin's `tag` label
    /// (drawn above the stub) instead of its `name`. A hidden tag draws nothing,
    /// so it is not hit-testable. A shown but empty tag is hit-tested against its
    /// "+tag" placeholder extent so the prompt is double-clickable to start
    /// editing.
    pub fn pin_tag_at_pos(
        &self,
        pos: Pos2,
        painter: &Style<'_, impl Renderer>,
    ) -> Option<(PinId, PinLocation)> {
        self.pin_part_at_pos(pos, |shape, pid, pin| {
            if pin.tag_hidden {
                return None;
            }
            let tag = pin.tag.clone();
            let text = if tag.is_empty() {
                crate::render::ADD_TAG_PLACEHOLDER
            } else {
                &tag
            };
            Some(
                shape
                    .tag_text_rect_for(pid, text, painter)?
                    .expand(LABEL_HIT_PAD),
            )
        })
    }

    /// Find a titled shape whose title text bbox contains `pos`. Blocks and
    /// areas have titles; areas (the top layer) are tested first. Ports and
    /// text boxes have no title and are skipped.
    pub fn title_at_pos(&self, pos: Pos2, painter: &Style<'_, impl Renderer>) -> Option<ShapeId> {
        for (id, shape) in self
            .areas()
            .chain(self.hit_candidates(Rect::from_min_max(pos, pos)))
        {
            if let Some(title) = shape.title() {
                let text_width = painter.text_size(title.name, &painter.theme().title_font).x;
                let title_width = (text_width + 10.0).max(20.0);
                // The clamped position — where the title actually draws (a
                // resize can leave a stored offset outside the block).
                let (title_pos, title_align) = crate::render::clamped_block_title_position(
                    shape.gui_rect(),
                    &title,
                    text_width,
                );
                let bbox = title_align.anchor_size(title_pos, vec2(title_width, TITLE_TEXT_SIZE));
                if bbox.expand(LABEL_HIT_PAD).contains(pos) {
                    return Some(id);
                }
            }
        }
        None
    }

    /// Find a titled shape whose title anchor handle is near `pos`. Blocks and
    /// areas have title anchors; areas (the top layer) are tested first.
    pub fn title_anchor_at_pos(&self, pos: Pos2) -> Option<ShapeId> {
        for (id, shape) in self
            .areas()
            .chain(self.hit_candidates(Rect::from_min_max(pos, pos)))
        {
            if let Some(anchor) = shape.title_anchor()
                && pos.distance(anchor) < MOVE_HOVER_DISTANCE
            {
                return Some(id);
            }
        }
        None
    }

    /// Find a block whose type-label text bbox contains `pos`. An empty type is
    /// hit-tested against its "Add type" placeholder extent so the prompt is
    /// double-clickable to start editing.
    pub fn type_at_pos(&self, pos: Pos2, painter: &Style<'_, impl Renderer>) -> Option<BlockId> {
        for (shape_id, shape) in self.hit_candidates(Rect::from_min_max(pos, pos)) {
            let ShapeId::Rect(id) = shape_id else {
                continue;
            };
            let ShapeRef::Block(block) = shape else {
                continue;
            };
            if let Some(type_label) = block.type_label() {
                let text = if type_label.name.is_empty() {
                    crate::render::ADD_TYPE_PLACEHOLDER
                } else {
                    type_label.name
                };
                let text_width = painter.text_size(text, &painter.theme().type_font).x;
                let width = (text_width + 10.0).max(20.0);
                // Match the draw: a committed type clamps into the block, the
                // empty-slot placeholder draws unclamped.
                let (pos_anchor, align) = if type_label.name.is_empty() {
                    crate::render::block_type_position(block.gui_rect(), &type_label)
                } else {
                    crate::render::clamped_block_type_position(
                        block.gui_rect(),
                        &type_label,
                        text_width,
                    )
                };
                let bbox = align.anchor_size(pos_anchor, vec2(width, TITLE_TEXT_SIZE));
                if bbox.expand(LABEL_HIT_PAD).contains(pos) {
                    return Some(id);
                }
            }
        }
        None
    }

    /// Resolve a pin to its world-space position in this scope: the tip of
    /// the port body when the pin is the scope's own boundary, the tip of
    /// its stub on the child block otherwise — the same split
    /// [`Drawing::pin_shape`] resolves everywhere else.
    pub fn anchor(&self, anchor: PinId) -> Option<Pos2> {
        let shape = self.shape(self.pin_shape(anchor)?)?;
        shape.anchor_point_with_rect(shape.gui_rect(), anchor)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::{
        canvas::Painter,
        theme::Theme,
        widget::test_fixtures::{self as fx, Scene},
    };
    use blockworx_doc::fixtures::{block_id, image_id, pin_id};
    use blockworx_geom::pos2;

    /// Run `check` against a `Drawing` over `scene` inside a headless egui pass,
    /// with a painter the label hit-tests can measure text with.
    fn with_drawing(scene: &mut Scene, check: impl Fn(&Drawing<'_>, &Style<'_, Painter>)) {
        let ctx = egui::Context::default();
        // The label hit-tests measure text in `CANVAS_FAMILY`, which nothing
        // binds until the app's fonts are installed on the following pass.
        ctx.set_fonts(crate::canvas::build_fonts(
            blockworx_paint::FontChoice::default(),
        ));
        ctx.run_ui(egui::RawInput::default(), |_| {})
            .drop_without_applying_deltas();
        ctx.run_ui(egui::RawInput::default(), |ui| {
            let drawing = scene.drawing();
            let theme = Theme::default();
            let mut painter = Painter::headless(ui.painter().clone(), theme.palette().clone());
            let style = Style::new(&theme, &mut painter);
            check(&drawing, &style);
        })
        .drop_without_applying_deltas();
    }

    /// A stale title offset (a resize can shrink the block under a dragged
    /// title) draws clamped back inside the block; the hit test must find the
    /// title where it draws, not at the stale offset.
    #[test]
    fn a_clamped_title_is_hit_where_it_draws() {
        use crate::grid::{GRID_SIZE, TITLE_TEXT_SIZE};
        let id = block_id(1);
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(300.0, 300.0), pos2(300.0 + 4.0 * GRID_SIZE, 420.0)),
            ),
            fx::titled(1, "a rather long title"),
            fx::title_offset(1, 500.0),
        ]);
        with_drawing(&mut scene, |drawing, style| {
            let (drawn_center, stale_center) = {
                let shape = drawing.shape(ShapeId::Rect(id)).unwrap();
                let title = shape.title().unwrap();
                let text_width = style.text_size(title.name, &style.theme().title_font).x;
                let (drawn, align) = crate::render::clamped_block_title_position(
                    shape.gui_rect(),
                    &title,
                    text_width,
                );
                let (stale, _) = crate::render::block_title_position(shape.gui_rect(), &title);
                // Precondition: the stale offset genuinely diverges from the
                // drawn position, or this test distinguishes nothing.
                assert!(
                    (stale.x - drawn.x).abs() > 4.0 * GRID_SIZE,
                    "stale {stale:?} vs drawn {drawn:?}"
                );
                (
                    align
                        .anchor_size(drawn, vec2(text_width, TITLE_TEXT_SIZE))
                        .center(),
                    align
                        .anchor_size(stale, vec2(text_width, TITLE_TEXT_SIZE))
                        .center(),
                )
            };
            assert_eq!(
                drawing.title_at_pos(drawn_center, style),
                Some(ShapeId::Rect(id)),
                "the drawn title must be hittable"
            );
            assert_eq!(
                drawing.title_at_pos(stale_center, style),
                None,
                "the stale position draws nothing and must not hit"
            );
        });
    }

    /// One 300×300 block titled "b", typed "T", carrying a west pin named "in"
    /// with a type and a visible tag — so its title, its pin's label cluster,
    /// and its body all overlap somewhere.
    fn overlapping_targets() -> Scene {
        Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(300.0, 300.0), pos2(600.0, 600.0)),
            ),
            fx::titled(1, "b"),
            fx::typed(1, "T"),
            fx::pin(3, 1, PinSide::West, 0),
            fx::pin_typed(3, "u8"),
            fx::pin_tagged(3, "T1"),
            fx::pin_tag_shown(3),
        ])
    }

    #[test]
    fn a_title_wins_over_the_block_body_beneath_it() {
        let rid = block_id(1);
        with_drawing(&mut overlapping_targets(), |data, painter| {
            let title = data
                .shape(ShapeId::Rect(rid))
                .unwrap()
                .title_anchor()
                .unwrap();
            assert!(
                data.shape_at_pos(title).is_some(),
                "the probe must also be over the body, or the test proves nothing"
            );
            assert!(matches!(
                data.resolve_at_pos(title, painter),
                Some(HitTarget::Title(ShapeId::Rect(hit))) if hit == rid
            ));
        });
    }

    #[test]
    fn a_pin_name_wins_over_the_block_body_beneath_it() {
        with_drawing(&mut overlapping_targets(), |data, painter| {
            let block = data.shape(ShapeId::Rect(block_id(1))).unwrap();
            let probe = block.pin_text_rect(pin_id(3), painter).unwrap().center();
            assert!(data.shape_at_pos(probe).is_some());
            assert!(matches!(
                data.resolve_at_pos(probe, painter),
                Some(HitTarget::Pin {
                    part: PinPart::Name,
                    ..
                })
            ));
        });
    }

    #[test]
    fn a_pin_tag_wins_over_the_stub_it_is_drawn_over() {
        with_drawing(&mut overlapping_targets(), |data, painter| {
            let block = data.shape(ShapeId::Rect(block_id(1))).unwrap();
            let tag = block.tag_text_rect_for(pin_id(3), "T1", painter).unwrap();
            let stub = block.pin_stub_rect(pin_id(3)).unwrap();
            let probe = tag.intersect(stub).center();
            assert!(
                tag.intersects(stub),
                "the tag must overlap the stub, or the test proves nothing"
            );
            assert!(matches!(
                data.resolve_at_pos(probe, painter),
                Some(HitTarget::Pin {
                    part: PinPart::Tag,
                    ..
                })
            ));
        });
    }

    #[test]
    fn a_bare_stub_still_resolves_to_the_stub() {
        with_drawing(&mut overlapping_targets(), |data, painter| {
            let block = data.shape(ShapeId::Rect(block_id(1))).unwrap();
            let stub = block.pin_stub_rect(pin_id(3)).unwrap();
            let probe = pos2(stub.center().x, stub.bottom() - 1.0);
            assert!(matches!(
                data.resolve_at_pos(probe, painter),
                Some(HitTarget::Pin {
                    part: PinPart::Stub,
                    ..
                })
            ));
        });
    }

    #[test]
    fn a_body_hit_with_nothing_over_it_resolves_to_the_shape() {
        let rid = block_id(1);
        with_drawing(&mut overlapping_targets(), |data, painter| {
            let probe = data.shape(ShapeId::Rect(rid)).unwrap().gui_rect().center();
            assert!(matches!(
                data.resolve_at_pos(probe, painter),
                Some(HitTarget::Shape(ShapeId::Rect(hit))) if hit == rid
            ));
        });
    }

    // A port's name is drawn inside its body, and double-clicking it is how a
    // port is renamed — so the label must win over the body it sits on.
    #[test]
    fn a_port_name_wins_over_the_port_body_beneath_it() {
        let port = pin_id(4);
        let mut scene = Scene::new(vec![fx::pin_at(
            4,
            Scope::Root,
            "Port 4",
            fx::slot(PinSide::West, 0),
            Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 30.0)),
        )]);
        with_drawing(&mut scene, |data, painter| {
            let probe = data
                .shape(ShapeId::Port(port))
                .unwrap()
                .pin_text_rect(port, painter)
                .unwrap()
                .center();
            assert_eq!(data.port_at_pos(probe), Some(port));
            assert!(matches!(
                data.resolve_at_pos(probe, painter),
                Some(HitTarget::Pin {
                    anchor,
                    part: PinPart::Name,
                    ..
                }) if anchor == port
            ));
        });
    }

    #[test]
    fn empty_canvas_resolves_to_nothing() {
        with_drawing(&mut overlapping_targets(), |data, painter| {
            assert!(data.resolve_at_pos(pos2(-500.0, -500.0), painter).is_none());
        });
    }

    #[test]
    fn an_image_over_a_block_is_hit_first() {
        // Images are an annotation layer above the blocks, so a click on an image
        // sitting over a block selects the image, not the block underneath.
        let sid = image_id(5);
        let mut scene = Scene::new(vec![
            fx::asset().1,
            fx::block(1, 0.0), // (0,0)..(45,60)
            fx::image(
                5,
                Scope::Root,
                Rect::from_min_max(pos2(10.0, 10.0), pos2(30.0, 30.0)),
            ),
        ]);
        let drawing = scene.drawing();
        let center = drawing
            .shape(ShapeId::Image(sid))
            .unwrap()
            .gui_rect()
            .center();
        assert!(
            drawing
                .shape(ShapeId::Rect(block_id(1)))
                .unwrap()
                .gui_rect()
                .contains(center),
            "the probe must be over the block too, or the test proves nothing"
        );
        assert_eq!(
            drawing.shape_at_pos(center),
            Some(ShapeId::Image(sid)),
            "the image wins the hit over the block beneath it"
        );
    }

    #[test]
    fn an_icon_is_selectable_like_any_shape() {
        // An icon is a first-class shape: clicking it selects it directly (no
        // need to select its block first). It is the foreground layer, so it is
        // hit-tested before the block beneath it, and the indexed and linear
        // paths must agree — `icon_at_pos` is index-independent.
        use crate::widget::spatial::SpatialIndex;
        let a = block_id(1);
        let icon_box = Rect::from_min_max(pos2(8.0, 8.0), pos2(32.0, 32.0));
        let mut scene = Scene::new(vec![
            fx::asset().1,
            fx::block(1, 0.0),
            fx::icon(1, icon_box),
        ]);
        let probe = icon_box.center();

        let linear = scene.drawing().shape_at_pos(probe);
        let index = SpatialIndex::from_drawing(&scene.drawing());
        let Scene {
            doc,
            index: doc_index,
            presentation,
            gesture,
            path,
            ..
        } = &mut scene;
        let indexed =
            Drawing::new_indexed(doc_index.view(doc), path, &index, presentation, gesture)
                .shape_at_pos(probe);
        assert_eq!(
            linear,
            Some(ShapeId::Icon(a)),
            "clicking an icon selects it"
        );
        assert_eq!(indexed, linear, "indexed and linear hit-tests must agree");
    }

    #[test]
    fn pins_in_rect_collects_only_enclosed_child_block_pins() {
        let (a, pa) = (block_id(1), pin_id(3));
        let mut scene = Scene::new(vec![fx::block(1, 0.0), fx::pin(3, 1, PinSide::East, 0)]);
        let drawing = scene.drawing();

        let stub = drawing
            .shape(ShapeId::Rect(a))
            .unwrap()
            .pin_stub_rect(pa)
            .unwrap();
        assert_eq!(drawing.pins_in_rect(stub.expand(5.0)), vec![pa]);
        let far = Rect::from_min_size(pos2(1000.0, 1000.0), vec2(20.0, 20.0));
        assert!(drawing.pins_in_rect(far).is_empty());
    }

    // A marquee that only *touches* a pin's stub (without enclosing it) still
    // selects the pin — `pins_in_rect` tests `intersects`, not `contains_rect`.
    #[test]
    fn pins_in_rect_selects_a_pin_whose_stub_is_merely_touched() {
        let (a, pa) = (block_id(1), pin_id(3));
        let mut scene = Scene::new(vec![fx::block(1, 0.0), fx::pin(3, 1, PinSide::East, 0)]);
        let drawing = scene.drawing();
        let stub = drawing
            .shape(ShapeId::Rect(a))
            .unwrap()
            .pin_stub_rect(pa)
            .unwrap();
        // A thin sliver over the stub's outer edge: overlaps but cannot enclose.
        let touch = Rect::from_min_max(
            pos2(stub.right() - 1.0, stub.top()),
            pos2(stub.right() + 5.0, stub.bottom()),
        );
        assert!(
            !touch.contains_rect(stub),
            "marquee must not enclose the stub"
        );
        assert_eq!(drawing.pins_in_rect(touch), vec![pa]);
    }

    // The route tool snaps to a pin from anywhere near its stub or its end, with
    // a margin wider than the old `HIT_RADIUS`.
    #[test]
    fn anchor_at_pos_snaps_from_near_the_stub_or_a_widened_end() {
        let (a, pa) = (block_id(1), pin_id(3));
        let mut scene = Scene::new(vec![fx::block(1, 0.0), fx::pin(3, 1, PinSide::East, 0)]);
        let drawing = scene.drawing();
        let (stub_center, head) = {
            let s = drawing.shape(ShapeId::Rect(a)).unwrap();
            (
                s.pin_stub_rect(pa).unwrap().center(),
                s.anchor_point_with_rect(s.gui_rect(), pa).unwrap(),
            )
        };
        // Anywhere along the stub registers.
        assert_eq!(drawing.anchor_at_pos(stub_center), Some(pa));
        // Past the old 9px HIT_RADIUS but within ROUTE_HIT_MARGIN of the end.
        let near = head + vec2(12.0, 0.0);
        assert!(head.distance(near) > crate::grid::HIT_RADIUS.get());
        assert!(head.distance(near) < ROUTE_HIT_MARGIN.get());
        assert_eq!(drawing.anchor_at_pos(near), Some(pa));
        // Far away: nothing.
        assert!(drawing.anchor_at_pos(pos2(500.0, 500.0)).is_none());
    }
}