blockworx_editor/widget/

foreground.rs

//! The foreground: the geometry one gesture may write.
//!
//! Selection raises. What the user has selected — and everything whose wires
//! that selection can disturb — is the *foreground*; everything else is the
//! *background*, whose routing lattice can then be built once and cached
//! across the whole gesture rather than rebuilt per mutation
//! (`docs/foreground-router-playbook.md`).
//!
//! The set is derived from the selection rather than declared, so a caller
//! cannot forget a wire — and it is deliberately a *superset* of what the
//! gesture will actually touch, because the cache's whole claim rests on
//! nothing being written outside it.

use std::collections::BTreeSet;

use blockworx_doc::{id::EntityRef, opcode::OpCodes};
use blockworx_geom::Rect;
use blockworx_router::block::MOAT_REACH;

use blockworx_doc::id::RouteId;

use crate::{
    shape::ShapeId,
    widget::{drawing::Drawing, routing::obstacle_rect},
};

/// What a gesture may write, raised out of the background.
///
/// The invariant the background cache depends on:
///
/// > **The foreground is a superset of everything the gesture can write.**
///
/// If it holds, the background survives the gesture. If it does not, the
/// gesture invalidates its own cache partway through — correct, but with the
/// saving lost, which is why [`Self::escapees`] exists to prove it in tests.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct Foreground {
    shapes: BTreeSet<ShapeId>,
    routes: BTreeSet<RouteId>,
}

impl Foreground {
    /// Raise `shapes` and everything their movement can disturb: the wires
    /// anchored to them, and the wires their current footprints already block
    /// or hug. A gesture that *moves* a shape adds its destination with
    /// [`Self::also_disturbed_by`] — the footprint it is heading for disturbs
    /// wires the one it is leaving never touched.
    pub fn raising(shapes: impl IntoIterator<Item = ShapeId>, drawing: &Drawing<'_>) -> Self {
        Self::derive(shapes.into_iter().collect(), BTreeSet::new(), drawing)
    }

    /// What a gesture's own ops touched, raised. Where [`Self::raising`] asks
    /// what the user *selected*, this asks what the gesture actually *wrote* —
    /// a subset, and the one the solve is scoped to, so that what a pass may
    /// re-solve is derived from the same ops it is riding on.
    pub fn written(ops: &[OpCodes], drawing: &Drawing<'_>) -> Self {
        let mut shapes = BTreeSet::new();
        let mut routes = BTreeSet::new();
        for target in ops.iter().map(OpCodes::target) {
            match target {
                EntityRef::Block(id) => {
                    shapes.insert(ShapeId::Rect(id));
                }
                EntityRef::Pin(id) => {
                    shapes.extend(drawing.pin_shape(id));
                }
                EntityRef::Route(id) => {
                    routes.insert(id);
                }
                EntityRef::RouteLabel(_)
                | EntityRef::Text(_)
                | EntityRef::Area(_)
                | EntityRef::Image(_)
                | EntityRef::Document
                | EntityRef::Asset(_) => {}
            }
        }
        Self::derive(shapes, routes, drawing)
    }

    #[tracing::instrument(name = "foreground", level = "info", skip_all)]
    fn derive(shapes: BTreeSet<ShapeId>, routes: BTreeSet<RouteId>, drawing: &Drawing<'_>) -> Self {
        let mut raised = Self { shapes, routes };
        let anchored: Vec<RouteId> = drawing
            .scope_route_ids()
            .into_iter()
            .filter(|&id| raised.anchored_to_a_raised_shape(id, drawing))
            .collect();
        raised.routes.extend(anchored);
        for rect in raised.footprints(drawing) {
            raised.raise_wires_crossing(rect, drawing);
        }
        raised
    }

    /// Also raise the wires `rect` blocks or hugs — the footprint a move is
    /// heading for, which is not in the document yet and so cannot be derived
    /// from it.
    pub fn also_disturbed_by(&mut self, rect: Rect, drawing: &Drawing<'_>) {
        self.raise_wires_crossing(rect, drawing);
    }

    /// Is this wire in the foreground — may this pass re-solve it?
    #[must_use]
    pub fn holds_route(&self, id: RouteId) -> bool {
        self.routes.contains(&id)
    }

