blockworx_editor/widget/

routing.rs

//! Route (re)solving for a level: the closed-graph solver every commit and
//! every drag/resize preview goes through, the per-leg reconstruction that
//! rebuilds a route's geometry from its stored corners, and the rip-up/reroute
//! entry points.
//!
//! Split out of [`Drawing`]'s core so the routing policy — when a route is left
//! alone, straightened, or re-solved — reads as one thing.

use std::collections::{BTreeMap, HashMap, HashSet};

use blockworx_doc::{
    commit::CommitBuilder,
    document::IndexedDocument,
    geometry::{GridPoint, GridVec, Waypoint},
    id::{PinId, RouteId, RouteLabelId},
    opcode::OpCodes,
    values::PinSide,
};
use blockworx_geom::{Pos2, Rect, Vec2, vec2};
use blockworx_router::{
    Bounds, ClosedRouter, Resolution, RouterNGBuilder, WIRE_COST, cost::COST_ZERO, point::Point,
    turtle::Mark,
};

use crate::{
    edit::{
        create::PathOrdinal,
        geometry::{PinMove, RouteEnd, backtracking_ordinals, pruned_waypoints, trimmed_ordinals},
        naming::InterfaceLock,
    },
    grid::{GRID_SIZE, grid_point, px_point, snap_to_grid},
    path::BlockPath,
    presentation::{Presentation, RouteGeometry},
    shape::{ShapeId, ShapeRef},
    widget::{
        auto_route::{
            label_anchors, reanchored, reroute_preview_closed, reroute_preview_excluding,
        },
        drawing::Drawing,
        foreground::Foreground,
        movement::moved_set_and_delta,
        reconstruct::{
            Endpoints, Obstacles, promote_corners_to_waypoints, reconstruct_corners_direct,
            reconstruct_route, straighten_route,
        },
        waypoint_router::add_route_cost,
    },
};
/// What one solve pass promoted: for each wire it touched, the corner list
/// its geometry now implies. The gesture's funnel diffs these against the
/// staged document and pushes the ones that moved — the solver itself never
/// writes.
pub type Promoted = Vec<(RouteId, Vec<Waypoint>)>;

/// What the gesture wrote, as the rider has to read it: the ops staged so far,
/// and the footprints their shapes have *left* — which the staged document no
/// longer holds, so nothing downstream can derive them.
#[derive(Clone, Copy)]
pub struct Edited<'a> {
    pub ops: &'a [OpCodes],
    pub vacated: &'a [Rect],
}

/// How much of the scope one ride re-solves.
#[derive(Clone, Copy)]
enum Riding<'a> {
    /// Every wire. The settling pass, which is not a gesture and has no
    /// foreground to derive — it is solving the document for the first time.
    WholeScope,
    /// Only what the gesture wrote and what that disturbed.
    Edited(Edited<'a>),
}

/// Fold what the gesture has written so far onto a scratch prediction,
/// re-solve against that document, and author every corner list the solve
/// promotes. Trims, re-solves and promotions therefore land in the same commit
/// as the gesture that caused them, and the "every corner is a waypoint"
/// invariant survives without the solver ever writing.
fn ride(
    indexed: &IndexedDocument<'_>,
    path: &BlockPath,
    presentation: &Presentation,
    riding: Riding<'_>,
    sink: &mut CommitBuilder,
) -> Option<Rect> {
    let _s = tracing::info_span!("ride").entered();
    let mut scratch = {
        let _s = tracing::info_span!("rider_scratch").entered();
        presentation.scratch(indexed)
    };
    let mut discarded = crate::gesture::Gesture::idle();
    let (promoted, disturbed) = {
        let mut drawing = Drawing::new(*indexed, path, &mut scratch, &mut discarded);
        match riding {
            Riding::WholeScope => (drawing.solve_routes(&[]), None),
            Riding::Edited(edited) => {
                let mut foreground = Foreground::written(edited.ops, &drawing);
                for &vacated in edited.vacated {
                    foreground.also_disturbed_by(vacated, &drawing);
                }
                // Measured before the solve moves anything: the wires it is
                // about to rewrite are where they are *now*, and the
                // reconstruction after the commit has to reach both.
                let was = foreground.extent(&drawing);
                let promoted = drawing.solve_foreground(&foreground, &[]);
                let now = foreground.extent(&drawing);
                (promoted, Some(was.union(now)))
            }
        }
    };
    debug_assert!(
        discarded.ops().is_empty(),
        "the solve is a read; it must author nothing of its own"
    );
    for (route, waypoints) in promoted {
        crate::edit::geometry::commit_route_edit(
            indexed.doc,
            crate::edit::geometry::RouteEdit {
                route,
                waypoints,
                anchors: &[],
            },
            sink,
        );
    }
    disturbed
}

/// The solve rider: re-solve the wires the gesture *disturbed*, and author what
/// that promotes into the same commit.
///
/// Scoped to the foreground rather than the whole scope, because re-solving
/// every wire means every wire may move — a cost proportional to the sheet, and
/// geometry churn nobody asked for: one block moving one cell used to rewrite
/// two thirds of a small sheet's corners.
///
/// A gesture that has written nothing has nothing to solve against.
/// Returns the rectangle the gesture disturbed, for the reconstruction that
/// follows the commit.
pub(crate) fn solve_rider(
    indexed: &IndexedDocument<'_>,
    path: &BlockPath,
    presentation: &Presentation,
    edited: Edited<'_>,
    sink: &mut CommitBuilder,
) -> Option<Rect> {
    ride(indexed, path, presentation, Riding::Edited(edited), sink)
}

/// Solve every wire in the scope, for the settling pass that gives a generated
/// document its corners. Not a gesture: there is nothing to scope to, and the
/// point is precisely to touch everything.
pub(crate) fn settle_scope(
    indexed: &IndexedDocument<'_>,
    path: &BlockPath,
    presentation: &Presentation,
    sink: &mut CommitBuilder,
) {
    ride(indexed, path, presentation, Riding::WholeScope, sink);
}

/// A shape's world rect as the router reads it. The one conversion, so a
/// preview's obstacle set and anything else that builds one cannot disagree
/// about where a block's edges are.
pub fn obstacle_rect(rect: Rect) -> blockworx_router::block::Block {
    blockworx_router::block::Block {
        top_left: rect.left_top().into(),
        bottom_right: rect.right_bottom().into(),
    }
}

/// What a lattice is built from: the hypothetical geometry it holds shapes
/// at, and every route's endpoints and waypoints, which it must hold a node for.
struct Seeding<'a> {
    hypo: GeometryOverrides<'a>,
    ids: &'a [RouteId],
    endpoints: &'a [(RouteId, Pos2, Pos2)],
    exclusions: &'a HashMap<RouteId, PreviewExclusions>,
    offsets: &'a HashMap<RouteId, GridVec>,
}

/// A wire a preview frame reroutes: its ends, the waypoints it routes
/// through, and — for one riding entirely inside a group drag — the offset
/// those waypoints ride at.
struct Rerouting {
    ends: Endpoints,
    stored: Vec<Waypoint>,
    rigid: Option<GridVec>,
}

/// Seed points for a lattice covering `within`, and no others.
///
/// Gathered per lattice rather than once per pass: a commit that straightens
/// every leg builds no lattice at all, and gathering 30,000 points for one that
/// is never built was ~8 ms of every commit. Points outside the bounds are
/// dropped here because the lattice would drop them anyway.
fn seeds_within(drawing: &Drawing<'_>, seeding: &Seeding<'_>, within: Region) -> Vec<Point> {
    let mut seed_points: Vec<Point> = Vec::with_capacity(seeding.endpoints.len() * 2);
    let bounds = within.bounds();
    let mut take = |p: Point| {
        if bounds.holds(p) {
            seed_points.push(p);
        }
    };
    for &(_, s, e) in seeding.endpoints {
        take(snap_to_grid(s).into());
        take(snap_to_grid(e).into());
    }
    for &id in seeding.ids {
        for pos in seeded_waypoints(drawing, seeding, id) {
            take(pos.into());
        }
    }
    seed_points
}

/// Where a lattice holds `id`'s waypoints this pass: offset with a group drag
/// it rides entirely inside, and without the ones a preview trims or prunes.
fn seeded_waypoints<'a>(
    drawing: &'a Drawing<'_>,
    seeding: &'a Seeding<'_>,
    id: RouteId,
) -> impl Iterator<Item = GridPoint> + 'a {
    let excluded = seeding.exclusions.get(&id);
    let delta = seeding.offsets.get(&id).copied();
    drawing
        .route(id)
        .into_iter()
        .flat_map(|route| route.waypoints.iter().enumerate())
        .filter(move |(index, _)| {
            !excluded.is_some_and(|x| x.excluded.contains(&PathOrdinal::new(*index)))
        })
        .map(move |(_, wp)| delta.map_or(wp.pos, |delta| wp.pos + delta))
}

/// Does a wire's geometry still run between these anchors without crossing a
/// block? One that does needs no routing, whatever else moved.
fn still_holds(geometry: &RouteGeometry, start: Pos2, end: Pos2, obstacles: &Obstacles) -> bool {
    geometry.start_pos() == start
        && geometry.end_pos() == end
        && !geometry
            .iter_edges()
            .any(|(_, e)| obstacles.blocked(e.start, e.end))
}

/// The rectangle to heal: what the wires needing a lattice span, with room
/// around them to get past whatever is refusing them.
///
/// The margin is the moat twice over — once because a block shapes the channels
/// that far out, and once more so a detour has somewhere to go. A region too
/// small does not route wrongly, it fails to route, and the leg falls back to
/// an L; that is why the margin is generous and why the unresolved list is what
/// makes this honest.
fn healing_region(reach: impl IntoIterator<Item = GridPoint>) -> Rect {
    let margin = 2.0 * blockworx_router::block::MOAT_REACH as f32 * GRID_SIZE;
    let mut region: Option<Rect> = None;
    for p in reach {
        let at = px_point(p);
        let here = Rect::from_min_max(at, at);
        region = Some(region.map_or(here, |so_far| so_far.union(here)));
    }
    region.unwrap_or(Rect::ZERO).expand(margin)
}

/// Which of a scope's wires a reconstruction re-derives. The rest keep the
/// geometry they have, which is still what the document implies — nothing
/// moved near them.
#[derive(Clone, Copy)]
pub(crate) enum Reconstructing<'a> {
    /// An open, an undo, a commit from elsewhere: nothing is known about what
    /// changed, so everything is re-derived.
    Everything,
    /// What a commit disturbed, and the wires a preview left drawn where the
    /// document does not put them — taken back in the same pass rather than
    /// re-derived once by the take-back and again by the commit.
    Within {
        disturbed: Rect,
        previewed: &'a std::collections::HashSet<RouteId>,
    },
    /// Exactly these — what a preview rewrote and the next borrow takes back.
    These(&'a std::collections::HashSet<RouteId>),
}

/// How much of the routing plane a lattice covers. A local edit has local
/// effects, so there is no reason a router built to move one block has to hold
/// the whole diagram.
#[derive(Clone, Copy, Debug)]
pub(crate) enum Region {
    WholeScope,
    Within(Rect),
}

impl Region {
    /// The lattice bounds this region names. The router owns what bounds mean —
    /// a block straddling the edge is kept whole, a channel stops at the edge,
    /// a seed outside seeds nothing — so nothing here re-decides it.
    fn bounds(self) -> Bounds {
        match self {
            Region::WholeScope => Bounds::UNBOUNDED,
            Region::Within(region) => Bounds::between(region.min, region.max),
        }
    }
}

/// Which of a scope's wires a pass may re-solve. The rest are not skipped —
/// they contribute their occupancy — they are simply not re-decided.
#[derive(Clone, Copy)]
enum Solving<'a> {
    Everything,
    Only(&'a Foreground),
}

impl Solving<'_> {
    fn may_solve(self, id: RouteId) -> bool {
        match self {
            Solving::Everything => true,
            Solving::Only(foreground) => foreground.holds_route(id),
        }
    }
}

/// Whether a routing pass is the live preview or the committed result. A
/// preview never mutates the document — it solves against hypothetical
/// geometry into the derived store; only a commit rewrites waypoints.
enum RoutePass<'a> {
    Preview(PreviewSpec<'a>),
    Commit,
}

/// What a preview frame previews without committing. `inside` classifies each
/// route endpoint as riding the gesture: a route fully inside previews its
/// waypoints offset rigidly by `grid_delta`; a straddling route (exactly one
/// end riding) has its moved-side approach corners *computed as trimmed* — the
/// commit applies the real trim on drop.
struct PreviewSpec<'a> {
    grid_delta: GridVec,
    inside: &'a dyn Fn(PinId) -> bool,
}

