blockworx/widget/

alignment.rs

//! Alignment guides shown while dragging. A dragged element's features (edges,
//! centers, pin stubs, or a single corner) are matched against the same features
//! of every other shape; each like-kind coincidence draws a thin line spanning
//! the aligned pair, drawn over the diagram so a center guide (which runs
//! through the opaque shapes it aligns) stays visible.
//!
//! Grid-quantized shapes (blocks, areas) coincide at discrete grid steps, so
//! their guides are stable. Free-positioned images/icons don't, so
//! [`snap_drag_offset`] makes their drag magnetic — snapping a center onto a
//! nearby feature so the guide lands instead of merely flashing past.

use blockworx_doc::id::PinId;
use blockworx_geom::{Pos2, Rect, Vec2, pos2, vec2};

use crate::{
    edit::geometry::PinMove,
    grid::PIN_PITCH,
    shape::{
        ShapeId, ShapeRef,
        pin::{PinSide, slot},
    },
    theme::{Role, Style},
    widget::drawing::Drawing,
};
use blockworx_paint::Renderer;

/// Coordinates within this many world units count as aligned when drawing a
/// guide (only absorbs float error — grid shapes coincide exactly).
const EPS: f32 = 0.5;

/// How near (world units) a freely-dragged image/icon feature must be to a static
/// feature for [`snap_drag_offset`] to pull it into exact alignment.
const SNAP_RADIUS: f32 = 6.0;

#[derive(Clone, Copy, PartialEq)]
enum Axis {
    /// A constant-x line; its perpendicular span is a y range.
    Vertical,
    /// A constant-y line; its perpendicular span is an x range.
    Horizontal,
}

#[derive(Clone, Copy, PartialEq)]
enum Kind {
    Edge,
    Center,
    PinStub,
}

#[derive(Clone, Copy)]
struct Candidate {
    axis: Axis,
    kind: Kind,
    coord: f32,
    lo: f32,
    hi: f32,
}

/// A rect's four edge candidates (the left/right verticals, top/bottom
/// horizontals) — no centers.
fn push_rect_edges(rect: Rect, out: &mut Vec<Candidate>) {
    let (t, b, l, r) = (rect.top(), rect.bottom(), rect.left(), rect.right());
    out.push(Candidate {
        axis: Axis::Vertical,
        kind: Kind::Edge,
        coord: l,
        lo: t,
        hi: b,
    });
    out.push(Candidate {
        axis: Axis::Vertical,
        kind: Kind::Edge,
        coord: r,
        lo: t,
        hi: b,
    });
    out.push(Candidate {
        axis: Axis::Horizontal,
        kind: Kind::Edge,
        coord: t,
        lo: l,
        hi: r,
    });
    out.push(Candidate {
        axis: Axis::Horizontal,
        kind: Kind::Edge,
        coord: b,
        lo: l,
        hi: r,
    });
}

fn push_rect_candidates(rect: Rect, out: &mut Vec<Candidate>) {
    push_rect_edges(rect, out);
    let (t, b, l, r) = (rect.top(), rect.bottom(), rect.left(), rect.right());
    out.push(Candidate {
        axis: Axis::Vertical,
        kind: Kind::Center,
        coord: rect.center().x,
        lo: t,
        hi: b,
    });
    out.push(Candidate {
        axis: Axis::Horizontal,
        kind: Kind::Center,
        coord: rect.center().y,
        lo: l,
        hi: r,
    });
}

/// A single point contributes one vertical and one horizontal guide candidate.
fn push_point_candidates(p: Pos2, kind: Kind, out: &mut Vec<Candidate>) {
    out.push(Candidate {
        axis: Axis::Vertical,
        kind,
        coord: p.x,
        lo: p.y,
        hi: p.y,
    });
    out.push(Candidate {
        axis: Axis::Horizontal,
        kind,
        coord: p.y,
        lo: p.x,
        hi: p.x,
    });
}

