blockworx/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 materialization 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::{HashMap, HashSet};

use blockworx_doc::{
    commit::CommitBuilder,
    document::IndexedDocument,
    geometry::{GridPoint, GridVec, Waypoint},
    id::{PinId, RouteId, RouteLabelId},
    values::PinSide,
};
use blockworx_geom::{Pos2, Rect, Vec2, vec2};
use blockworx_router::{
    ClosedRouter, 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,
    shape::{ShapeId, ShapeRef},
    widget::{
        auto_route::{
            label_anchors, reanchored, recompute_route_crossings, reroute_preview_closed,
            reroute_preview_excluding,
        },
        drawing::Drawing,
        materialize::{
            Endpoints, Obstacles, materialize_corners_direct, materialize_route,
            promote_corners_to_waypoints,
        },
        movement::moved_set_and_delta,
        waypoint_router::{add_route_cost, route_edges_blocked},
    },
};
/// 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>)>;

/// The solve rider (`docs/flag-day-playbook.md`, 12·3): fold what the
/// gesture has written so far onto a scratch prediction, re-solve `path`'s
/// scope 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.
///
/// A gesture that has written nothing has nothing to solve against.
pub(crate) fn solve_rider(
    indexed: &IndexedDocument<'_>,
    path: &BlockPath,
    presentation: &Presentation,
    sink: &mut CommitBuilder,
) {
    let mut scratch = presentation.scratch(indexed);
    let mut discarded = crate::gesture::Gesture::idle();
    let promoted = {
        let mut drawing = Drawing::new(*indexed, path, &mut scratch, &mut discarded);
        drawing.solve_routes(&[])
    };
    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,
        );
    }
}

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