/// What a route edit's commit pushes as ops: the corner list the relayed
/// geometry promotes, and each captured label anchor re-projected onto it.
type RelaidRoute = (
    Vec<Waypoint>,
    Vec<(RouteLabelId, blockworx_doc::geometry::FracVal)>,
);

/// A pin sitting at a hypothetical slot for one preview frame: routes anchored
/// to it solve as if the pin were already there, without moving it.
pub struct PinSlotOverride {
    pub pin: PinId,
    pub side: PinSide,
    pub offset: u32,
}

/// The hypothetical geometry one solve runs against: dragged/resized shapes at
/// previewed rects, dragged pins at previewed slots. Empty for a settled
/// document (a commit, or a preview whose overrides ride in elsewhere).
#[derive(Clone, Copy, Default)]
struct GeometryOverrides<'a> {
    rects: &'a [(ShapeId, Rect)],
    pins: &'a [PinSlotOverride],
}

/// The corners one preview frame previews deleted without deleting them: the
/// straddle trim plus any backtracking prune, computed against the frame's
/// hypothetical endpoints. `pruned` mirrors the commit pass's "a prune
/// happened, so the route must re-solve" trigger; a trim alone does not force
/// one (matching the mutating flow, where trims never did).
#[derive(Default)]
struct PreviewExclusions {
    excluded: HashSet<PathOrdinal>,
    pruned: bool,
}

/// One route edit's working-corner plan, built on the drag's first frame
/// ([`Drawing::route_edit_session`]) and applied only on release
/// ([`Drawing::commit_route_edit`]): where each dragged corner enters the
/// stored waypoint list, plus each label's world position at drag start —
/// re-imposed on every relayout so labels stay put while the wire moves under
/// them. Between build and commit the document is never written; the per-frame
/// preview relays the hypothetical corner list into derived state.
pub struct RouteEditSession {
    slots: Vec<WaypointSlot>,
    anchors: Vec<(RouteLabelId, Pos2)>,
}

/// Where one working corner lands in the stored waypoint list: a grabbed
/// existing corner (moved in place) or a fresh insertion.
enum WaypointSlot {
    /// Reuse the corner holding this ordinal in the *stored* list, so a grab
    /// survives insertions made by other slots of the same batch.
    Existing(PathOrdinal),
    /// Make a new corner at this index of the *working* list — which counts
    /// the corners earlier slots of the same batch already inserted. So the
    /// plan and its replay have to walk the slots in the same order, or a
    /// second insertion lands somewhere the first never made room for.
    InsertAt(usize),
}

/// The stored corners as a working list keyed by the ordinal each holds in
/// the document. Shared by the plan and its replay rather than written twice:
/// both count positions in this list, and a list built two ways is two
/// different meanings for the same `InsertAt`.
fn keyed_corners<T>(
    waypoints: &[Waypoint],
    value: impl Fn(&Waypoint) -> T,
) -> Vec<(Option<PathOrdinal>, T)> {
    waypoints
        .iter()
        .enumerate()
        .map(|(index, wp)| (Some(PathOrdinal::new(index)), value(wp)))
        .collect()
}

impl RouteEditSession {
    /// Each label's captured drag-start world anchor, for the overlay that
    /// draws labels pinned while the wire moves under them.
    pub fn anchors(&self) -> &[(RouteLabelId, Pos2)] {
        &self.anchors
    }

    /// The stored corner list with the working corners applied at `cursors` —
    /// the hypothetical the preview relays through and the commit writes.
    /// Working corners come out locked: the user placed them.
    pub fn corners(
        &self,
        waypoints: &[Waypoint],
        cursors: &[Pos2],
    ) -> Vec<(GridPoint, InterfaceLock)> {
        // Ordinals name positions in the *stored* list, so a grabbed corner is
        // resolved before any insertion shifts it.
        let mut corners = keyed_corners(waypoints, |wp| {
            let lock = if wp.locked {
                InterfaceLock::Locked
            } else {
                InterfaceLock::Unlocked
            };
            (wp.pos, lock)
        });
        for (slot, &cursor) in self.slots.iter().zip(cursors) {
            let pos = grid_point(cursor);
            match slot {
                WaypointSlot::Existing(ordinal) => {
                    if let Some(c) = corners.iter_mut().find(|(o, _)| *o == Some(*ordinal)) {
                        c.1 = (pos, InterfaceLock::Locked);
                    }
                }
                // Clamped because the stored list can have shrunk under the
                // plan since it was made, and an index past the end must
                // still place a corner rather than panic.
                WaypointSlot::InsertAt(i) => {
                    let i = (*i).min(corners.len());
                    corners.insert(i, (None, (pos, InterfaceLock::Locked)));
                }
            }
        }
        corners.into_iter().map(|(_, corner)| corner).collect()
    }
}

/// The previewed geometry for `shape` when it appears in `overrides` (a block or
/// port being dragged or resized), or `None` to use its stored geometry.
fn override_rect(shape: ShapeId, overrides: &[(ShapeId, Rect)]) -> Option<Rect> {
    overrides
        .iter()
        .find(|(overridden, _)| *overridden == shape)
        .map(|(_, rect)| *rect)
}

/// The previewed slot for `pin` when a drag previews one.
fn override_slot(pin: PinId, pins: &[PinSlotOverride]) -> Option<&PinSlotOverride> {
    pins.iter().find(|o| o.pin == pin)
}