/// Each pin's stub row: a *horizontal* guide at the stub's y, shifted by
/// `offset`. Only the row is offered — a pin sits at a fixed offset from the edge
/// it attaches to, so its x is not a meaningful alignment feature (the edge is);
/// its y lets pins on different blocks line up. Works for block pins and the port
/// pin.
fn push_pin_rows(shape: &ShapeRef, offset: Vec2, out: &mut Vec<Candidate>) {
    shape.with_pins(|pid, _pin| {
        if let Some(stub) = shape.pin_stub_rect(pid) {
            let c = stub.center() + offset;
            out.push(Candidate {
                axis: Axis::Horizontal,
                kind: Kind::PinStub,
                coord: c.y,
                lo: c.x,
                hi: c.x,
            });
        }
    });
}

/// The features a shape contributes. Blocks: edges, centers, and pin rows.
/// Ports: the pin row plus two verticals at the pentagon's tip and flat back.
/// Areas: edges and centers. Text boxes: only the top-left corner (their box
/// is normally hidden). Images/icons: only the center, so they align
/// center-to-center (an icon to its containing block's center). `offset` previews
/// a drag (zero for a resting shape).
fn shape_candidates(id: ShapeId, shape: &ShapeRef, offset: Vec2, out: &mut Vec<Candidate>) {
    match id {
        ShapeId::Rect(_) => {
            push_rect_candidates(shape.gui_rect().translate(offset), out);
            push_pin_rows(shape, offset, out);
        }
        ShapeId::Port(_) => {
            // A horizontal guide through the pin (to line up with other pins),
            // plus two verticals at the pentagon's tip and flat back — its bbox's
            // left/right edges. The pin's x is a fixed offset from the tip, so it
            // is not an alignment feature.
            push_pin_rows(shape, offset, out);
            let r = shape.gui_rect().translate(offset);
            for x in [r.left(), r.right()] {
                out.push(Candidate {
                    axis: Axis::Vertical,
                    kind: Kind::Edge,
                    coord: x,
                    lo: r.top(),
                    hi: r.bottom(),
                });
            }
        }
        ShapeId::Area(_) => push_rect_candidates(shape.gui_rect().translate(offset), out),
        ShapeId::Text(_) => {
            push_point_candidates(
                shape.gui_rect().translate(offset).left_top(),
                Kind::Edge,
                out,
            );
        }
        ShapeId::Image(_) | ShapeId::Icon(_) => {
            push_point_candidates(
                shape.gui_rect().translate(offset).center(),
                Kind::Center,
                out,
            );
        }
    }
}

fn match_guides(moving: &[Candidate], statics: &[Candidate]) -> Vec<[Pos2; 2]> {
    // (axis, coord, lo, hi) — guides sharing an axis and coordinate merge so a
    // column of aligned shapes yields a single line spanning all of them.
    let mut merged: Vec<(Axis, f32, f32, f32)> = Vec::new();
    for m in moving {
        for s in statics {
            if m.axis != s.axis || m.kind != s.kind || (m.coord - s.coord).abs() >= EPS {
                continue;
            }
            let (lo, hi) = (m.lo.min(s.lo), m.hi.max(s.hi));
            match merged
                .iter_mut()
                .find(|(a, c, _, _)| *a == m.axis && (*c - m.coord).abs() < EPS)
            {
                Some(e) => {
                    e.2 = e.2.min(lo);
                    e.3 = e.3.max(hi);
                }
                None => merged.push((m.axis, m.coord, lo, hi)),
            }
        }
    }
    merged
        .into_iter()
        .map(|(axis, coord, lo, hi)| match axis {
            Axis::Vertical => [pos2(coord, lo), pos2(coord, hi)],
            Axis::Horizontal => [pos2(lo, coord), pos2(hi, coord)],
        })
        .collect()
}

/// Draw the computed guide segments. Call this *after* the scene so a center
/// guide — which runs through the opaque shapes it aligns — stays visible.
pub fn draw_guides(guides: &[[Pos2; 2]], painter: &mut Style<'_, impl Renderer>) {
    for &seg in guides {
        painter.line_segment(seg, (1.0, Role::AlignmentGuide));
    }
}

/// The resting alignment features of every shape (plus areas) except those
/// `is_excluded` — the static set a drag or resize matches its moving features
/// against.
fn build_statics(data: &Drawing, is_excluded: impl Fn(ShapeId) -> bool) -> Vec<Candidate> {
    let mut statics = Vec::new();
    for (id, shape) in data.shapes().chain(data.areas()) {
        if !is_excluded(id) {
            shape_candidates(id, &shape, Vec2::ZERO, &mut statics);
        }
    }
    statics
}