/// 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 supposes 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 supposes 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: a collaborator's commit lands
                // mid-drag, 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 supposes 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)
    }

    /// 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 suppose_drag(
        &mut self,
        _phase: &crate::tools::tool::Supposing,
        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.suppose_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 _ = self.route_update_closed(
            &[],
            GeometryOverrides {
                rects: &overrides,
                pins: &[],
            },
            RoutePass::Preview(PreviewSpec {
                grid_delta,
                inside: &inside,
            }),
        );
    }

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

    /// 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 suppose_pin_drag(
        &mut self,
        _phase: &crate::tools::tool::Supposing,
        pin: PinId,
        side: PinSide,
        offset: u32,
    ) {
        let slots = [PinSlotOverride { pin, side, offset }];
        let inside = move |other: PinId| other == pin;
        let _ = self.route_update_closed(
            &[],
            GeometryOverrides {
                rects: &[],
                pins: &slots,
            },
            RoutePass::Preview(PreviewSpec {
                grid_delta: GridVec::new(0, 0),
                inside: &inside,
            }),
        );
    }

    /// Re-route as if every listed pin were already at its previewed
    /// `(side, slot)` — the group equivalent of
    /// [`suppose_pin_drag`](Self::suppose_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 suppose_pin_drags(&mut self, _phase: &crate::tools::tool::Supposing, moves: &[PinMove]) {
        let slots: Vec<PinSlotOverride> = moves
            .iter()
            .map(|m| PinSlotOverride {
                pin: m.pin,
                side: m.to.side,
                offset: m.to.offset,
            })
            .collect();
        let _ = self.route_update_closed(
            &[],
            GeometryOverrides {
                rects: &[],
                pins: &slots,
            },
            RoutePass::Preview(PreviewSpec {
                grid_delta: GridVec::new(0, 0),
                inside: &|_| false,
            }),
        );
    }

    /// 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.
    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 {
        let mut builder = RouterNGBuilder::default();
        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()
    }

    /// 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 materialization,
    /// 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 — supposed, 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-materialized 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 *supposed* 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<'_>,
    ) -> Promoted {
        let ids = self.scope_route_ids();
        let endpoints: Vec<(RouteId, Pos2, Pos2)> = ids
            .iter()
            .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 supposed 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(),
        };
        let previewed = matches!(pass, RoutePass::Preview(_));
        let obstacles = matches!(pass, RoutePass::Commit).then(|| self.obstacle_rects(hypo.rects));
        // Freeze the geometry up front: seed a full channel at every route
        // endpoint (snapped, as the router will use them) and every waypoint. A
        // route fully inside a group drag previews through offset waypoints, so
        // seed its waypoints at the SAME offset that `reroute_preview_closed` uses.
        let mut seed_points: Vec<Point> = Vec::with_capacity(endpoints.len() * 2);
        for &(_, s, e) in &endpoints {
            seed_points.push(snap_to_grid(s).into());
            seed_points.push(snap_to_grid(e).into());
        }
        for &id in &ids {
            let Some(route) = self.route(id) else {
                continue;
            };
            let offset = match &pass {
                RoutePass::Preview(spec)
                    if (spec.inside)(route.from) && (spec.inside)(route.to) =>
                {
                    Some(spec.grid_delta)
                }
                _ => None,
            };
            let excluded = exclusions.get(&id);
            for (index, wp) in route.waypoints.iter().enumerate() {
                if excluded.is_some_and(|x| x.excluded.contains(&PathOrdinal::new(index))) {
                    continue;
                }
                let pos = wp.pos;
                let pos = match offset {
                    Some(delta) => pos + delta,
                    None => pos,
                };
                seed_points.push(pos.into());
            }
        }
        let mut router = {
            let _s = tracing::info_span!("closed_build", seeds = seed_points.len()).entered();
            self.build_closed_router(hypo, &seed_points)
        };
        // Route in draw order so occupancy accumulates identically to the old
        // path and crossing hops resolve the same way.
        let route_loop = tracing::info_span!("closed_route_loop").entered();
        let (indexed, presentation) = self.split();
        let doc = indexed.doc;
        let mut promoted: Promoted = Vec::new();
        let mut resolved: Vec<RouteId> = Vec::new();
        match pass {
            RoutePass::Commit => {
                let routes = &mut presentation.routes;
                for (id, anchor_start, anchor_end) in endpoints {
                    let Some(route) = doc.route(&id) else {
                        continue;
                    };
                    let geometry = 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()
                    };
                    let unchanged = !pruned
                        && geometry.start_pos() == anchor_start
                        && geometry.end_pos() == anchor_end
                        && !route_edges_blocked(&router, geometry.iter_edges().map(|(_, e)| e))
                        && !ripup.contains(&id);
                    if unchanged {
                        // 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. Cheap and idempotent for
                        // genuinely-unchanged routes.
                        promoted.push((id, promote_corners_to_waypoints(&stored, geometry)));
                        add_route_cost(
                            &mut router,
                            geometry.iter_edges().map(|(_, edge)| edge),
                            WIRE_COST,
                        );
                    } else if let Some(obstacles) = &obstacles {
                        // Keep every straight leg, route only the blocked or
                        // non-colinear ones, and promote the resulting corners to
                        // waypoints. `add_route_cost` is applied inside so later
                        // routes still spread off this one.
                        if let Some(corners) = materialize_route(
                            &stored,
                            geometry,
                            Endpoints {
                                start: grid_point(anchor_start),
                                end: grid_point(anchor_end),
                            },
                            obstacles,
                            Some(&mut router),
                        ) {
                            promoted.push((id, corners));
                        }
                    }
                }
            }
            RoutePass::Preview(spec) => {
                let routes = &mut presentation.routes;
                let no_exclusions = PreviewExclusions::default();
                for (id, anchor_start, anchor_end) in endpoints {
                    let Some(route) = doc.route(&id) else {
                        continue;
                    };
                    let geometry = routes.entry(id).or_default();
                    let exclusion = exclusions.get(&id).unwrap_or(&no_exclusions);
                    let unchanged = !exclusion.pruned
                        && geometry.start_pos() == anchor_start
                        && geometry.end_pos() == anchor_end
                        && !route_edges_blocked(&router, geometry.iter_edges().map(|(_, e)| e))
                        && !ripup.contains(&id);
                    if unchanged {
                        add_route_cost(
                            &mut router,
                            geometry.iter_edges().map(|(_, edge)| edge),
                            WIRE_COST,
                        );
                        continue;
                    }
                    let ends = Endpoints {
                        start: grid_point(anchor_start),
                        end: grid_point(anchor_end),
                    };
                    let stored = route.waypoints.clone();
                    if (spec.inside)(route.from) && (spec.inside)(route.to) {
                        reroute_preview_closed(
                            &stored,
                            geometry,
                            ends,
                            spec.grid_delta,
                            &mut router,
                        );
                    } else {
                        reroute_preview_excluding(
                            &stored,
                            geometry,
                            ends,
                            &exclusion.excluded,
                            &mut router,
                        );
                    }
                    // Drawn somewhere the document does not put it, so the
                    // cull set has to be told; a wire whose geometry still
                    // holds (the `unchanged` skip above) does not.
                    resolved.push(id);
                }
            }
        }
        drop(route_loop);
        {
            let _s = tracing::info_span!("closed_crossings").entered();
            recompute_route_crossings(&ids, &mut self.presentation.routes);
        }
        if previewed {
            self.presentation.routes_supposed();
            self.suppose_routes(resolved);
        }
        promoted
    }

    /// 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 materialization; the interactive mutation
    /// path reuses the same per-leg policy.
    pub fn materialize_routes(&mut self) {
        let ids = self.scope_route_ids();
        let endpoints: Vec<(RouteId, GridPoint, GridPoint)> = 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 = 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, GridPoint, GridPoint)> = Vec::new();
        {
            let (indexed, presentation) = self.split();
            let doc = indexed.doc;
            let routes = &mut presentation.routes;
            for &(id, s, e) in &endpoints {
                let Some(route) = doc.route(&id) else {
                    continue;
                };
                let geometry = routes.entry(id).or_default();
                let ends = Endpoints { start: s, end: e };
                if materialize_route(&route.waypoints, geometry, ends, &obstacles, None).is_none() {
                    deferred.push((id, s, e));
                }
            }
        }

        // Phase 2: only if something needs routing, build the graph once, seed the
        // straight routes' occupancy, then route the deferred legs against it.
        if !deferred.is_empty() {
            let deferred_ids: HashSet<RouteId> = deferred.iter().map(|&(id, ..)| id).collect();
            let mut router = {
                let mut seeds: Vec<Point> = Vec::new();
                for &(_, s, e) in &endpoints {
                    seeds.push(snap_to_grid(px_point(s)).into());
                    seeds.push(snap_to_grid(px_point(e)).into());
                }
                for &id in &ids {
                    let Some(route) = self.route(id) else {
                        continue;
                    };
                    for wp in route.waypoints.clone() {
                        seeds.push(wp.pos.into());
                    }
                }
                let mut router = self.build_closed_router(GeometryOverrides::default(), &seeds);
                for &id in &ids {
                    if !deferred_ids.contains(&id)
                        && let Some(geometry) = self.presentation.routes.get(&id)
                    {
                        add_route_cost(
                            &mut router,
                            geometry.iter_edges().map(|(_, e)| e),
                            WIRE_COST,
                        );
                    }
                }
                router
            };
            let (indexed, presentation) = self.split();
            let doc = indexed.doc;
            let routes = &mut presentation.routes;
            for (id, s, e) in deferred {
                let Some(route) = doc.route(&id) else {
                    continue;
                };
                let geometry = routes.entry(id).or_default();
                let ends = Endpoints { start: s, end: e };
                materialize_route(
                    &route.waypoints,
                    geometry,
                    ends,
                    &obstacles,
                    Some(&mut router),
                );
            }
        }

        recompute_route_crossings(&ids, &mut self.presentation.routes);
    }

    /// 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 ids = self.scope_route_ids();
        let geometry = self.presentation.routes.entry(id).or_default();
        materialize_corners_direct(corners, geometry, ends);
        let relayed = reanchored(geometry, anchors);
        let promoted = promote_corners_to_waypoints(stored, geometry);
        recompute_route_crossings(&ids, &mut self.presentation.routes);
        // 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 supposition back.
        self.presentation.routes_supposed();
        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::tools::tool::Supposing,
        id: RouteId,
        session: &RouteEditSession,
        cursors: &[Pos2],
    ) {
        let Some(ends) = self.route_ends(id) else {
            return;
        };
        let ids = self.scope_route_ids();
        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();
        materialize_corners_direct(&corners, geometry, ends);
        recompute_route_crossings(&ids, routes);
        self.presentation.routes_supposed();
    }

    /// 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);
        }
        self.presentation.routes_supposed();
    }

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

    pub fn debug_marks(&self) -> Vec<Mark> {
        self.scratch_closed_router(&[]).debug_marks()
    }
}