impl Drawing<'_> {
    /// Solve this scope's wires against the settled document and report the
    /// corner lists the solve promotes. Read-only: the geometry lands in the
    /// presentation layer, and the promoted lists are the gesture funnel's to
    /// push as ops.
    pub fn solve_routes(&mut self, ripup: &[RouteId]) -> Promoted {
        self.route_update_closed(
            ripup,
            GeometryOverrides::default(),
            RoutePass::Commit,
            Solving::Everything,
        )
    }

    /// Re-solve only `foreground`'s wires. Every other wire in the scope keeps
    /// the geometry it has and contributes it as occupancy, so the foreground
    /// routes *around* the rest and lands last — which is what makes the result
    /// depend on the selection, deliberately
    /// (`docs/foreground-router-playbook.md`).
    pub fn solve_foreground(&mut self, foreground: &Foreground, ripup: &[RouteId]) -> Promoted {
        self.route_update_closed(
            ripup,
            GeometryOverrides::default(),
            RoutePass::Commit,
            Solving::Only(foreground),
        )
    }

    /// Suppose each `(shape, offset)` in `drags` displaced by its offset,
    /// without moving the shapes themselves in the model: the previewed rects
    /// the frame draws at, and — for the shapes that take part in routing — the
    /// wires re-solved to track them. With grid-snapped offsets the geometry
    /// matches what the real move on drop produces.
    pub fn preview_drag(
        &mut self,
        _phase: &crate::widget::PreviewPhase,
        drags: &[(ShapeId, Vec2)],
    ) {
        // A translation is just a rect override at the offset position.
        let overrides: Vec<(ShapeId, Rect)> = drags
            .iter()
            .filter_map(|&(shape, offset)| {
                Some((shape, self.shape(shape)?.gui_rect().translate(offset)))
            })
            .collect();
        self.preview_shapes(&overrides);
        // Annotations (areas, text, artwork) are not in the routing graph, so a
        // drag of nothing else has no wires to re-solve.
        if !drags.iter().any(|&(shape, _)| shape.affects_routing()) {
            return;
        }
        // A group drag shares one offset across all shapes; derive the moved-set
        // and grid-cell delta from that offset via the same helper the commit
        // (`move_shapes`) uses, so a route fully inside the selection previews
        // through waypoints offset by the SAME delta the commit will apply. The
        // same sets classify straddling routes, whose stale approach corners the
        // preview solve computes as trimmed — so the live preview shows the clean
        // re-route the commit's real trim will produce (no release flash).
        let ids: Vec<ShapeId> = drags.iter().map(|&(shape, _)| shape).collect();
        let delta = drags.first().map_or(Vec2::ZERO, |&(_, offset)| offset);
        let (moved_rects, moved_pins, grid_delta) = moved_set_and_delta(&ids, delta);
        let riding = self.riding_pins(&moved_rects, &moved_pins);
        let inside = |pin: PinId| riding.contains(&pin);
        let foreground = self.preview_foreground(ids, &overrides);
        let _ = self.route_update_closed(
            &[],
            GeometryOverrides {
                rects: &overrides,
                pins: &[],
            },
            RoutePass::Preview(PreviewSpec {
                grid_delta,
                inside: &inside,
            }),
            Solving::Only(&foreground),
        );
    }

    /// Suppose each `(shape, rect)` in `resizes` at that previewed geometry,
    /// without resizing the shapes in the model — the resize-aware counterpart
    /// of [`Self::preview_drag`].
    pub fn preview_resize(
        &mut self,
        _phase: &crate::widget::PreviewPhase,
        resizes: &[(ShapeId, Rect)],
    ) {
        self.preview_shapes(resizes);
        if !resizes.iter().any(|&(shape, _)| shape.affects_routing()) {
            return;
        }
        let foreground = self.preview_foreground(resizes.iter().map(|&(shape, _)| shape), resizes);
        let _ = self.route_update_closed(
            &[],
            GeometryOverrides {
                rects: resizes,
                pins: &[],
            },
            RoutePass::Preview(PreviewSpec {
                grid_delta: GridVec::new(0, 0),
                inside: &|_| false,
            }),
            Solving::Only(&foreground),
        );
    }

    /// Re-route the routes touching `pin` as if it sat at (`side`, `offset`),
    /// for the live drag preview. The hypothetical slot rides into the solve as
    /// an override — anchor point and zero-cost channel both — so the pin itself
    /// never moves; its routes' approach corners are computed as trimmed so the
    /// preview matches the clean re-route the drop produces.
    pub fn preview_pin_drag(
        &mut self,
        _phase: &crate::widget::PreviewPhase,
        pin: PinId,
        side: PinSide,
        offset: u32,
    ) {
        let slots = [PinSlotOverride { pin, side, offset }];
        let inside = move |other: PinId| other == pin;
        let foreground = self.preview_foreground(self.pin_shape(pin), &[]);
        let _ = self.route_update_closed(
            &[],
            GeometryOverrides {
                rects: &[],
                pins: &slots,
            },
            RoutePass::Preview(PreviewSpec {
                grid_delta: GridVec::new(0, 0),
                inside: &inside,
            }),
            Solving::Only(&foreground),
        );
    }

    /// Re-route as if every listed pin were already at its previewed
    /// `(side, slot)` — the group equivalent of
    /// [`preview_pin_drag`](Self::preview_pin_drag), minus the approach trim
    /// (the group flow never trimmed). Applies the whole move set as overrides
    /// so the routes re-solve in a single pass while a multi-pin drag previews
    /// them, without committing the relocation.
    pub fn preview_pin_drags(&mut self, _phase: &crate::widget::PreviewPhase, moves: &[PinMove]) {
        let slots: Vec<PinSlotOverride> = moves
            .iter()
            .map(|m| PinSlotOverride {
                pin: m.pin,
                side: m.to.side,
                offset: m.to.offset,
            })
            .collect();
        let foreground =
            self.preview_foreground(moves.iter().filter_map(|m| self.pin_shape(m.pin)), &[]);
        let _ = self.route_update_closed(
            &[],
            GeometryOverrides {
                rects: &[],
                pins: &slots,
            },
            RoutePass::Preview(PreviewSpec {
                grid_delta: GridVec::new(0, 0),
                inside: &|_| false,
            }),
            Solving::Only(&foreground),
        );
    }

    /// What a preview may re-solve: the wires the moving shapes carry or
    /// disturb, both where they are and where they are `heading_for`.
    fn preview_foreground(
        &self,
        shapes: impl IntoIterator<Item = ShapeId>,
        heading_for: &[(ShapeId, Rect)],
    ) -> Foreground {
        let mut foreground = Foreground::raising(shapes, self);
        for &(_, rect) in heading_for {
            foreground.also_disturbed_by(rect, self);
        }
        foreground
    }

    /// Where a route endpoint anchors, honoring a `hypo` entry for the shape
    /// (previewed rect) or the pin (previewed slot) it lands on. Which shape
    /// draws the pin is [`Drawing::pin_shape`]'s one answer, and the anchor
    /// math is the shape layer's own — the same the emitters read.
    fn anchor_pos_overridden(&self, pin: PinId, hypo: GeometryOverrides<'_>) -> Option<Pos2> {
        let sid = self.pin_shape(pin)?;
        let shape = self.shape(sid)?;
        let rect = override_rect(sid, hypo.rects).unwrap_or_else(|| shape.gui_rect());
        match (override_slot(pin, hypo.pins), &shape) {
            (Some(o), ShapeRef::Block(block)) => Some(block.pin_anchor_at(rect, o.side, o.offset)),
            _ => shape.anchor_point_with_rect(rect, pin),
        }
    }

    /// The scope's routing shapes — its child blocks and its own boundary
    /// ports, in draw order. Exactly what the router registers as obstacles
    /// and what the obstacle index tests, so a leg judged clear by one is
    /// judged clear by the other.
    #[tracing::instrument(level = "info", skip_all)]
    fn routing_shapes(&self) -> Vec<(ShapeId, ShapeRef<'_>)> {
        self.blocks_layer().chain(self.ports_layer()).collect()
    }

    /// Build the closed routing graph for this scope: seed each child/port
    /// obstacle rect and its pin channels (at previewed geometry for any shape
    /// or pin in `hypo`), plus a full channel at every point in `seed_points`
    /// (route endpoints and waypoints), then freeze the graph. The seed points
    /// are exactly the ones every route needs, so the closed graph contains a
    /// node for every route's endpoints and waypoints.
    fn build_closed_router(
        &self,
        hypo: GeometryOverrides<'_>,
        seed_points: &[Point],
    ) -> ClosedRouter {
        self.build_router_within(Region::WholeScope, hypo, seed_points)
    }

    /// The same build, confined to `within`. A region keeps every block that
    /// *intersects* it — a block straddling the edge blocks as much as it does
    /// anywhere — and every seed point inside it. What that leaves out is the
    /// rest of the diagram, which is the point: the lattice costs what the
    /// region holds rather than what the sheet holds.
    fn build_router_within(
        &self,
        within: Region,
        hypo: GeometryOverrides<'_>,
        seed_points: &[Point],
    ) -> ClosedRouter {
        let mut builder = RouterNGBuilder::default().within(within.bounds());
        for (sid, shape) in self.routing_shapes() {
            // A shape being dragged/resized uses its previewed rect, so obstacles
            // and pin channels are placed where it is heading — and a dragged
            // pin's channel likewise sits at its previewed slot.
            let rect = override_rect(sid, hypo.rects).unwrap_or_else(|| shape.gui_rect());
            builder.add_block(rect.left_top(), rect.right_bottom());
            shape.with_pins(|pid, _pin| {
                let slot = match &shape {
                    ShapeRef::Block(block) => override_slot(pid, hypo.pins)
                        .map(|o| block.pin_anchor_at(rect, o.side, o.offset)),
                    _ => None,
                };
                let Some(anchor) = slot.or_else(|| shape.anchor_point_with_rect(rect, pid)) else {
                    return;
                };
                let anchor_pos = if anchor.x >= rect.center().x {
                    anchor + vec2(GRID_SIZE, 0.0)
                } else {
                    anchor - vec2(GRID_SIZE, 0.0)
                };
                builder.add_h_channel(anchor_pos, COST_ZERO);
            });
        }
        for &p in seed_points {
            builder.add_seed_point(p);
        }
        builder.build_closed()
    }

    /// A lattice over `region`, with every wire not being `routed` laid in as
    /// occupancy before anything routes — so the wires that do route land
    /// last, around the rest.
    fn healing_lattice(
        &self,
        within: Region,
        seeding: &Seeding<'_>,
        routed: &HashSet<RouteId>,
    ) -> ClosedRouter {
        let seed_points = seeds_within(self, seeding, within);
        let mut lattice = {
            let _s = tracing::info_span!(
                "closed_build",
                seeds = seed_points.len(),
                region = ?within
            )
            .entered();
            self.build_router_within(within, seeding.hypo, &seed_points)
        };
        for &id in seeding.ids {
            if routed.contains(&id) {
                continue;
            }
            if let Some(geometry) = self.presentation.routes.get(&id) {
                add_route_cost(
                    &mut lattice,
                    geometry.iter_edges().map(|(_, edge)| edge),
                    WIRE_COST,
                );
            }
        }
        lattice
    }

    /// Route `wires` through a lattice over `region`, everything else laid in
    /// as occupancy first; then route the ones that fell back again, through a
    /// lattice over the whole scope. A region too small to detour in is routine
    /// and says nothing about the wire, so a wire is unresolved only when the
    /// sheet itself holds no path — what it would have been before regions.
    ///
    /// `route` lays one wire in the lattice it is given and says whether it
    /// found a path. One that finds none over the scope keeps its fallback L:
    /// that is what it settles on.
    fn heal<W>(
        &mut self,
        wires: Vec<(RouteId, W)>,
        region: Rect,
        seeding: &Seeding<'_>,
        mut route: impl FnMut(RouteId, &W, &mut RouteGeometry, &mut ClosedRouter) -> Resolution,
    ) {
        let mut attempt = |drawing: &mut Self, within: Region, wires: Vec<(RouteId, W)>| {
            let routed: HashSet<RouteId> = wires.iter().map(|(id, _)| *id).collect();
            let mut lattice = drawing.healing_lattice(within, seeding, &routed);
            let mut fell_back = Vec::new();
            for (id, wire) in wires {
                let geometry = drawing.presentation.routes.entry(id).or_default();
                if route(id, &wire, geometry, &mut lattice) == Resolution::Fallback {
                    fell_back.push((id, wire));
                }
            }
            fell_back
        };
        let fell_back = attempt(self, Region::Within(region), wires);
        if !fell_back.is_empty() {
            let _s = tracing::info_span!("heal_whole_scope", wires = fell_back.len()).entered();
            attempt(self, Region::WholeScope, fell_back);
        }
    }

    /// The obstacle rectangles of this scope, at previewed geometry for any
    /// shape in `overrides`. These are exactly the rects
    /// [`Self::build_closed_router`] registers as router blocks, wrapped for the
    /// cheap "does a straight leg cross a block?" test used by reconstruction,
    /// so a leg judged clear here is the same one the router would leave
    /// straight — without building the routing graph.
    fn obstacle_rects(&self, overrides: &[(ShapeId, Rect)]) -> Obstacles {
        let rects = self
            .routing_shapes()
            .into_iter()
            .map(|(sid, shape)| {
                obstacle_rect(override_rect(sid, overrides).unwrap_or_else(|| shape.gui_rect()))
            })
            .collect();
        Obstacles::new(rects)
    }

    /// The waypoints each route must route *around* this preview frame: the
    /// straddle trim (the moved side of a route with exactly one end riding the
    /// gesture) plus the backtracking prune, both computed against the frame's
    /// hypothetical endpoints — previewed, never applied. A route fully inside the
    /// gesture keeps its skeleton byte-identical: it previews through rigidly
    /// offset waypoints and, moving rigidly, can't introduce a reversal. Both
    /// rules are the emitters' own ([`crate::edit::geometry`]), read from the
    /// preview's side.
    fn preview_exclusions(
        &self,
        endpoints: &[(RouteId, Pos2, Pos2)],
        spec: &PreviewSpec<'_>,
    ) -> HashMap<RouteId, PreviewExclusions> {
        endpoints
            .iter()
            .filter_map(|&(id, s, e)| {
                let route = self.route(id)?;
                let stored = route.waypoints.clone();
                let (start_in, finish_in) = ((spec.inside)(route.from), (spec.inside)(route.to));
                if start_in && finish_in {
                    return None;
                }
                let mut excluded: HashSet<PathOrdinal> = match (start_in, finish_in) {
                    (true, false) => trimmed_ordinals(&stored, RouteEnd::From),
                    (false, true) => trimmed_ordinals(&stored, RouteEnd::To),
                    _ => Vec::new(),
                }
                .into_iter()
                .collect();
                let working: Vec<Waypoint> = stored
                    .iter()
                    .enumerate()
                    .filter(|(index, _)| !excluded.contains(&PathOrdinal::new(*index)))
                    .map(|(_, wp)| *wp)
                    .collect();
                // The prune's ordinals index `working`; map them back through the
                // surviving positions so both sets name the stored list.
                let survivors: Vec<PathOrdinal> = (0..stored.len())
                    .map(PathOrdinal::new)
                    .filter(|o| !excluded.contains(o))
                    .collect();
                let doomed = backtracking_ordinals(&working, grid_point(s), grid_point(e));
                let pruned = !doomed.is_empty();
                excluded.extend(
                    doomed
                        .into_iter()
                        .filter_map(|o| survivors.get(usize::from(o)).copied()),
                );
                (!excluded.is_empty()).then_some((id, PreviewExclusions { excluded, pruned }))
            })
            .collect()
    }

    /// Closed-graph route solver used by every path except live `RouteTool`
    /// drawing: load, interactive commits, AND the drag/resize preview. It builds
    /// the routing graph ONCE with all obstacle, endpoint, and waypoint geometry
    /// (honoring `overrides` for previewed shapes and offsetting waypoints of
    /// fully-dragged routes) seeded up front, then routes every route against it,
    /// applying `WIRE_COST` occupancy by mutating existing edge weights in place —
    /// so the graph is never rebuilt per route (the O(routes²) cost the old
    /// per-route rebuild paid; see TUNING.md Finding 1).
    ///
    /// `pass` distinguishes a permanent edit (a drop, delete, paste, nudge —
    /// the geometry is final) from a transient drag/resize preview (recomputed
    /// every frame from stable state). On commit a changed route is
    /// re-reconstructed per leg — its straight legs are kept and only the legs that
    /// are now blocked or non-colinear are routed — and its corners are promoted
    /// to waypoints; the backtracking prune really removes reversal corners. A
    /// preview never touches the document: it routes through the stable waypoint
    /// skeleton minus its *previewed* trims and prunes (so per-frame recomputation
    /// never piles up derived corners), taking only immutable borrows.
    #[tracing::instrument(level = "info", skip_all, fields(routes = self.scope_route_ids().len(), ripup = ripup.len()))]
    fn route_update_closed(
        &mut self,
        ripup: &[RouteId],
        hypo: GeometryOverrides<'_>,
        pass: RoutePass<'_>,
        solving: Solving<'_>,
    ) -> Promoted {
        let ids = self.scope_route_ids();
        // Anchors only for the wires this pass may re-solve. A wire it will not
        // touch contributes its *geometry* as occupancy, which is already in the
        // presentation — resolving where its pins are would answer a question
        // nobody asks.
        let endpoints: Vec<(RouteId, Pos2, Pos2)> = {
            let _s = tracing::info_span!("closed_anchors").entered();
            ids.iter()
                .filter(|&&id| solving.may_solve(id))
                .filter_map(|&id| {
                    let route = self.route(id)?;
                    let s = self.anchor_pos_overridden(route.from, hypo)?;
                    let e = self.anchor_pos_overridden(route.to, hypo)?;
                    Some((id, s, e))
                })
                .collect()
        };
        // Preview: work out each route's previewed exclusions BEFORE seeding, so
        // the graph matches the steady state of the old mutating flow (where a
        // trimmed or pruned corner really was gone by the next frame's build).
        let exclusions: HashMap<RouteId, PreviewExclusions> = match &pass {
            RoutePass::Preview(spec) => self.preview_exclusions(&endpoints, spec),
            RoutePass::Commit => HashMap::new(),
        };
        // A route riding entirely inside a group drag seeds its waypoints at the
        // drag's offset, because that is where `reroute_preview_closed` will
        // route them. Worked out here so seeding needs neither the pass nor its
        // spec.
        let offsets: HashMap<RouteId, GridVec> = match &pass {
            RoutePass::Preview(spec) => ids
                .iter()
                .filter_map(|&id| {
                    let route = self.route(id)?;
                    ((spec.inside)(route.from) && (spec.inside)(route.to))
                        .then_some((id, spec.grid_delta))
                })
                .collect(),
            RoutePass::Commit => HashMap::new(),
        };
        let previewed = matches!(pass, RoutePass::Preview(_));
        let obstacles = self.obstacle_rects(hypo.rects);
        let seeding = Seeding {
            hypo,
            ids: &ids,
            endpoints: &endpoints,
            exclusions: &exclusions,
            offsets: &offsets,
        };
        let mut promoted: Promoted = Vec::new();
        let mut resolved: Vec<RouteId> = Vec::new();
        // An illegal L never holds — its legs run through blocks — so a pass
        // that raised one routes it again.
        let holding: HashSet<RouteId> = endpoints
            .iter()
            .filter(|&&(id, start, end)| {
                self.route_geometry(id)
                    .is_some_and(|geometry| still_holds(geometry, start, end, &obstacles))
                    && !ripup.contains(&id)
            })
            .map(|&(id, ..)| id)
            .collect();
        match pass {
            RoutePass::Commit => {
                // Wires the straighten pass could not take verbatim. Only these
                // need a lattice, and on settled geometry there are usually
                // none: a nudge routes **zero** legs.
                let mut deferred: Vec<(RouteId, (Endpoints, Vec<Waypoint>))> = Vec::new();
                {
                    let _s = tracing::info_span!("closed_route_loop").entered();
                    let (indexed, presentation) = self.split();
                    let doc = indexed.doc;
                    for &(id, anchor_start, anchor_end) in &endpoints {
                        let Some(route) = doc.route(&id) else {
                            continue;
                        };
                        let geometry = presentation.routes.entry(id).or_default();
                        // Drop any waypoint the wire doubles back on (a 180°
                        // turn strict waypoint routing can leave behind), then
                        // force a re-route so the reversal geometry is rebuilt
                        // clean.
                        let doomed = backtracking_ordinals(
                            &route.waypoints,
                            grid_point(anchor_start),
                            grid_point(anchor_end),
                        );
                        let pruned = !doomed.is_empty();
                        let stored = if pruned {
                            pruned_waypoints(&route.waypoints, &doomed)
                        } else {
                            route.waypoints.clone()
                        };
                        if !pruned && holding.contains(&id) {
                            // An "unchanged" route may still carry a stale
                            // waypoint set from a live drag preview: the preview
                            // rewrites the edges to track the moved shape but
                            // leaves the waypoints behind, and its snapped
                            // endpoints then match here so the route reads as
                            // unchanged. Re-derive the waypoints from the
                            // (correct) edges so the "every corner is a
                            // waypoint" invariant holds and the saved geometry
                            // matches what a fresh load rebuilds.
                            promoted.push((id, promote_corners_to_waypoints(&stored, geometry)));
                            continue;
                        }
                        // Keep every straight leg; a leg that is blocked or
                        // non-colinear needs the lattice, so set the wire aside
                        // rather than build one for a pass that may not use it.
                        let ends = Endpoints {
                            start: grid_point(anchor_start),
                            end: grid_point(anchor_end),
                        };
                        match straighten_route(&stored, geometry, ends, obstacles.reroute_blocked())
                        {
                            Some(corners) => promoted.push((id, corners)),
                            None => deferred.push((id, (ends, stored))),
                        }
                    }
                }
                if !deferred.is_empty() {
                    let _s =
                        tracing::info_span!("closed_route_deferred", deferred = deferred.len())
                            .entered();
                    let mut settled: BTreeMap<RouteId, Vec<Waypoint>> = BTreeMap::new();
                    let region = healing_region(deferred.iter().flat_map(|(_, (ends, stored))| {
                        [ends.start, ends.end]
                            .into_iter()
                            .chain(stored.iter().map(|wp| wp.pos))
                    }));
                    self.heal(
                        deferred,
                        region,
                        &seeding,
                        |id, (ends, stored), geometry, lattice| {
                            let laid = reconstruct_route(
                                stored,
                                geometry,
                                *ends,
                                obstacles.reroute_blocked(),
                                lattice,
                            );
                            // A retry replaces the attempt before it.
                            settled.insert(id, laid.corners);
                            laid.resolution
                        },
                    );
                    promoted.extend(settled);
                }
            }
            RoutePass::Preview(spec) => {
                // A wire whose geometry still holds keeps it and is occupancy;
                // the rest are re-routed through a lattice over the region they
                // span, never the sheet. One riding entirely inside a group
                // drag previews through its waypoints offset rigidly.
                let rerouting: Vec<(RouteId, Rerouting)> = endpoints
                    .iter()
                    .filter(|&&(id, ..)| {
                        let pruned = exclusions.get(&id).is_some_and(|x| x.pruned);
                        pruned || !holding.contains(&id)
                    })
                    .filter_map(|&(id, s, e)| {
                        let route = self.route(id)?;
                        let ends = Endpoints {
                            start: grid_point(s),
                            end: grid_point(e),
                        };
                        let rigid = ((spec.inside)(route.from) && (spec.inside)(route.to))
                            .then_some(spec.grid_delta);
                        let stored = route.waypoints.clone();
                        Some((
                            id,
                            Rerouting {
                                ends,
                                stored,
                                rigid,
                            },
                        ))
                    })
                    .collect();
                if !rerouting.is_empty() {
                    let region = healing_region(rerouting.iter().flat_map(|(id, wire)| {
                        [wire.ends.start, wire.ends.end]
                            .into_iter()
                            .chain(seeded_waypoints(self, &seeding, *id))
                    }));
                    let _s = tracing::info_span!("closed_route_loop", routes = rerouting.len())
                        .entered();
                    // Drawn somewhere the document does not put it, so the
                    // cull set and the take-back have to be told.
                    resolved.extend(rerouting.iter().map(|&(id, _)| id));
                    let no_exclusions = PreviewExclusions::default();
                    self.heal(
                        rerouting,
                        region,
                        &seeding,
                        |id, wire, geometry, lattice| match wire.rigid {
                            Some(delta) => reroute_preview_closed(
                                &wire.stored,
                                geometry,
                                wire.ends,
                                delta,
                                lattice,
                            ),
                            None => reroute_preview_excluding(
                                &wire.stored,
                                geometry,
                                wire.ends,
                                &exclusions.get(&id).unwrap_or(&no_exclusions).excluded,
                                lattice,
                            ),
                        },
                    );
                }
            }
        }
        if previewed {
            let scope = self.scope_path().clone();
            self.presentation
                .routes_previewed(resolved.iter().copied(), &scope);
            self.preview_routes(resolved);
        }
        promoted
    }

    /// Is this wire one of the set being reconstructed? A wire with no
    /// geometry yet has never been reconstructed, so a rectangle always
    /// reaches it.
    fn route_reaches(&self, id: RouteId, reconstructing: Reconstructing<'_>) -> bool {
        match reconstructing {
            Reconstructing::Everything => true,
            Reconstructing::These(these) => these.contains(&id),
            Reconstructing::Within {
                disturbed: region,
                previewed,
            } => {
                if previewed.contains(&id) {
                    return true;
                }
                let Some(geometry) = self.route_geometry(id) else {
                    return true;
                };
                region.contains(geometry.start_pos())
                    || region.contains(geometry.end_pos())
                    || geometry.iter_edges().any(|(_, edge)| {
                        region.contains(px_point(edge.start)) || region.contains(px_point(edge.end))
                    })
            }
        }
    }

    /// Reconstruct every route's edge geometry from its stored corner waypoints
    /// WITHOUT globally re-routing. Straight (axis-aligned, unobstructed) legs are
    /// drawn directly; only non-colinear or obstacle-crossing legs are routed, and
    /// then only for the routes that need it. A clean block (every leg straight) is
    /// rebuilt with zero pathfinding, so stored/hand-adjusted geometry is preserved
    /// exactly. This is the load-time reconstruction; the interactive mutation
    /// path reuses the same per-leg policy.
    pub fn reconstruct_routes(&mut self) {
        self.reconstruct_routes_reaching(Reconstructing::Everything);
    }

    /// The same reconstruction, confined to the wires `reconstructing` names.
    ///
    /// A wire it does not reach is drawn from geometry that is still correct —
    /// nothing moved near it — so re-deriving it would spend the sheet's time
    /// to arrive back where it started. A commit that knows what it disturbed
    /// passes that rectangle; an open, an undo or a foreign commit knows
    /// nothing and passes [`Reconstructing::Everything`]; a preview's next
    /// borrow takes back [`Reconstructing::These`] wires it drew.
    pub(crate) fn reconstruct_routes_reaching(&mut self, reconstructing: Reconstructing<'_>) {
        let ids: Vec<RouteId> = self
            .scope_route_ids()
            .into_iter()
            .filter(|&id| self.route_reaches(id, reconstructing))
            .collect();
        if ids.is_empty() {
            return;
        }
        let endpoints: Vec<(RouteId, GridPoint, GridPoint)> = {
            let _s = tracing::info_span!("anchors", routes = ids.len()).entered();
            ids.iter()
                .filter_map(|&id| {
                    let route = self.route(id)?;
                    let s = self.anchor_pos_overridden(route.from, GeometryOverrides::default())?;
                    let e = self.anchor_pos_overridden(route.to, GeometryOverrides::default())?;
                    Some((id, grid_point(s), grid_point(e)))
                })
                .collect()
        };
        let obstacles = {
            let _s = tracing::info_span!("obstacles").entered();
            self.obstacle_rects(&[])
        };

        // Phase 1: straighten every leg we can; defer routes that still need the
        // router (some leg blocked or non-colinear).
        let mut deferred: Vec<(RouteId, (Endpoints, Vec<Waypoint>))> = Vec::new();
        {
            let _s = tracing::info_span!("straighten", routes = endpoints.len()).entered();
            let (indexed, presentation) = self.split();
            let doc = indexed.doc;
            for &(id, s, e) in &endpoints {
                let Some(route) = doc.route(&id) else {
                    continue;
                };
                let geometry = presentation.routes.entry(id).or_default();
                let ends = Endpoints { start: s, end: e };
                if straighten_route(&route.waypoints, geometry, ends, obstacles.keep_blocked())
                    .is_none()
                {
                    deferred.push((id, (ends, route.waypoints.clone())));
                }
            }
        }

        // Phase 2: only if something needs routing, heal it — through a lattice
        // over the rectangle it spans, as a commit does: a load that defers three
        // wires has no more reason to lattice the sheet than a commit that defers
        // three. A first settle defers everything, so its region is the sheet.
        if !deferred.is_empty() {
            let _s = tracing::info_span!("route_deferred", deferred = deferred.len()).entered();
            let anchors: Vec<(RouteId, Pos2, Pos2)> = endpoints
                .iter()
                .map(|&(id, s, e)| (id, px_point(s), px_point(e)))
                .collect();
            let (exclusions, offsets) = (HashMap::new(), HashMap::new());
            let seeding = Seeding {
                hypo: GeometryOverrides::default(),
                ids: &ids,
                endpoints: &anchors,
                exclusions: &exclusions,
                offsets: &offsets,
            };
            let region = healing_region(deferred.iter().flat_map(|(_, (ends, stored))| {
                [ends.start, ends.end]
                    .into_iter()
                    .chain(stored.iter().map(|wp| wp.pos))
            }));
            self.heal(
                deferred,
                region,
                &seeding,
                |_, (ends, stored), geometry, lattice| {
                    reconstruct_route(stored, geometry, *ends, obstacles.keep_blocked(), lattice)
                        .resolution
                },
            );
        }
    }

    /// The route's resolved, snapped anchor endpoints against the settled
    /// document — the ends every route-edit relayout runs between.
    fn route_ends(&self, id: RouteId) -> Option<Endpoints> {
        let route = self.route(id)?;
        let s = self.anchor_pos_overridden(route.from, GeometryOverrides::default())?;
        let e = self.anchor_pos_overridden(route.to, GeometryOverrides::default())?;
        Some(Endpoints {
            start: grid_point(s),
            end: grid_point(e),
        })
    }

    /// Re-lay a single route's edges directly from `corners`, WITHOUT the
    /// router — straight legs stay straight and a diagonal leg gets an
    /// L-bend, so the wire goes exactly where it was put and never
    /// autoroutes. Returns the corner list the relayed geometry promotes and
    /// each captured label anchor re-projected onto it: the pair the route
    /// edit's commit pushes as ops.
    fn relay_route(
        &mut self,
        id: RouteId,
        corners: &[GridPoint],
        stored: &[Waypoint],
        anchors: &[(RouteLabelId, Pos2)],
    ) -> Option<RelaidRoute> {
        let ends = self.route_ends(id)?;
        let geometry = self.presentation.routes.entry(id).or_default();
        reconstruct_corners_direct(corners, geometry, ends);
        let relayed = reanchored(geometry, anchors);
        let promoted = promote_corners_to_waypoints(stored, geometry);
        // The relay ignores obstacles on purpose, so what it left is not what
        // the document implies — a drag that ended where it started commits
        // nothing, and this is what takes its preview back.
        let scope = self.scope_path().clone();
        self.presentation.routes_previewed([id], &scope);
        Some((promoted, relayed))
    }

    /// Plan a route edit: classify where each cursor's working corner lands on
    /// route `id` — a grabbed existing corner within half a cell is reused,
    /// anything else inserts in path order — and capture each label's world
    /// anchor. Read-only: [`Self::preview_route_edit`] renders the plan per
    /// drag frame and [`Self::commit_route_edit`] applies it on release, so
    /// between them the document is never written. Cursors must sit at least a
    /// cell apart (the edge drag's boundary seeds guarantee it); two cursors
    /// collapsing onto one working corner abort the plan.
    pub fn route_edit_session(&self, id: RouteId, cursors: &[Pos2]) -> Option<RouteEditSession> {
        let wire = self.auto_route(id)?;
        let geometry = self.route_geometry(id)?;
        // Planned against a working copy, so the second cursor sees the first
        // cursor's insertion — the same list `corners` replays the slots
        // against, built by the same function so the two cannot mean
        // different things by an index into it.
        let mut working = keyed_corners(&wire.route.waypoints, |wp| px_point(wp.pos));
        let mut slots = Vec::with_capacity(cursors.len());
        for &cursor in cursors {
            let hit = working
                .iter()
                .find(|(_, pos)| pos.distance(cursor) <= GRID_SIZE * 0.5)
                .copied();
            match hit {
                Some((Some(ordinal), _)) => slots.push(WaypointSlot::Existing(ordinal)),
                Some((None, _)) => return None,
                None => {
                    let d_new = geometry.distance_along(cursor);
                    let index = working
                        .iter()
                        .filter(|&&(_, pos)| geometry.distance_along(pos) < d_new)
                        .count();
                    let pos = px_point(grid_point(cursor));
                    working.insert(index, (None, pos));
                    slots.push(WaypointSlot::InsertAt(index));
                }
            }
        }
        Some(RouteEditSession {
            slots,
            anchors: label_anchors(&wire.labels, geometry),
        })
    }

    /// Relay route `id` directly through the session's hypothetical corner
    /// list at `cursors` — the pure per-frame preview of a route edit. Writes
    /// derived geometry only; the authored route and its labels (the drag
    /// overlay draws them pinned at the session's anchors) are untouched.
    pub fn preview_route_edit(
        &mut self,
        _phase: &crate::widget::PreviewPhase,
        id: RouteId,
        session: &RouteEditSession,
        cursors: &[Pos2],
    ) {
        let Some(ends) = self.route_ends(id) else {
            return;
        };
        let Some(route) = self.route(id) else {
            return;
        };
        let corners: Vec<GridPoint> = session
            .corners(&route.waypoints, cursors)
            .into_iter()
            .map(|(pos, _)| pos)
            .collect();
        let routes = &mut self.presentation.routes;
        let geometry = routes.entry(id).or_default();
        reconstruct_corners_direct(&corners, geometry, ends);
        let scope = self.scope_path().clone();
        self.presentation.routes_previewed([id], &scope);
    }

    /// Finalize a route edit — the drag's one document write. Relays the
    /// session's working corners (locked: the user placed them), promotes the
    /// resulting corners so the hand-placed geometry persists, and re-anchors
    /// each label to its captured drag-start position.
    pub fn commit_route_edit(&mut self, id: RouteId, session: &RouteEditSession, cursors: &[Pos2]) {
        let Some(route) = self.route(id) else {
            return;
        };
        let edited: Vec<Waypoint> = session
            .corners(&route.waypoints, cursors)
            .into_iter()
            .map(|(pos, lock)| Waypoint {
                pos,
                locked: lock.is_locked(),
            })
            .collect();
        let corners: Vec<GridPoint> = edited.iter().map(|wp| wp.pos).collect();
        let anchors = session.anchors.clone();
        let Some((waypoints, relayed)) = self.relay_route(id, &corners, &edited, &anchors) else {
            return;
        };
        self.author("commit_route_edit", |indexed, sink| {
            crate::edit::geometry::commit_route_edit(
                indexed.doc,
                crate::edit::geometry::RouteEdit {
                    route: id,
                    waypoints,
                    anchors: &relayed,
                },
                sink,
            );
        });
    }

    /// Rip up a route entirely and autoroute it fresh: drop every waypoint so the
    /// endpoints re-route on Dijkstra cost alone, with no user-placed corners.
    /// The gesture's solve rider re-promotes the corners the router finds.
    pub fn reroute(&mut self, id: RouteId) {
        self.author("reroute", |indexed, sink| {
            crate::edit::geometry::reroute(indexed, id, &[], sink);
        });
        self.rip_up(&[id]);
    }

    /// Rip up and autoroute every wire of THIS scope with an endpoint on
    /// `block` (either end): drop their user waypoints and let the rider
    /// re-solve them. The block-wide analogue of [`Self::reroute`].
    ///
    /// Scoped deliberately: a block's pins are its boundary ports, so the
    /// wires *inside* it end on the same ids. Those are drawn one level
    /// down, the rider does not re-solve them, and tearing up a path nobody
    /// re-lays would just lose it.
    pub fn reroute_block(&mut self, block: blockworx_doc::id::BlockId) {
        let on_block: HashSet<PinId> = self
            .block_pins(crate::path::Scope::Block(block))
            .into_iter()
            .map(|(id, _)| id)
            .collect();
        let ids: Vec<RouteId> = self
            .scope_route_ids()
            .into_iter()
            .filter(|&id| {
                self.route(id)
                    .is_some_and(|r| on_block.contains(&r.from) || on_block.contains(&r.to))
            })
            .collect();
        for &id in &ids {
            self.author("reroute_block", |indexed, sink| {
                crate::edit::geometry::reroute(indexed, id, &[], sink);
            });
        }
        self.rip_up(&ids);
    }

    /// Forget what these wires were solved to, so the next pass re-solves
    /// them from nothing rather than keeping the path the user just tore up.
    /// The rip-up is the one gesture that must NOT be handed its own previous
    /// answer, and dropped geometry is how the solve is told so.
    fn rip_up(&mut self, ids: &[RouteId]) {
        for id in ids {
            self.presentation.routes.remove(id);
        }
        let scope = self.scope_path().clone();
        self.presentation
            .routes_previewed(ids.iter().copied(), &scope);
    }

    /// Closed-router view of the current scope's geometry and existing-route
    /// occupancy, for tools that pathfind against it without mutating the
    /// document (`RouteTool`). The graph is built ONCE (obstacles + every existing
    /// route's endpoints and waypoints + `extra_seeds`), then existing routes are
    /// re-applied as `WIRE_COST` occupancy in place — no per-route rebuild.
    /// `extra_seeds` seeds the points the caller will route through (an in-progress
    /// route's endpoints/waypoints) so they exist as graph nodes.
    pub fn scratch_closed_router(&self, extra_seeds: &[Point]) -> ClosedRouter {
        let ids = self.scope_route_ids();
        let mut seeds: Vec<Point> = Vec::new();
        for &id in &ids {
            let Some(route) = self.route(id) else {
                continue;
            };
            if let Some(s) = self.anchor_pos_overridden(route.from, GeometryOverrides::default()) {
                seeds.push(snap_to_grid(s).into());
            }
            if let Some(e) = self.anchor_pos_overridden(route.to, GeometryOverrides::default()) {
                seeds.push(snap_to_grid(e).into());
            }
            for wp in route.waypoints.clone() {
                seeds.push(wp.pos.into());
            }
        }
        seeds.extend_from_slice(extra_seeds);
        let mut router = self.build_closed_router(GeometryOverrides::default(), &seeds);
        for &id in &ids {
            if let Some(geometry) = self.presentation.routes.get(&id) {
                add_route_cost(
                    &mut router,
                    geometry.iter_edges().map(|(_, e)| e),
                    WIRE_COST,
                );
            }
        }
        router
    }

    /// Where a gesture on `foreground` routes, for the diagnostic overlay: the
    /// healing region around every wire it raises, and the lattice the router
    /// builds there with everything else laid in as occupancy.
    ///
    /// The largest bound such a gesture uses: a pass heals only the raised
    /// wires that need routing, and the region around those is inside this
    /// one. `None` when the foreground raises no wire of this scope.
    pub fn healing_bound(&self, foreground: &Foreground) -> Option<(Rect, Vec<Mark>)> {
        let ids = self.scope_route_ids();
        let raised: Vec<(RouteId, Endpoints)> = ids
            .iter()
            .filter(|&&id| foreground.holds_route(id))
            .filter_map(|&id| Some((id, self.route_ends(id)?)))
            .collect();
        if raised.is_empty() {
            return None;
        }
        let endpoints: Vec<(RouteId, Pos2, Pos2)> = raised
            .iter()
            .map(|&(id, ends)| (id, px_point(ends.start), px_point(ends.end)))
            .collect();
        let (exclusions, offsets) = (HashMap::new(), HashMap::new());
        let seeding = Seeding {
            hypo: GeometryOverrides::default(),
            ids: &ids,
            endpoints: &endpoints,
            exclusions: &exclusions,
            offsets: &offsets,
        };
        let region = healing_region(raised.iter().flat_map(|&(id, ends)| {
            [ends.start, ends.end]
                .into_iter()
                .chain(seeded_waypoints(self, &seeding, id))
        }));
        let routed: HashSet<RouteId> = raised.iter().map(|&(id, _)| id).collect();
        let lattice = self.healing_lattice(Region::Within(region), &seeding, &routed);
        Some((region, lattice.debug_marks()))
    }
}