/// Guides for a shape (or group) drag: the dragged shapes — previewed at
/// `offset` — contribute their features; every other shape (including areas)
/// contributes the same at its resting position.
pub fn shape_drag_guides(data: &Drawing, dragged: &[ShapeId], offset: Vec2) -> Vec<[Pos2; 2]> {
    let mut moving = Vec::new();
    for &id in dragged {
        if let Some(shape) = data.shape(id) {
            shape_candidates(id, &shape, offset, &mut moving);
        }
    }
    let statics = build_statics(data, |id| dragged.contains(&id));
    match_guides(&moving, &statics)
}

/// Alignment guides for a resize: the shape's features at its previewed `resized`
/// rect, matched against every other shape's resting features. A resize doesn't
/// translate the shape, so it can't reuse [`shape_drag_guides`]'s `offset` path.
pub fn resize_guides(data: &Drawing, id: ShapeId, resized: Rect) -> Vec<[Pos2; 2]> {
    let mut moving = Vec::new();
    resized_candidates(id, resized, &mut moving);
    let statics = build_statics(data, |sid| sid == id);
    match_guides(&moving, &statics)
}

/// The features a shape at `rect` contributes while being resized: rect shapes
/// (blocks, areas) offer edges + centers; images/icons offer edges (the ones
/// the resize magnetism snaps — see [`snap_resize_corner`]); ports offer their
/// tip/back columns. Text boxes aren't resizable.
fn resized_candidates(id: ShapeId, rect: Rect, out: &mut Vec<Candidate>) {
    match id {
        ShapeId::Rect(_) | ShapeId::Area(_) => push_rect_candidates(rect, out),
        ShapeId::Image(_) | ShapeId::Icon(_) => push_rect_edges(rect, out),
        ShapeId::Port(_) => {
            for x in [rect.left(), rect.right()] {
                out.push(Candidate {
                    axis: Axis::Vertical,
                    kind: Kind::Edge,
                    coord: x,
                    lo: rect.top(),
                    hi: rect.bottom(),
                });
            }
        }
        ShapeId::Text(_) => {}
    }
}

/// Snap a resize's dragged `corner` to a nearby static *edge* — its x to the
/// nearest static vertical edge, its y to the nearest static horizontal edge,
/// each within [`SNAP_RADIUS`] and independently — so a free image/icon edge
/// lines up as a move would. `exclude` is the shape being resized (its own edges
/// aren't targets). Returns the corrected corner.
pub fn snap_resize_corner(data: &Drawing, exclude: ShapeId, corner: Pos2) -> Pos2 {
    let statics = build_statics(data, |sid| sid == exclude);
    let mut best_x: Option<f32> = None;
    let mut best_y: Option<f32> = None;
    for s in statics.iter().filter(|s| s.kind == Kind::Edge) {
        let (cur, best) = match s.axis {
            Axis::Vertical => (corner.x, &mut best_x),
            Axis::Horizontal => (corner.y, &mut best_y),
        };
        let d = s.coord - cur;
        if d.abs() <= SNAP_RADIUS && best.is_none_or(|b: f32| d.abs() < b.abs()) {
            *best = Some(d);
        }
    }
    pos2(
        corner.x + best_x.unwrap_or(0.0),
        corner.y + best_y.unwrap_or(0.0),
    )
}

/// Magnetic alignment for a freely-positioned image/icon drag: adjust `raw_offset`
/// so a dragged feature snaps exactly onto a nearby static feature of the same
/// kind/axis (within [`SNAP_RADIUS`]), per axis independently — so a drag can snap
/// horizontally, vertically, or both. Returns `raw_offset` unchanged where nothing
/// is near. The static set is every other shape (plus areas), matching
/// [`shape_drag_guides`], so a snap always coincides with a drawn guide.
pub fn snap_drag_offset(data: &Drawing, dragged: &[ShapeId], raw_offset: Vec2) -> Vec2 {
    let mut moving = Vec::new();
    for &id in dragged {
        if let Some(shape) = data.shape(id) {
            shape_candidates(id, &shape, raw_offset, &mut moving);
        }
    }
    let statics = build_statics(data, |id| dragged.contains(&id));
    // Smallest within-radius correction on each axis. A `Vertical` candidate's
    // `coord` is an x (corrects the offset's x); a `Horizontal` one is a y.
    let mut best_x: Option<f32> = None;
    let mut best_y: Option<f32> = None;
    for m in &moving {
        for s in &statics {
            if m.axis != s.axis || m.kind != s.kind {
                continue;
            }
            let d = s.coord - m.coord;
            if d.abs() > SNAP_RADIUS {
                continue;
            }
            let best = match m.axis {
                Axis::Vertical => &mut best_x,
                Axis::Horizontal => &mut best_y,
            };
            if best.is_none_or(|b: f32| d.abs() < b.abs()) {
                *best = Some(d);
            }
        }
    }
    raw_offset + vec2(best_x.unwrap_or(0.0), best_y.unwrap_or(0.0))
}