#[cfg(test)]
mod tests {
    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 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::materialize(&mut scene);
        let route = route_id(5);
        let drawing = scene.drawing();
        let geometry = drawing
            .route_geometry(route)
            .expect("the fixture's wire is materialized")
            .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:?}",
        );
    }

    /// 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.suppose_drag(
            &crate::tools::tool::Supposing::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 materialized");
            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 materialized 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.suppose_drag(
            &crate::tools::tool::Supposing::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.suppose_drag(
            &crate::tools::tool::Supposing::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::materialize(&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.suppose_drag(
                &crate::tools::tool::Supposing::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 materialized.
        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 materialized");
        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"
        );
    }

    #[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 materialized");
        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().suppose_drag(
                &crate::tools::tool::Supposing::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 materialized");
        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"
        );
    }

    #[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 *suppose* 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.suppose_drag(
                    &crate::tools::tool::Supposing::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.suppose_resize(
                &crate::tools::tool::Supposing::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, supposed) = {
            let mut drawing = scene.drawing();
            let start0 = drawing.route_geometry(rid).unwrap().start_pos();
            drawing.suppose_pin_drag(
                &crate::tools::tool::Supposing::testing(),
                pa,
                PinSide::East,
                3,
            );
            let start = drawing.route_geometry(rid).unwrap().start_pos();
            let supposed = 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, supposed)
        };

        assert_ne!(start, start0, "precondition: slot 3 moves the anchor");
        assert_eq!(
            grid_point(start),
            grid_point(supposed),
            "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.suppose_pin_drags(
                &crate::tools::tool::Supposing::testing(),
                &[PinMove {
                    pin: pa,
                    to: PinSlot {
                        side: PinSide::East,
                        offset: 2,
                    },
                }],
            );
        }
        assert_eq!(scene.doc.stamp(), stamp);
        assert_eq!(scene.doc.clone(), before);
    }
}