#[cfg(test)]
mod tests {
    use blockworx_doc::{
        block_model::RouteUpdate,
        opcode::{Crud, OpCodes},
    };
    use blockworx_doc::{
        fixtures::{block_id, pin_id, route_id},
        geometry::{GridPoint, PinSlot, Waypoint},
        id::RouteId,
        values::PinSide,
    };
    use blockworx_geom::{Rect, pos2, vec2};

    use super::{GeometryOverrides, Region, healing_region};
    use crate::{
        edit::{
            geometry::{PinMove, RouteEnd, trimmed_approach},
            naming::InterfaceLock,
        },
        grid::{GRID_SIZE, grid_point, px_point},
        path::Scope,
        presentation::{RouteEdge, RouteGeometry},
        shape::{BaseShape, ShapeId, ShapeRef},
        widget::{
            auto_route::Wire,
            drawing::Drawing,
            test_fixtures::{
                self as fx, Scene, route_passes_through, two_blocks_with_a_routed_waypoint,
            },
        },
    };

    /// The plan and its replay have to agree about what an insertion index
    /// counts. Two cursors that both make new corners are the case where
    /// they can disagree: the second is planned against a list the first has
    /// already grown, so a replay that rebuilt the list differently — or
    /// applied the slots in another order — would put the second corner
    /// somewhere the preview never drew it.
    #[test]
    fn a_two_corner_plan_replays_in_the_order_it_was_planned() {
        let mut scene = two_blocks_with_a_routed_waypoint();
        fx::reconstruct(&mut scene);
        let route = route_id(5);
        let drawing = scene.drawing();
        let geometry = drawing
            .route_geometry(route)
            .expect("the fixture's wire is reconstructed")
            .clone();
        // Two points on the wire, a long way apart and neither on the stored
        // corner, so both slots are insertions rather than grabs. Taken as
        // edge midpoints, which are on the polyline by construction — a
        // guessed point would miss the wire and plan nothing.
        let edges: Vec<_> = geometry.iter_edges().map(|(_, e)| e.clone()).collect();
        assert!(
            edges.len() >= 2,
            "precondition: the wire needs two edges to insert around",
        );
        let midpoint =
            |e: &RouteEdge| px_point(e.start) + (px_point(e.end) - px_point(e.start)) * 0.5;
        let (early, late) = (midpoint(&edges[0]), midpoint(&edges[edges.len() - 1]));
        let stored = drawing
            .auto_route(route)
            .expect("the wire is in scope")
            .route
            .waypoints
            .clone();
        assert_eq!(
            stored.len(),
            1,
            "precondition: one stored corner to insert around",
        );

        let session = drawing
            .route_edit_session(route, &[early, late])
            .expect("two well-separated cursors plan");
        let corners = session.corners(&stored, &[early, late]);

        assert_eq!(
            corners.len(),
            3,
            "one stored corner plus two insertions: {corners:?}",
        );
        let locked: Vec<usize> = corners
            .iter()
            .enumerate()
            .filter(|(_, (_, lock))| *lock == InterfaceLock::Locked)
            .map(|(i, _)| i)
            .collect();
        assert_eq!(
            locked.len(),
            2,
            "the two the user placed come out locked: {corners:?}",
        );
        // Planned early-then-late, so the replay must keep that order: the
        // earlier cursor's corner sits before the later one's.
        let (first, second) = (corners[locked[0]].0, corners[locked[1]].0);
        assert!(
            geometry.distance_along(px_point(first)) < geometry.distance_along(px_point(second)),
            "the replay reordered the planned corners: {first:?} then {second:?}",
        );
    }