/// Guides for a pin drag: each previewed pin — the same [`PinMove`] the
/// commit will carry — matches against every other pin stub except
/// `exclude`.
pub fn pin_drag_guides(data: &Drawing, moving: &[PinMove], exclude: &[PinId]) -> Vec<[Pos2; 2]> {
    let mut moving_c = Vec::new();
    for &PinMove { pin: pid, to } in moving {
        let Some(shape) = data.pin_shape(pid).and_then(|id| data.shape(id)) else {
            continue;
        };
        let (Some(stub), Some(pin)) = (shape.pin_stub_rect(pid), shape.pin(pid)) else {
            continue;
        };
        let rect = shape.gui_rect();
        let half = stub.width() / 2.0;
        let x = match to.side {
            PinSide::East => rect.right() + half,
            PinSide::West => rect.left() - half,
        };
        let y = stub.center().y + (to.offset as f32 - slot(pin).offset as f32) * PIN_PITCH;
        // A pin aligns by its row (y) only — its x is fixed to the block edge.
        moving_c.push(Candidate {
            axis: Axis::Horizontal,
            kind: Kind::PinStub,
            coord: y,
            lo: x,
            hi: x,
        });
    }
    let mut statics = Vec::new();
    for (_, shape) in data.shapes() {
        shape.with_pins(|pid, _pin| {
            if !exclude.contains(&pid)
                && let Some(stub) = shape.pin_stub_rect(pid)
            {
                let c = stub.center();
                statics.push(Candidate {
                    axis: Axis::Horizontal,
                    kind: Kind::PinStub,
                    coord: c.y,
                    lo: c.x,
                    hi: c.x,
                });
            }
        });
    }
    match_guides(&moving_c, &statics)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::widget::test_fixtures::{self as fx, Scene};
    use blockworx_doc::{
        fixtures::{block_id, image_id, pin_id},
        geometry::PinSlot,
        id::BlockId,
    };

    fn rect_at(x: f32, y: f32, w: f32, h: f32) -> Rect {
        Rect::from_min_max(pos2(x, y), pos2(x + w, y + h))
    }

    fn block_at(n: u32, x: f32, y: f32, w: f32, h: f32) -> blockworx_doc::opcode::OpCodes {
        fx::block_in(n, Scope::Root, rect_at(x, y, w, h))
    }

    // Vertical guides hold x constant; horizontal guides hold y constant.
    fn vlines(guides: &[[Pos2; 2]]) -> Vec<f32> {
        guides
            .iter()
            .filter(|g| (g[0].x - g[1].x).abs() < 0.5)
            .map(|g| g[0].x)
            .collect()
    }
    fn hlines(guides: &[[Pos2; 2]]) -> Vec<f32> {
        guides
            .iter()
            .filter(|g| (g[0].y - g[1].y).abs() < 0.5)
            .map(|g| g[0].y)
            .collect()
    }
    fn has(coords: &[f32], c: f32) -> bool {
        coords.iter().any(|&x| (x - c).abs() < 0.5)
    }
    fn stub_center(d: &Drawing, block: BlockId, pin: PinId) -> Pos2 {
        d.shape(ShapeId::Rect(block))
            .unwrap()
            .pin_stub_rect(pin)
            .unwrap()
            .center()
    }

    fn rect_of(d: &Drawing, id: ShapeId) -> Rect {
        d.shape(id).unwrap().gui_rect()
    }

    // Dragging a block so an edge meets another block's edge yields a guide at
    // that coordinate; a non-coincident offset yields none. (Coordinates come
    // from the snapped `gui_rect`s, so grid snapping doesn't matter.)
    #[test]
    fn shape_drag_guides_flags_edge_alignment() {
        // Different y so only vertical (edge-x) alignment is possible.
        let mut scene = Scene::new(vec![
            block_at(1, 0.0, 0.0, 45.0, 45.0),
            block_at(2, 90.0, 150.0, 45.0, 45.0),
        ]);
        let drawing = scene.drawing();
        let (a, b) = (ShapeId::Rect(block_id(1)), ShapeId::Rect(block_id(2)));
        let (ar, br) = (rect_of(&drawing, a), rect_of(&drawing, b));

        // Land A's right edge exactly on B's left edge.
        let guides = shape_drag_guides(&drawing, &[a], vec2(br.left() - ar.right(), 0.0));
        assert!(has(&vlines(&guides), br.left()));
        // No coincidence at a small, non-aligning offset.
        let none = shape_drag_guides(&drawing, &[a], vec2(7.0, 0.0));
        assert!(none.is_empty());
    }

    // Center-to-center alignment yields a guide even when no edges coincide
    // (the blocks have different widths, so their edges can't also line up).
    #[test]
    fn shape_drag_guides_flags_center_alignment() {
        let mut scene = Scene::new(vec![
            block_at(1, 0.0, 0.0, 30.0, 45.0),
            block_at(2, 75.0, 150.0, 75.0, 45.0),
        ]);
        let drawing = scene.drawing();
        let (a, b) = (ShapeId::Rect(block_id(1)), ShapeId::Rect(block_id(2)));
        let (ar, br) = (rect_of(&drawing, a), rect_of(&drawing, b));
        assert!(
            (ar.width() - br.width()).abs() > 0.5,
            "the blocks must differ in width, or edges could align too"
        );

        let guides = shape_drag_guides(&drawing, &[a], vec2(br.center().x - ar.center().x, 0.0));
        assert!(has(&vlines(&guides), br.center().x));
    }

    // Two pin stubs sharing a row produce a horizontal guide on that row.
    #[test]
    fn shape_drag_guides_flags_pin_stub_alignment() {
        let mut scene = Scene::new(vec![
            block_at(1, 0.0, 0.0, 40.0, 150.0),
            fx::pin(3, 1, PinSide::East, 1),
            block_at(2, 300.0, 0.0, 40.0, 150.0),
            fx::pin(4, 2, PinSide::East, 1),
        ]);
        let drawing = scene.drawing();

        let row = stub_center(&drawing, block_id(2), pin_id(4)).y;
        // Pure horizontal drag keeps A's pin on the same row as B's.
        let guides = shape_drag_guides(&drawing, &[ShapeId::Rect(block_id(1))], vec2(100.0, 0.0));
        assert!(has(&hlines(&guides), row));
    }

    // A text box contributes only its top-left corner: its left edge aligns, but
    // its (hidden) right edge does not.
    #[test]
    fn shape_drag_guides_text_box_uses_only_its_corner() {
        let mut scene = Scene::new(vec![
            block_at(1, 0.0, 300.0, 40.0, 40.0),
            fx::text(5, Scope::Root, "some text", pos2(100.0, 100.0)),
        ]);
        let drawing = scene.drawing();
        let a = ShapeId::Rect(block_id(1));
        let tb = rect_of(&drawing, ShapeId::Text(blockworx_doc::fixtures::text_id(5)));
        let ar = rect_of(&drawing, a);

        // Drag A so its left edge meets the text box's top-left x → a guide.
        let g1 = shape_drag_guides(&drawing, &[a], vec2(tb.left() - ar.left(), 0.0));
        assert!(has(&vlines(&g1), tb.left()));
        // Drag A so its left edge meets the text box's RIGHT edge → no guide
        // there (the right edge is not an alignment feature).
        let g2 = shape_drag_guides(&drawing, &[a], vec2(tb.right() - ar.left(), 0.0));
        assert!(!has(&vlines(&g2), tb.right()));
    }

    // An image dragged so its center lands on a block's center yields both a
    // vertical and horizontal center guide (image features are center-only).
    #[test]
    fn shape_drag_guides_flags_image_center_alignment() {
        let mut scene = Scene::new(vec![
            fx::asset().1,
            block_at(1, 100.0, 100.0, 40.0, 40.0),
            fx::image(5, Scope::Root, rect_at(0.0, 0.0, 25.0, 25.0)),
        ]);
        let drawing = scene.drawing();
        let img = ShapeId::Image(image_id(5));
        let ic = rect_of(&drawing, img).center();
        let bc = rect_of(&drawing, ShapeId::Rect(block_id(1))).center();

        let guides = shape_drag_guides(&drawing, &[img], bc - ic);
        assert!(has(&vlines(&guides), bc.x));
        assert!(has(&hlines(&guides), bc.y));
    }

    // A block's icon aligns to the block's own center (the block is a static).
    #[test]
    fn shape_drag_guides_flags_icon_to_block_center() {
        // The icon box is centered on the block, so a zero drag aligns it.
        let mut scene = Scene::new(vec![
            fx::asset().1,
            block_at(1, 0.0, 0.0, 60.0, 60.0),
            fx::icon(1, rect_at(15.0, 15.0, 30.0, 30.0)),
        ]);
        let drawing = scene.drawing();
        let bc = rect_of(&drawing, ShapeId::Rect(block_id(1))).center();
        let icon = ShapeId::Icon(block_id(1));
        assert!(
            (rect_of(&drawing, icon).center() - bc).length() < 0.5,
            "the icon must start centered, or a zero drag proves nothing"
        );

        let guides = shape_drag_guides(&drawing, &[icon], Vec2::ZERO);
        assert!(has(&vlines(&guides), bc.x));
        assert!(has(&hlines(&guides), bc.y));
    }

    // Magnetism pulls a near miss (within SNAP_RADIUS) exactly onto a center, and
    // leaves a far drag untouched.
    #[test]
    fn snap_drag_offset_pulls_a_near_center_and_ignores_a_far_one() {
        let mut scene = Scene::new(vec![
            fx::asset().1,
            block_at(1, 100.0, 100.0, 40.0, 40.0),
            fx::image(5, Scope::Root, rect_at(0.0, 0.0, 20.0, 20.0)),
        ]);
        let drawing = scene.drawing();
        let img = ShapeId::Image(image_id(5));
        let ic = rect_of(&drawing, img).center();
        let bc = rect_of(&drawing, ShapeId::Rect(block_id(1))).center();

        // Land the image center 3px short of the block center (< SNAP_RADIUS).
        let near = (bc - ic) - vec2(3.0, 3.0);
        let snapped = snap_drag_offset(&drawing, &[img], near);
        assert!(
            ((ic + snapped) - bc).length() < 1e-3,
            "snapped onto the center"
        );

        let far = vec2(1000.0, 1000.0);
        assert_eq!(
            snap_drag_offset(&drawing, &[img], far),
            far,
            "far drag unchanged"
        );
    }

    // A previewed pin moved onto another pin's row produces a guide; the dragged
    // pin's own resting stub is excluded from the static set.
    #[test]
    fn pin_drag_guides_flags_a_shared_row() {
        let mut scene = Scene::new(vec![
            block_at(1, 0.0, 0.0, 40.0, 150.0),
            fx::pin(3, 1, PinSide::East, 0),
            block_at(2, 300.0, 0.0, 40.0, 150.0),
            fx::pin(4, 2, PinSide::East, 2),
        ]);
        let drawing = scene.drawing();

        let row = stub_center(&drawing, block_id(2), pin_id(4)).y;
        // Move A's pin to slot 2 → same row as B's pin.
        let moved = PinMove {
            pin: pin_id(3),
            to: PinSlot {
                side: PinSide::East,
                offset: 2,
            },
        };
        let guides = pin_drag_guides(&drawing, &[moved], &[pin_id(3)]);
        assert!(has(&hlines(&guides), row));
    }

    // A block pin offers only a horizontal (row) guide: its x is fixed to the
    // block edge, so a vertical guide through it would be noise.
    #[test]
    fn a_block_pin_offers_only_a_row_guide() {
        let mut scene = Scene::new(vec![
            block_at(1, 0.0, 0.0, 40.0, 150.0),
            fx::pin(3, 1, PinSide::East, 1),
        ]);
        let drawing = scene.drawing();
        let id = ShapeId::Rect(block_id(1));
        let shape = drawing.shape(id).unwrap();

        let mut out = Vec::new();
        shape_candidates(id, &shape, Vec2::ZERO, &mut out);
        let pins: Vec<&Candidate> = out.iter().filter(|c| c.kind == Kind::PinStub).collect();
        assert!(!pins.is_empty(), "the pin contributes a row guide");
        assert!(
            pins.iter().all(|c| c.axis == Axis::Horizontal),
            "a pin never offers a vertical (column) guide"
        );
    }

    // A port offers a horizontal guide through its pin plus two verticals at the
    // pentagon's tip and flat back (its bbox's left/right edges) — but no vertical
    // through the pin itself.
    #[test]
    fn a_port_offers_a_pin_row_and_tip_and_back_columns() {
        let pid = pin_id(3);
        let mut scene = Scene::new(vec![fx::pin_at(
            3,
            Scope::Root,
            "x",
            fx::slot(PinSide::East, 0),
            rect_at(10.0, 20.0, 40.0, 30.0),
        )]);
        let drawing = scene.drawing();
        let id = ShapeId::Port(pid);
        let shape = drawing.shape(id).unwrap();
        let r = shape.gui_rect();

        let mut out = Vec::new();
        shape_candidates(id, &shape, Vec2::ZERO, &mut out);
        assert!(
            out.iter()
                .any(|c| c.kind == Kind::PinStub && c.axis == Axis::Horizontal),
            "a horizontal guide through the pin"
        );
        assert!(
            out.iter()
                .filter(|c| c.kind == Kind::PinStub)
                .all(|c| c.axis == Axis::Horizontal),
            "no vertical guide through the pin"
        );
        let vlines: Vec<f32> = out
            .iter()
            .filter(|c| c.axis == Axis::Vertical)
            .map(|c| c.coord)
            .collect();
        assert!(has(&vlines, r.left()), "a vertical at one pentagon end");
        assert!(has(&vlines, r.right()), "a vertical at the other end");
    }

    // Resizing a block so an edge lands on another block's edge yields a guide at
    // that coordinate; a non-coincident resize yields none.
    #[test]
    fn resize_guides_flag_an_edge_meeting_another() {
        let mut scene = Scene::new(vec![
            block_at(1, 0.0, 0.0, 45.0, 45.0),
            block_at(2, 90.0, 150.0, 45.0, 45.0),
        ]);
        let drawing = scene.drawing();
        let a = ShapeId::Rect(block_id(1));
        let br = rect_of(&drawing, ShapeId::Rect(block_id(2)));

        // Grow A's right edge out to B's left edge → a vertical guide there.
        let onto = Rect::from_min_max(pos2(0.0, 0.0), pos2(br.left(), 45.0));
        let guides = resize_guides(&drawing, a, onto);
        assert!(has(&vlines(&guides), br.left()));

        // A resize that lines nothing up yields no guide.
        let off = Rect::from_min_max(pos2(0.0, 0.0), pos2(52.0, 45.0));
        assert!(resize_guides(&drawing, a, off).is_empty());
    }

    // A resize's dragged corner snaps its edge onto a nearby static edge, per
    // axis: a near x snaps, a far y is left alone; a far corner is unchanged.
    #[test]
    fn snap_resize_corner_snaps_a_dragged_edge_to_a_static_edge() {
        let mut scene = Scene::new(vec![
            fx::asset().1,
            block_at(1, 0.0, 0.0, 45.0, 45.0),
            fx::image(5, Scope::Root, rect_at(100.0, 100.0, 60.0, 40.0)),
        ]);
        let drawing = scene.drawing();
        let img = ShapeId::Image(image_id(5));
        let ar = rect_of(&drawing, ShapeId::Rect(block_id(1)));

        // A corner 3px shy of block a's right edge (< SNAP_RADIUS) snaps its x
        // onto it; its y has no nearby edge and is left free.
        let corner = pos2(ar.right() - 3.0, 500.0);
        let snapped = snap_resize_corner(&drawing, img, corner);
        assert!((snapped.x - ar.right()).abs() < 1e-3, "x snaps to the edge");
        assert_eq!(snapped.y, 500.0, "y has no nearby edge");

        let far = pos2(1000.0, 1000.0);
        assert_eq!(
            snap_resize_corner(&drawing, img, far),
            far,
            "far corner unchanged"
        );
    }
}