    /// Is `entity` in the foreground?
    #[must_use]
    pub fn holds(&self, entity: EntityRef, drawing: &Drawing<'_>) -> bool {
        match entity {
            EntityRef::Block(id) => self.shapes.contains(&ShapeId::Rect(id)),
            EntityRef::Route(id) => self.routes.contains(&id),
            EntityRef::Pin(id) => drawing
                .pin_shape(id)
                .is_some_and(|shape| self.shapes.contains(&shape)),
            EntityRef::RouteLabel(id) => drawing
                .indexed()
                .doc
                .route_label(&id)
                .is_some_and(|label| self.routes.contains(&label.owner)),
            EntityRef::Text(id) => self.shapes.contains(&ShapeId::Text(id)),
            EntityRef::Area(id) => self.shapes.contains(&ShapeId::Area(id)),
            EntityRef::Image(id) => self.shapes.contains(&ShapeId::Image(id)),
            EntityRef::Document | EntityRef::Asset(_) => false,
        }
    }

    /// The ops in `commit` that write routing geometry this foreground does
    /// not hold — each one a reason the background cache would have to be
    /// dropped. Empty is the invariant holding.
    ///
    /// Deliberately conservative about *which* ops count: any op on a block,
    /// pin or route is treated as moving the lattice, though a rename plainly
    /// does not. A cheap over-report costs a rebuild; an under-report would
    /// solve against occupancy that has silently moved.
    pub fn escapees<'a>(
        &'a self,
        ops: &'a [OpCodes],
        drawing: &'a Drawing<'_>,
    ) -> impl Iterator<Item = EntityRef> + 'a {
        ops.iter()
            .map(OpCodes::target)
            .filter(|&target| moves_the_lattice(target) && !self.holds(target, drawing))
    }

    /// The rectangle this foreground occupies: every shape it raised and every
    /// wire, grown by the moat a block shapes its channels within.
    ///
    /// What a commit *disturbed*, in other words — which is what the
    /// reconstruction after it needs, since a wire outside this rectangle is
    /// drawn from geometry nothing moved near.
    #[must_use]
    pub fn extent(&self, drawing: &Drawing<'_>) -> Rect {
        let margin = crate::grid::GRID_SIZE * MOAT_REACH as f32;
        let mut extent: Option<Rect> = None;
        let mut widen = |rect: Rect| {
            extent = Some(extent.map_or(rect, |so_far: Rect| so_far.union(rect)));
        };
        for id in self.shapes() {
            if let Some(shape) = drawing.shape(id) {
                widen(shape.gui_rect());
            }
        }
        for id in self.routes() {
            if let Some(geometry) = drawing.route_geometry(id) {
                widen(Rect::from_min_max(
                    geometry.start_pos().min(geometry.end_pos()),
                    geometry.start_pos().max(geometry.end_pos()),
                ));
                for (_, edge) in geometry.iter_edges() {
                    let (a, b) = (
                        crate::grid::px_point(edge.start),
                        crate::grid::px_point(edge.end),
                    );
                    widen(Rect::from_min_max(a.min(b), a.max(b)));
                }
            }
        }
        extent.unwrap_or(Rect::ZERO).expand(margin)
    }

    /// The shapes raised, for the caller building the background without them.
    pub fn shapes(&self) -> impl Iterator<Item = ShapeId> + '_ {
        self.shapes.iter().copied()
    }

    /// The wires raised, for the same reason.
    pub fn routes(&self) -> impl Iterator<Item = RouteId> + '_ {
        self.routes.iter().copied()
    }

    fn anchored_to_a_raised_shape(&self, id: RouteId, drawing: &Drawing<'_>) -> bool {
        let Some(route) = drawing.route(id) else {
            return false;
        };
        [route.from, route.to]
            .into_iter()
            .filter_map(|pin| drawing.pin_shape(pin))
            .any(|shape| self.shapes.contains(&shape))
    }

    fn footprints(&self, drawing: &Drawing<'_>) -> Vec<Rect> {
        self.shapes
            .iter()
            .filter_map(|&id| Some(drawing.shape(id)?.gui_rect()))
            .collect()
    }

    /// Every wire `rect` reaches: the ones it crosses, and the ones running
    /// within its moat.
    ///
    /// The moat rather than the route gutter, because a block does not only
    /// obstruct wires — it *shapes the channels* around itself, trimming those
    /// it spans and seeding five lanes of its own out to [`MOAT_REACH`]. A wire
    /// running in one of those channels is drawn where it is *because* of this
    /// block, so moving the block can change it even though the wire never
    /// touches it.
    fn raise_wires_crossing(&mut self, rect: Rect, drawing: &Drawing<'_>) {
        let obstacle = obstacle_rect(rect);
        let crossed: Vec<RouteId> = drawing
            .scope_route_ids()
            .into_iter()
            .filter(|id| !self.routes.contains(id))
            .filter(|&id| {
                drawing.route_geometry(id).is_some_and(|geometry| {
                    geometry.iter_edges().any(|(_, edge)| {
                        obstacle.intersects_edge(edge.start, edge.end)
                            || obstacle.hugs_wire(edge.start, edge.end, MOAT_REACH)
                    })
                })
            })
            .collect();
        self.routes.extend(crossed);
    }
}