    /// The walls of a ring around block `1`, by id, in whole cells. The west
    /// wall is far from the wire, which runs east.
    const RING: [(u32, (i32, i32, i32, i32)); 4] = [
        (10, (0, 0, 44, 4)),
        (11, (0, 52, 44, 4)),
        (12, (40, 4, 4, 48)),
        (WEST_WALL, (0, 4, 4, 48)),
    ];
    const WEST_WALL: u32 = 13;

    /// Block `1` inside the `walls` of [`RING`] that are listed, wired east to
    /// block `2` outside it, whose top sits at `far_top` cells: pins `3`/`4`,
    /// route `5`.
    fn walled_in_wire(walls: &[u32], far_top: i32) -> Scene {
        let mut ops = vec![
            fx::block_in(1, Scope::Root, fx::cells(26, 26, 4, 4)),
            fx::block_in(2, Scope::Root, fx::cells(80, far_top, 4, 4)),
        ];
        for (n, (x, y, w, h)) in RING {
            if walls.contains(&n) {
                ops.push(fx::block_in(n, Scope::Root, fx::cells(x, y, w, h)));
            }
        }
        ops.extend([
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[]),
        ]);
        let mut scene = Scene::new(ops);
        fx::reconstruct(&mut scene);
        scene
    }

    /// The walls of [`RING`] `geometry` runs through.
    fn walls_crossed(geometry: &RouteGeometry, walls: &[u32]) -> Vec<u32> {
        RING.iter()
            .filter(|(n, _)| walls.contains(n))
            .filter(|&&(_, (x, y, w, h))| {
                geometry.iter_edges().any(|(_, e)| {
                    let (x0, x1) = (e.start.x.min(e.end.x), e.start.x.max(e.end.x));
                    let (y0, y1) = (e.start.y.min(e.end.y), e.start.y.max(e.end.y));
                    x0 < x + w && x < x1.max(x0 + 1) && y0 < y + h && y < y1.max(y0 + 1)
                })
            })
            .map(|&(n, _)| n)
            .collect()
    }

    /// Every routing shape of the scene's scope, for asking where wires cross
    /// them.
    fn routing_shape_ids(drawing: &Drawing<'_>) -> Vec<ShapeId> {
        drawing
            .routing_shapes()
            .into_iter()
            .map(|(id, _)| id)
            .collect()
    }

    const ALL_WALLS: [u32; 4] = [10, 11, 12, WEST_WALL];
    const EAST_WALL: u32 = 12;

    /// A wire the whole sheet holds no path for settles on its fallback L: the
    /// gesture that raised it writes the L's corners, and the draw pass marks
    /// where the L runs through a block — not the wire's color, which an
    /// accent can share.
    #[test]
    fn an_unroutable_wire_settles_on_its_l_and_is_marked_where_it_crosses() {
        let rid = route_id(5);
        let mut scene = walled_in_wire(&ALL_WALLS, 40);
        assert!(
            stored_corners(&scene.drawing(), rid).is_empty(),
            "precondition: the wire starts with no corners"
        );

        scene.commit(|drawing| {
            drawing.move_shape(ShapeId::Rect(block_id(2)), vec2(0.0, GRID_SIZE));
        });

        let corners = stored_corners(&scene.drawing(), rid);
        assert_eq!(corners.len(), 1, "the L's one bend is written: {corners:?}");
        let geometry = fx::geometry(&scene, rid);
        assert_eq!(walls_crossed(geometry, &ALL_WALLS), vec![EAST_WALL]);
        let drawing = scene.drawing();
        let marks = drawing
            .standing_conflicts(&routing_shape_ids(&drawing))
            .crossings;
        let (x, y, w, h) = RING[2].1;
        let east = fx::cells(x, y, w, h);
        assert!(!marks.is_empty(), "the illegal stretch is marked");
        assert!(
            marks.iter().all(|mark| mark.intersects(east)),
            "every mark sits on the wall the L runs through: {marks:?}"
        );
    }

    /// An illegal wire costs nothing while nothing touches it: a commit that
    /// never raised it leaves it exactly as it is, even one that opens a path
    /// for it — and the commit that does raise it routes it.
    #[test]
    fn an_illegal_wire_is_rerouted_only_by_a_commit_that_raises_it() {
        let rid = route_id(5);
        let west = ShapeId::Rect(block_id(WEST_WALL));
        let mut scene = walled_in_wire(&ALL_WALLS, 40);
        scene.commit(|drawing| {
            drawing.move_shape(ShapeId::Rect(block_id(2)), vec2(0.0, GRID_SIZE));
        });
        let settled = route_edges(&scene.drawing(), rid);
        {
            let drawing = scene.drawing();
            let raised = crate::widget::foreground::Foreground::raising([west], &drawing);
            assert!(
                !raised.holds_route(rid),
                "precondition: deleting the west wall does not raise the wire"
            );
        }

        scene.commit(|drawing| drawing.delete(crate::shape::Deletable::Shape(west)));
        assert!(
            !scene
                .committed()
                .iter()
                .any(|op| matches!(op, OpCodes::Route(id, _) if *id == rid)),
            "the far delete wrote the wire"
        );
        assert_eq!(route_edges(&scene.drawing(), rid), settled);

        let east = ShapeId::Rect(block_id(EAST_WALL));
        scene.commit(|drawing| drawing.delete(crate::shape::Deletable::Shape(east)));
        let standing = [10, 11];
        assert_eq!(
            walls_crossed(fx::geometry(&scene, rid), &standing),
            Vec::<u32>::new()
        );
        let drawing = scene.drawing();
        assert!(
            drawing
                .standing_conflicts(&routing_shape_ids(&drawing))
                .crossings
                .is_empty(),
            "the rerouted wire is legal"
        );
    }

    /// Wires the router laid are never marked: on a settled grid, ports and
    /// all, no wire runs through a routing shape.
    #[test]
    fn a_settled_grid_has_no_wire_conflicts() {
        let mut scene = fx::scale_scene(6);
        let drawing = scene.drawing();
        assert!(
            !drawing.scope_route_ids().is_empty(),
            "precondition: the grid has wires"
        );
        assert_eq!(
            drawing
                .standing_conflicts(&routing_shape_ids(&drawing))
                .crossings,
            Vec::<Rect>::new()
        );
    }

    /// The diagnostic's bound holds every wire the selection raises, and the
    /// lattice it shows is the region's, not the sheet's: nothing drawn falls
    /// outside the bound.
    #[test]
    fn the_diagnostic_shows_the_bounded_lattice_a_selection_heals_in() {
        let mut scene = fx::scale_scene(6);
        let drawing = scene.drawing();
        let block = drawing
            .child_blocks()
            .first()
            .map(|&(id, _)| ShapeId::Rect(id))
            .expect("the grid has blocks");
        let foreground = crate::widget::foreground::Foreground::raising([block], &drawing);
        let (bound, marks) = drawing
            .healing_bound(&foreground)
            .expect("a block with wires raises some");
        let raised: Vec<RouteId> = foreground.routes().collect();
        assert!(!raised.is_empty(), "precondition: the block raises wires");
        for &id in &raised {
            let ends = drawing.route_ends(id).expect("a raised wire has ends");
            assert!(
                bound.contains(px_point(ends.start)) && bound.contains(px_point(ends.end)),
                "{id:?} lies outside the bound"
            );
        }
        let sheet = drawing
            .child_blocks()
            .iter()
            .filter_map(|&(id, _)| drawing.shape(ShapeId::Rect(id)))
            .map(|shape| shape.gui_rect())
            .reduce(|a, b| a.union(b))
            .expect("the grid has blocks");
        assert!(
            !bound.contains_rect(sheet),
            "precondition: the bound is smaller than the sheet"
        );
        let slack = bound.expand(GRID_SIZE);
        let outside: Vec<_> = marks
            .iter()
            .filter_map(|mark| match *mark {
                blockworx_router::turtle::Mark::Line { from, to } => {
                    (!slack.contains(from) || !slack.contains(to)).then_some(from)
                }
                blockworx_router::turtle::Mark::Circle { center, .. }
                | blockworx_router::turtle::Mark::Label { pos: center, .. } => {
                    (!slack.contains(center)).then_some(center)
                }
            })
            .take(4)
            .collect();
        assert!(!marks.is_empty(), "precondition: the lattice has marks");
        assert!(
            outside.is_empty(),
            "the lattice reaches past its bound: {outside:?}"
        );
    }

    /// A region lattice is bounded by the router, not merely built from the
    /// blocks near the region: a lane escaping it runs where the region dropped
    /// every block, and a wire routed along it passes through them as though
    /// they were not there.
    #[test]
    fn a_region_lattice_holds_nothing_outside_its_region() {
        let mut scene = walled_in_wire(&ALL_WALLS, 26);
        let drawing = scene.drawing();
        let region = Region::Within(fx::cells(18, 16, 74, 24));
        let lattice = drawing.build_router_within(region, GeometryOverrides::default(), &[]);
        let nodes = lattice.fingerprint();
        assert!(
            !nodes.points().is_empty(),
            "precondition: the region holds a lattice"
        );
        let escaped: Vec<_> = nodes
            .points()
            .iter()
            .filter(|&&p| !region.bounds().holds(p))
            .take(4)
            .collect();
        assert!(escaped.is_empty(), "lanes escaped the region: {escaped:?}");
    }

    /// A wire whose only way round lies beyond its healing region is not left
    /// on its L: the bounded lattice fails, and the whole scope is tried.
    #[test]
    fn a_region_too_small_to_detour_in_grows_to_the_scope() {
        let rid = route_id(5);
        let standing = [10, 11, EAST_WALL];
        let mut scene = walled_in_wire(&standing, 26);
        let geometry = fx::geometry(&scene, rid);
        let region = healing_region([geometry.start_pos, geometry.end_pos]);
        let (x, y, w, h) = RING[2].1;
        let east = fx::cells(x, y, w, h);
        assert!(
            east.min.y <= region.min.y && region.max.y <= east.max.y,
            "precondition: the east wall cuts the region in two, so it holds no path"
        );
        assert!(
            !region.intersects(fx::cells(0, 4, 4, 48)),
            "precondition: the gap the path needs lies outside the region"
        );
        assert_eq!(
            walls_crossed(geometry, &standing),
            vec![EAST_WALL],
            "precondition: the document's straight wire runs through the east wall"
        );

        scene.commit(|drawing| {
            drawing.move_shape(ShapeId::Rect(block_id(2)), vec2(GRID_SIZE, 0.0));
        });
        assert_eq!(
            walls_crossed(fx::geometry(&scene, rid), &standing),
            Vec::<u32>::new()
        );
    }

    /// Two blocks joined by one straight wire, B at `x_b`. Blocks `1`/`2`,
    /// pins `3`/`4`, route `5`.
    fn a_to_b_route(x_b: f32) -> Scene {
        Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, x_b),
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[]),
        ])
    }

    fn route_edges(drawing: &Drawing<'_>, rid: RouteId) -> Vec<(GridPoint, GridPoint)> {
        drawing
            .route_geometry(rid)
            .unwrap()
            .iter_edges()
            .map(|(_, e)| (e.start, e.end))
            .collect()
    }

    fn stored_corners(drawing: &Drawing<'_>, rid: RouteId) -> Vec<GridPoint> {
        drawing
            .auto_route(rid)
            .expect("the route is in this scope")
            .route
            .waypoints
            .iter()
            .map(|wp| wp.pos)
            .collect()
    }

    #[test]
    fn a_drag_preview_moves_only_the_dragged_endpoint() {
        let mut scene = a_to_b_route(120.0);
        let rid = route_id(5);
        let mut drawing = scene.drawing();
        // Baseline routing against the stored positions.
        drawing.solve_routes(&[]);
        let start0 = drawing.route_geometry(rid).unwrap().start_pos();
        let end0 = drawing.route_geometry(rid).unwrap().end_pos();

        // Drag block `a` by a grid-aligned offset; only its endpoint follows.
        let offset = vec2(2.0 * GRID_SIZE, GRID_SIZE);
        drawing.preview_drag(
            &crate::widget::PreviewPhase::testing(),
            &[(ShapeId::Rect(block_id(1)), offset)],
        );

        let g = drawing.route_geometry(rid).unwrap();
        assert_eq!(g.start_pos(), start0 + offset);
        assert_eq!(g.end_pos(), end0);
    }

    /// `add_route_label` and `place_route_label` are both wire-label writes
    /// (`edit::create::wire_label`, `edit::geometry::place_wire_label`), so
    /// each is a gesture of its own here.
    #[test]
    fn place_route_label_stores_the_distance_it_is_given() {
        let mut scene = a_to_b_route(120.0);
        let rid = route_id(5);

        let (on_wire, lid) = scene.commit(|drawing| {
            let geometry = drawing
                .route_geometry(rid)
                .expect("the route is reconstructed");
            let points = geometry.points();
            assert!(points.len() >= 2, "the route has at least one segment");
            let on_wire = points[0] + (points[1] - points[0]) * 0.5;
            let lid = drawing
                .add_route_label(rid, on_wire)
                .expect("the label lands on the reconstructed route");
            (on_wire, lid)
        });
        let _ = on_wire;

        let stored = |scene: &mut Scene| -> blockworx_doc::geometry::FracVal {
            scene
                .drawing()
                .auto_route(rid)
                .expect("the route is in this scope")
                .labels
                .iter()
                .find(|(id, _)| *id == lid)
                .map(|&(_, dist)| dist)
                .expect("the label is on the wire")
        };
        let before = stored(&mut scene);
        let target = blockworx_doc::geometry::FracVal::from(f32::from(before) + GRID_SIZE);
        assert_ne!(before, target, "the test moves the label somewhere new");

        scene.commit(|drawing| drawing.place_route_label(lid, target));

        assert_eq!(stored(&mut scene), target);
    }

    #[test]
    fn moving_a_distant_block_leaves_unrelated_routes_byte_identical() {
        // Goal A: a purely local edit must not perturb the rest of the network.
        let mut scene = a_to_b_route(120.0);
        let far = block_id(9);
        scene.apply(vec![fx::block(9, 600.0)]); // nowhere near the route
        let rid = route_id(5);
        let before = route_edges(&scene.drawing(), rid);

        // Commit a move of the distant block.
        scene.commit(|drawing| {
            drawing.move_shapes(
                &[ShapeId::Rect(far)],
                vec2(2.0 * GRID_SIZE, 3.0 * GRID_SIZE),
            );
        });

        assert_eq!(
            before,
            route_edges(&scene.drawing(), rid),
            "a distant block move must leave an unrelated route byte-identical"
        );
    }

    #[test]
    fn editing_a_route_never_autoroutes_around_obstacles() {
        // Requirement: moving a route segment must not trigger an autoroute. The
        // editor relay ([`Drawing::relay_route`], which the route edit's commit
        // runs) redraws the wire straight THROUGH a block sitting on it — a
        // fresh autoroute would instead detour around it.
        let mut scene = a_to_b_route(240.0);
        // A block straddling the wire's row (grid (8,1)-(10,4)).
        scene.apply(vec![fx::block_in(
            9,
            Scope::Root,
            Rect::from_min_max(pos2(120.0, 20.0), pos2(160.0, 60.0)),
        )]);
        let rid = route_id(5);
        let mut drawing = scene.drawing();

        drawing
            .relay_route(rid, &[], &[], &[])
            .expect("the wire has resolvable endpoints");

        assert_eq!(
            route_edges(&drawing, rid).len(),
            1,
            "the relayed wire stays a single straight leg"
        );
        assert!(
            route_passes_through(
                drawing.route_geometry(rid).unwrap(),
                GridPoint { x: 7, y: 2 }
            ),
            "the relay draws straight through the block — the editor never autoroutes"
        );
    }

    #[test]
    fn drag_preview_reroutes_through_offset_waypoint() {
        // Dragging BOTH endpoints of a route with a waypoint must preview the
        // wire routed through the waypoint OFFSET by the drag delta, while the
        // STORED waypoint stays put (the drag is uncommitted).
        let mut scene = two_blocks_with_a_routed_waypoint();
        let (a, b, rid) = (block_id(1), block_id(2), route_id(5));
        let mut drawing = scene.drawing();
        drawing.solve_routes(&[]);
        let stored_before = stored_corners(&drawing, rid);
        let (start0, end0) = {
            let g = drawing.route_geometry(rid).unwrap();
            (g.start_pos(), g.end_pos())
        };

        let off = vec2(0.0, 4.0 * GRID_SIZE); // grid_delta (0, 4)
        drawing.preview_drag(
            &crate::widget::PreviewPhase::testing(),
            &[(ShapeId::Rect(a), off), (ShapeId::Rect(b), off)],
        );

        // Both endpoints follow the drag: the whole route previews rigidly shifted.
        let g = drawing.route_geometry(rid).unwrap();
        assert_eq!(g.start_pos(), start0 + off);
        assert_eq!(g.end_pos(), end0 + off);

        // The STORED waypoints are untouched by the preview (the drag is
        // uncommitted): the shift lives only in the previewed edges.
        assert_eq!(
            stored_corners(&drawing, rid),
            stored_before,
            "stored waypoints stay put; the preview is uncommitted"
        );
    }

    #[test]
    fn drag_preview_leaves_partially_selected_route() {
        // Dragging only ONE endpoint: the route straddles the selection boundary,
        // so only the dragged endpoint follows and the stored corners stay put
        // (the preview is uncommitted).
        let mut scene = two_blocks_with_a_routed_waypoint();
        let (a, rid) = (block_id(1), route_id(5));
        let mut drawing = scene.drawing();
        drawing.solve_routes(&[]);
        let stored_before = stored_corners(&drawing, rid);
        let end0 = drawing.route_geometry(rid).unwrap().end_pos();

        let off = vec2(0.0, 4.0 * GRID_SIZE);
        drawing.preview_drag(
            &crate::widget::PreviewPhase::testing(),
            &[(ShapeId::Rect(a), off)],
        );

        // The stationary endpoint stays; only the dragged one moves.
        assert_eq!(
            drawing.route_geometry(rid).unwrap().end_pos(),
            end0,
            "the un-dragged endpoint is fixed"
        );

        // A partial-selection preview re-solves the moved leg from the stable
        // corner skeleton, so it may normalize (e.g. drop a deduped revisit) but
        // must never COMMIT new corners — every surviving corner was already there.
        let stored_after = stored_corners(&drawing, rid);
        assert!(
            stored_after.iter().all(|p| stored_before.contains(p)),
            "preview introduced new corners {stored_after:?} vs {stored_before:?}"
        );
    }

    /// Two blocks whose pins sit on different slots, so the wire between them
    /// really bends, standing on the corners the SOLVER itself lays down: the
    /// throwaway corner is ripped up, which gives the settling gesture an op to
    /// author and its rider a reason to promote the solved list back. A claim
    /// about what a drag does to a wire's shape only means something about a
    /// shape the solve already agrees with.
    fn settled_bend() -> Scene {
        let tall = |n, x: f32| {
            fx::block_in(
                n,
                Scope::Root,
                Rect::from_min_max(pos2(x, 0.0), pos2(x + 40.0, 120.0)),
            )
        };
        let mut scene = Scene::new(vec![
            tall(1, 0.0),
            tall(2, 300.0),
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(4, 2, PinSide::West, 1),
            fx::route(5, Scope::Root, 3, 4, &[(10, 4)]),
        ]);
        fx::reconstruct(&mut scene);
        scene.commit(|drawing| drawing.reroute(route_id(5)));
        scene
    }

    #[test]
    fn drag_preview_matches_commit() {
        // The whole point: the previewed geometry must equal the committed
        // geometry, so releasing the drag causes no visible snap.
        let off = vec2(0.0, 4.0 * GRID_SIZE);
        let (a, b, rid) = (block_id(1), block_id(2), route_id(5));

        // Preview path.
        let mut scene = settled_bend();
        let settled = scene.drawing().route_geometry(rid).unwrap().points();
        let previewed = {
            let mut preview = scene.drawing();
            preview.preview_drag(
                &crate::widget::PreviewPhase::testing(),
                &[(ShapeId::Rect(a), off), (ShapeId::Rect(b), off)],
            );
            preview.route_geometry(rid).unwrap().points()
        };
        // Precondition: the drag previewed a move at all, so agreeing with the
        // commit is agreement about something.
        assert_ne!(previewed, settled, "the preview moved the wire");

        // Commit path (fresh scene, same drag), from the same settled solve.
        let mut scene2 = settled_bend();
        scene2.commit(|commit| commit.move_shapes(&[ShapeId::Rect(a), ShapeId::Rect(b)], off));
        // What the user sees on release: the geometry the landed commit
        // re-derives, which is the rider's promoted corners reconstructed.
        let committed = scene2.drawing().route_geometry(rid).unwrap().points();

        assert_eq!(
            previewed, committed,
            "drag preview geometry must equal the committed geometry (no release snap)"
        );
    }

    #[test]
    fn a_gesture_removes_a_backtracking_waypoint() {
        // Two waypoints planted in the open corridor between the blocks force the
        // wire east, then straight back west, then east again — a 180° reversal
        // strict waypoint routing would honour. The gesture's solve rider must
        // drop the overshoot so no edge doubles back. The blocks sit far apart
        // so the corridor is wide enough for the two interior waypoints.
        let far = (15, 1);
        let near = (5, 1);
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, 300.0),
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[far, near]),
        ]);
        let rid = route_id(5);
        // Any gesture at all: the rider re-solves the scope it touched, and
        // the reversal is what the re-solve prunes. A rip-up is the smallest
        // one that names this route.
        scene.commit(|drawing| drawing.reroute(rid));

        let drawing = scene.drawing();
        let geometry = drawing
            .route_geometry(rid)
            .expect("the route is reconstructed");
        let edges: Vec<_> = geometry.iter_edges().map(|(_, e)| e.clone()).collect();
        let doubles_back = edges.windows(2).any(|w| {
            let (ax, ay) = (w[0].end.x - w[0].start.x, w[0].end.y - w[0].start.y);
            let (bx, by) = (w[1].end.x - w[1].start.x, w[1].end.y - w[1].start.y);
            (ay == 0 && by == 0 && (ax > 0) != (bx > 0))
                || (ax == 0 && bx == 0 && (ay > 0) != (by > 0))
        });
        assert!(!doubles_back, "the wire doubles back after the gesture");
        assert!(
            !stored_corners(&drawing, rid).contains(&GridPoint { x: far.0, y: far.1 }),
            "the overshoot waypoint was dropped"
        );
    }

    #[test]
    fn trim_approach_drops_up_to_two_unlocked_corners_from_the_endpoint() {
        let wp = |x, y, locked| Waypoint {
            pos: GridPoint { x, y },
            locked,
        };
        let corners = [wp(2, 0, false), wp(4, 0, false), wp(6, 0, false)];
        let positions =
            |kept: Vec<Waypoint>| -> Vec<GridPoint> { kept.into_iter().map(|w| w.pos).collect() };

        assert_eq!(
            positions(trimmed_approach(&corners, RouteEnd::From)),
            vec![GridPoint { x: 6, y: 0 }],
            "the two leading corners nearest the start are dropped"
        );
        assert_eq!(
            positions(trimmed_approach(&corners, RouteEnd::To)),
            vec![GridPoint { x: 2, y: 0 }],
            "the two trailing corners nearest the finish are dropped"
        );

        // A locked corner ends the scan, preserving the user's explicit bend and
        // everything past it.
        let locked_first = [wp(2, 0, true), wp(4, 0, false)];
        assert_eq!(
            positions(trimmed_approach(&locked_first, RouteEnd::From)),
            vec![GridPoint { x: 2, y: 0 }, GridPoint { x: 4, y: 0 }],
            "a leading locked corner blocks the trim entirely"
        );
    }

    /// A drop trims every wire straddling the moved block in one pass — each
    /// from its moved end — and leaves a wire with both ends on the block as
    /// it was: its corners ride with the block, so none went stale.
    #[test]
    fn a_moved_blocks_straddling_wires_are_all_trimmed_together() {
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, 300.0),
            fx::block(6, 600.0),
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(7, 1, PinSide::East, 1),
            fx::pin(8, 1, PinSide::West, 0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::pin(9, 6, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[(8, 1), (8, 3), (14, 3)]),
            fx::route(10, Scope::Root, 9, 7, &[(30, 5), (8, 5), (8, 2)]),
            fx::route(11, Scope::Root, 8, 3, &[(-2, 1), (-2, -3), (5, -3)]),
        ]);
        scene.begin("drop");
        scene
            .drawing()
            .trim_partial_route_approaches(&[ShapeId::Rect(block_id(1))]);

        let written: Vec<(RouteId, Vec<GridPoint>)> = scene
            .gesture
            .ops()
            .iter()
            .filter_map(|op| match op {
                OpCodes::Route(id, Crud::Update(RouteUpdate::Waypoints(waypoints))) => {
                    Some((*id, waypoints.iter().map(|wp| wp.pos).collect()))
                }
                _ => None,
            })
            .collect();
        let at = |x, y| GridPoint { x, y };
        assert_eq!(
            written,
            vec![
                (route_id(5), vec![at(14, 3)]),
                (route_id(10), vec![at(30, 5)]),
            ],
            "each straddler loses the corners at its moved end; the loop keeps its own"
        );
    }

    #[test]
    fn flipping_a_block_reroutes_and_trims_like_a_drag() {
        // Flip L/R moves a block's pins to new sides. Like a drag, the connected
        // route drops its stale approach corner and re-routes, leaving a
        // well-formed wire (waypoints in sync with corners). Mirrors the
        // FlipShapePins handler: flip, trim approaches, re-route.
        let mut scene = two_blocks_with_a_routed_waypoint();
        let (a, rid) = (block_id(1), route_id(5));

        scene.commit(|d| {
            d.flip_shape_pins(ShapeId::Rect(a));
            d.trim_partial_route_approaches(&[ShapeId::Rect(a)]);
        });

        let d = scene.drawing();
        let wire = d.auto_route(rid).expect("the route survives the flip");
        let geometry = d.route_geometry(rid).expect("the route is reconstructed");
        assert!(
            geometry.iter_edges().next().is_some(),
            "the flipped route has geometry"
        );
        assert!(
            waypoints_are_the_corners(&wire, geometry),
            "flip re-route left the waypoints in sync with the corners"
        );
    }

    #[test]
    fn flipping_a_port_reroutes_without_moving_the_parent_pin() {
        use crate::shape::pin::{orientation, slot};
        // A boundary port on the document root, wired to a child block's pin.
        let (port_id, rid) = (pin_id(3), route_id(5));
        let mut scene = Scene::new(vec![
            fx::pin_at(
                3,
                Scope::Root,
                "io",
                fx::slot(PinSide::East, 1),
                Rect::from_min_max(pos2(0.0, 45.0), pos2(40.0, 61.0)),
            ),
            fx::block(2, 120.0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[]),
        ]);
        let pin = scene
            .drawing()
            .held_pin(port_id)
            .expect("the port's pin")
            .clone();
        let (before_side, before_orientation) = (slot(&pin).side, orientation(&pin));
        // A fresh port faces opposite the edge its pin occupies.
        assert_eq!(before_orientation, before_side.flip());

        scene.commit(|drawing| drawing.flip_shape_pins(ShapeId::Port(port_id)));

        let drawing = scene.drawing();
        let pin = drawing.held_pin(port_id).expect("the port's pin").clone();
        // The pin's edge side (what the parent block draws) is untouched; only the
        // port's facing changed.
        assert_eq!(
            slot(&pin).side,
            before_side,
            "flipping the port moved the parent pin"
        );
        assert_eq!(orientation(&pin), before_orientation.flip());

        // The route followed the port to its new facing — still connected.
        let port = drawing.shape(ShapeId::Port(port_id)).unwrap();
        let anchor = port
            .anchor_point_with_rect(port.gui_rect(), port_id)
            .unwrap();
        assert_eq!(drawing.route_geometry(rid).unwrap().start_pos(), anchor);
    }

    /// The route's stored waypoints must be exactly its edge corners (the interior
    /// vertices where the polyline bends) — the "every corner is a waypoint"
    /// invariant. A mismatch is a stale waypoint set: it renders wrong when the
    /// route is selected and changes on the next load (which re-derives it).
    fn waypoints_are_the_corners(wire: &Wire<'_>, geometry: &RouteGeometry) -> bool {
        let edges: Vec<_> = geometry.iter_edges().map(|(_, e)| e).collect();
        let corners: std::collections::HashSet<GridPoint> =
            edges.windows(2).map(|w| w[0].end).collect();
        let waypoints: std::collections::HashSet<GridPoint> =
            wire.route.waypoints.iter().map(|wp| wp.pos).collect();
        corners == waypoints
    }

    #[test]
    fn dragging_a_block_keeps_route_waypoints_matching_the_corners() {
        // B sits on a different row than A, so the wire bends — it has real
        // corners that must stay in sync with the stored waypoints.
        let (b, rid) = (block_id(2), route_id(5));
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block_in(
                2,
                Scope::Root,
                Rect::from_min_max(pos2(300.0, 150.0), pos2(340.0, 190.0)),
            ),
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[]),
        ]);
        scene.drawing().solve_routes(&[]);

        // Drag B: several live-preview frames, then the on-drop commit — exactly
        // the sequence MoveBlock produces.
        let delta = vec2(0.0, 4.0 * GRID_SIZE);
        for frame in 1..=4 {
            scene.drawing().preview_drag(
                &crate::widget::PreviewPhase::testing(),
                &[(ShapeId::Rect(b), vec2(0.0, frame as f32 * GRID_SIZE))],
            );
        }
        scene.commit(|d| {
            d.move_shape(ShapeId::Rect(b), delta);
            d.trim_partial_route_approaches(&[ShapeId::Rect(b)]);
        });

        let d = scene.drawing();
        let wire = d.auto_route(rid).unwrap();
        let geometry = d.route_geometry(rid).expect("the route is reconstructed");
        assert!(
            waypoints_are_the_corners(&wire, geometry),
            "after a drag the route's waypoints must match its corners"
        );
    }

    #[test]
    fn flipping_a_block_preserves_its_childrens_internal_routes() {
        // C's boundary port wired to a grandchild's pin — a route living inside C.
        let (c, pc, rid) = (block_id(1), pin_id(3), route_id(5));
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::pin_at(
                3,
                Scope::Block(c),
                "io",
                fx::slot(PinSide::West, 1),
                Rect::from_min_max(pos2(0.0, 45.0), pos2(40.0, 61.0)),
            ),
            fx::block_in(
                2,
                Scope::Block(c),
                Rect::from_min_max(pos2(60.0, 0.0), pos2(100.0, 40.0)),
            ),
            fx::pin(4, 2, PinSide::East, 0),
            fx::route(5, Scope::Block(c), 3, 4, &[]),
        ]);

        let anchor_before = {
            scene.path.push(c);
            let mut drawing = scene.drawing();
            drawing.solve_routes(&[]);
            let port = drawing.shape(ShapeId::Port(pc)).unwrap();
            port.anchor_point_with_rect(port.gui_rect(), pc).unwrap()
        };

        // Mirror C at the top level: its edge pins flip side, but each pin's port
        // orientation is frozen.
        scene.path.pop();
        scene.commit(|drawing| drawing.flip_shape_pins(ShapeId::Rect(c)));

        // Inside C, the boundary port hasn't moved, so its internal route keeps
        // its endpoint.
        scene.path.push(c);
        let mut drawing = scene.drawing();
        drawing.solve_routes(&[]);
        let port = drawing.shape(ShapeId::Port(pc)).unwrap();
        let anchor_after = port.anchor_point_with_rect(port.gui_rect(), pc).unwrap();
        assert_eq!(
            anchor_after, anchor_before,
            "flipping the block moved its interior port"
        );
        assert_eq!(
            drawing.route_geometry(rid).unwrap().start_pos(),
            anchor_after,
            "internal route lost its port endpoint"
        );
    }

    /// A commit that lands after a preview takes the preview back in its own
    /// pass, even when what it disturbed is nowhere near the previewed wire.
    #[test]
    fn a_commit_takes_back_a_preview_it_never_disturbed() {
        let mut scene = Scene::new(vec![
            fx::block(1, 0.0),
            fx::block(2, 120.0),
            fx::block(6, 3000.0),
            fx::pin(3, 1, PinSide::East, 0),
            fx::pin(4, 2, PinSide::West, 0),
            fx::route(5, Scope::Root, 3, 4, &[]),
        ]);
        let rid = route_id(5);
        let settled = route_edges(&scene.drawing(), rid);
        {
            let mut drawing = scene.drawing();
            drawing.preview_drag(
                &crate::widget::PreviewPhase::testing(),
                &[(ShapeId::Rect(block_id(2)), vec2(0.0, 4.0 * GRID_SIZE))],
            );
            assert_ne!(
                route_edges(&drawing, rid),
                settled,
                "precondition: the preview drew the wire somewhere else"
            );
        }
        scene.commit(|drawing| {
            drawing.move_shape(ShapeId::Rect(block_id(6)), vec2(GRID_SIZE, 0.0));
        });
        assert!(
            !scene.committed().is_empty(),
            "precondition: the far move committed"
        );
        assert_eq!(
            route_edges(&scene.drawing(), rid),
            settled,
            "the preview outlived the commit"
        );
    }

    #[test]
    fn drag_and_resize_preview_frames_never_touch_the_document() {
        // A routed waypoint makes the straddle trim and backtracking prune
        // non-trivial: the preview must *preview* corners away, not delete them.
        let mut scene = two_blocks_with_a_routed_waypoint();
        let (a, rid) = (block_id(1), route_id(5));
        scene.drawing().solve_routes(&[]);
        assert!(
            !stored_corners(&scene.drawing(), rid).is_empty(),
            "precondition: the committed route must carry corners to trim"
        );
        let before = scene.doc.clone();
        let stamp = scene.doc.stamp();

        {
            let mut drawing = scene.drawing();
            let start0 = drawing.route_geometry(rid).unwrap().start_pos();
            for frame in 1..=4 {
                let offset = vec2(GRID_SIZE * frame as f32, GRID_SIZE);
                drawing.preview_drag(
                    &crate::widget::PreviewPhase::testing(),
                    &[(ShapeId::Rect(a), offset)],
                );
            }
            assert_ne!(
                drawing.route_geometry(rid).unwrap().start_pos(),
                start0,
                "precondition: the preview really re-solved the dragged route"
            );
            let grown = drawing.shape(ShapeId::Rect(a)).unwrap().gui_rect();
            drawing.preview_resize(
                &crate::widget::PreviewPhase::testing(),
                &[(
                    ShapeId::Rect(a),
                    Rect::from_min_size(grown.min, grown.size() + vec2(GRID_SIZE, GRID_SIZE)),
                )],
            );
        }

        assert_eq!(
            scene.doc.stamp(),
            stamp,
            "a preview frame must not produce a new document value"
        );
        assert_eq!(scene.doc.clone(), before);
    }

    #[test]
    fn a_pin_drag_preview_tracks_the_hypothetical_slot_without_moving_the_pin() {
        let mut scene = a_to_b_route(120.0);
        let (a, pa, rid) = (block_id(1), pin_id(3), route_id(5));
        scene.drawing().solve_routes(&[]);
        let before = scene.doc.clone();
        let stamp = scene.doc.stamp();

        let (start0, start, previewed) = {
            let mut drawing = scene.drawing();
            let start0 = drawing.route_geometry(rid).unwrap().start_pos();
            drawing.preview_pin_drag(
                &crate::widget::PreviewPhase::testing(),
                pa,
                PinSide::East,
                3,
            );
            let start = drawing.route_geometry(rid).unwrap().start_pos();
            let previewed = match drawing.shape(ShapeId::Rect(a)).unwrap() {
                ShapeRef::Block(block) => block.pin_anchor_at(block.gui_rect(), PinSide::East, 3),
                _ => unreachable!("a is a block"),
            };
            (start0, start, previewed)
        };

        assert_ne!(start, start0, "precondition: slot 3 moves the anchor");
        assert_eq!(
            grid_point(start),
            grid_point(previewed),
            "the previewed endpoint sits at the hypothetical slot"
        );
        assert_eq!(scene.doc.stamp(), stamp);
        assert_eq!(scene.doc.clone(), before);

        // The group flow runs the same pure pass.
        {
            let mut drawing = scene.drawing();
            drawing.preview_pin_drags(
                &crate::widget::PreviewPhase::testing(),
                &[PinMove {
                    pin: pa,
                    to: PinSlot {
                        side: PinSide::East,
                        offset: 2,
                    },
                }],
            );
        }
        assert_eq!(scene.doc.stamp(), stamp);
        assert_eq!(scene.doc.clone(), before);
    }
}

#[cfg(test)]
mod region_cost {
    use super::*;
    use crate::widget::test_fixtures::{cells, scale_scene};
    use std::time::Instant;

    /// What a lattice costs when it covers the region an edit touches rather
    /// than the whole diagram.
    ///
    /// `cargo test --release -p blockworx-editor region_cost -- --ignored --nocapture`
    #[test]
    #[ignore = "a timing, not a check"]
    fn a_region_lattice_costs_what_the_region_holds() {
        let mut scene = scale_scene(50);
        let drawing = scene.drawing();

        let mut seeds: Vec<Point> = Vec::new();
        for id in drawing.scope_route_ids() {
            let Some(route) = drawing.route(id) else {
                continue;
            };
            for end in [route.from, route.to] {
                if let Some(at) = drawing.anchor_pos_overridden(end, GeometryOverrides::default()) {
                    seeds.push(snap_to_grid(at).into());
                }
            }
            for wp in &route.waypoints {
                seeds.push(wp.pos.into());
            }
        }

        let whole = Instant::now();
        let full =
            drawing.build_router_within(Region::WholeScope, GeometryOverrides::default(), &seeds);
        let whole = whole.elapsed();

        // The grid is on a 16-cell pitch with 8-cell blocks, so this holds a
        // 3×3 neighbourhood with room for their moats.
        let region = cells(-8, -8, 56, 56);
        let local = Instant::now();
        let bounded = drawing.build_router_within(
            Region::Within(region),
            GeometryOverrides::default(),
            &seeds,
        );
        let local = local.elapsed();

        let raised = Instant::now();
        let foreground = crate::widget::foreground::Foreground::raising(
            drawing
                .child_blocks()
                .first()
                .map(|&(id, _)| crate::shape::ShapeId::Rect(id)),
            &drawing,
        );
        let raised = raised.elapsed();

        eprintln!(
            "==== whole sheet: {whole:?}, {} nodes",
            full.fingerprint().nodes()
        );
        eprintln!(
            "==== raising one block: {raised:?}, {} of {} wires raised",
            foreground.routes().count(),
            drawing.scope_route_ids().len()
        );
        eprintln!(
            "==== 3×3 region:  {local:?}, {} nodes",
            bounded.fingerprint().nodes()
        );
    }
}