/// Whether an op on this entity can move the routing lattice. Texts, areas and
/// images are not routing obstacles — `routing_shapes` is the blocks layer and
/// the ports layer — so no edit to one can change where a wire runs.
fn moves_the_lattice(target: EntityRef) -> bool {
    matches!(
        target,
        EntityRef::Block(_) | EntityRef::Pin(_) | EntityRef::Route(_)
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::grid::GRID_SIZE;
    use crate::grid::px_point;
    use crate::path::Scope;
    use crate::widget::test_fixtures::{
        Scene, block_in, cells, pin, reconstruct, route, scale_scene,
    };
    use blockworx_doc::id::BlockId;
    use blockworx_doc::values::PinSide;
    use blockworx_geom::Rect;
    use blockworx_geom::vec2;

    /// The nth block the scene created, by creation order — the hand-built
    /// scenes above name their blocks by the number they passed.
    fn block_id_of(scene: &mut Scene, n: usize) -> BlockId {
        scene.drawing().child_blocks()[n - 1].0
    }

    /// The scale fixture titles its blocks `block_<row>_<col>`, which is how a
    /// test names one without reaching into the generator's private tables.
    fn block_titled(scene: &mut Scene, title: &str) -> BlockId {
        scene
            .drawing()
            .child_blocks()
            .into_iter()
            .find(|(_, block)| block.title.name == title)
            .map_or_else(|| panic!("no block titled {title}"), |(id, _)| id)
    }

    /// The wires the *document* says land on `block` — read through pin
    /// ownership rather than through `pin_shape`, so the expectation does not
    /// come from the same place the implementation does.
    fn wires_landing_on(scene: &mut Scene, block: BlockId) -> Vec<RouteId> {
        let drawing = scene.drawing();
        let doc = drawing.indexed().doc;
        drawing
            .scope_route_ids()
            .into_iter()
            .filter(|&id| {
                drawing.route(id).is_some_and(|route| {
                    [route.from, route.to]
                        .iter()
                        .filter_map(|p| doc.pin(p))
                        .any(|pin| pin.owner == block)
                })
            })
            .collect()
    }

    /// Every wire anchored to a raised block comes up with it.
    #[test]
    fn raising_a_block_raises_the_wires_anchored_to_it() {
        let mut scene = scale_scene(3);
        let block = block_titled(&mut scene, "block_1_1");
        let anchored = wires_landing_on(&mut scene, block);
        assert!(
            !anchored.is_empty(),
            "the fixture wires nothing to this block; the test would prove nothing"
        );

        let raised = Foreground::raising([ShapeId::Rect(block)], &scene.drawing());
        let raised_routes: Vec<RouteId> = raised.routes().collect();
        for id in anchored {
            assert!(raised_routes.contains(&id), "{id:?} was left behind");
        }
    }

    /// And it is a *subset*: raising one block of nine must not raise every
    /// wire. Without this the superset test below could pass trivially.
    #[test]
    fn raising_a_block_leaves_the_rest_in_the_background() {
        let mut scene = scale_scene(3);
        let block = block_titled(&mut scene, "block_1_1");
        let all = scene.drawing().scope_route_ids().len();
        assert!(all > 0, "no wires to leave behind");

        let raised = Foreground::raising([ShapeId::Rect(block)], &scene.drawing());
        assert!(
            raised.routes().count() < all,
            "raised all {all} wires — nothing was left in the background"
        );
    }

    /// A block with no pins, moved onto a wire it has nothing to do with,
    /// must raise that wire — it is the bystander case, and the only reason
    /// the footprint clause takes the destination as well as the origin.
    #[test]
    fn a_destination_raises_a_wire_the_mover_has_nothing_to_do_with() {
        let mut scene = Scene::new(vec![
            block_in(1, Scope::Root, cells(0, 0, 4, 4)),
            block_in(2, Scope::Root, cells(24, 0, 4, 4)),
            pin(1, 1, PinSide::East, 0),
            pin(2, 2, PinSide::West, 0),
            route(1, Scope::Root, 1, 2, &[]),
            // The bystander: no pins, nowhere near the wire.
            block_in(3, Scope::Root, cells(10, 20, 4, 4)),
        ]);
        reconstruct(&mut scene);

        let wire = scene.drawing().scope_route_ids()[0];
        let over_the_wire = {
            let drawing = scene.drawing();
            let geometry = drawing.route_geometry(wire).expect("the wire is solved");
            let (_, edge) = geometry.iter_edges().next().expect("the wire has an edge");
            let mid = px_point(edge.start).lerp(px_point(edge.end), 0.5);
            Rect::from_center_size(mid, vec2(4.0 * GRID_SIZE, 4.0 * GRID_SIZE))
        };

        let mut raised = Foreground::raising(
            [ShapeId::Rect(block_id_of(&mut scene, 3))],
            &scene.drawing(),
        );
        assert!(
            raised.routes().next().is_none(),
            "the bystander already holds the wire at its home; the test would prove nothing"
        );

        raised.also_disturbed_by(over_the_wire, &scene.drawing());
        assert!(
            raised.routes().any(|id| id == wire),
            "moving onto the wire did not raise it"
        );
    }

    /// **The superset rule**, proved through the real gesture path: every op a
    /// move seals — the rider's promotions included — targets geometry the
    /// foreground already held. It is what lets a background router be built
    /// once and survive the gesture.
    ///
    /// This test was first written inverted, asserting the escapees were *not*
    /// empty: with the rider re-solving the whole scope, moving one block one
    /// cell rewrote 20 of this sheet's 30 wires.
    #[test]
    fn a_move_writes_nothing_outside_the_foreground() {
        let mut scene = scale_scene(3);
        let block = block_titled(&mut scene, "block_1_1");
        let delta = vec2(GRID_SIZE, 0.0);

        let mut raised = Foreground::raising([ShapeId::Rect(block)], &scene.drawing());
        let heading_for = scene
            .drawing()
            .shape(ShapeId::Rect(block))
            .expect("the block")
            .gui_rect()
            .translate(delta);
        raised.also_disturbed_by(heading_for, &scene.drawing());

        scene.commit(|drawing| drawing.move_shape(ShapeId::Rect(block), delta));
        assert!(
            !scene.committed().is_empty(),
            "the move sealed nothing; the test would prove nothing"
        );

        let committed = scene.committed().to_vec();
        let drawing = scene.drawing();
        let escaped: Vec<EntityRef> = raised.escapees(&committed, &drawing).collect();
        assert!(
            escaped.is_empty(),
            "wrote outside the foreground: {escaped:?}"
        );
    }

    /// And the churn is gone with it: a one-cell move rewrites a handful of
    /// wires, not most of the sheet.
    #[test]
    fn a_one_cell_move_rewrites_only_the_wires_it_disturbs() {
        let mut scene = scale_scene(3);
        let block = block_titled(&mut scene, "block_1_1");
        let all = scene.drawing().scope_route_ids().len();

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

        let rewritten = scene
            .committed()
            .iter()
            .filter(|op| matches!(op.target(), EntityRef::Route(_)))
            .count();
        assert!(
            rewritten * 2 < all,
            "rewrote {rewritten} of {all} wires — the solve is not scoped"
        );
    }
}