blockworx_editor/edit/

geometry.rs

//! The geometry family: the emitters
//! that move, resize, and re-slot what already exists, plus the route
//! lists those gestures carry. The gesture solved its own constraints —
//! magnetism, minimum sizes, the re-routed polyline — and hands the result
//! in; the list arithmetic over the indexed document is the emitter's own.
//!
//! A keyboard nudge has no emitter of its own: a one-cell arrow delta is
//! [`move_shape`] / [`move_group`] and a one-slot pin delta is
//! [`nudge_pins`].

use ahash::{HashSet, HashSetExt};
use blockworx_doc::{
    block_model::{
        AreaUpdate, Block, BlockUpdate, Icon, ImageUpdate, Pin, PinUpdate, RouteLabelUpdate,
        RouteUpdate, TextUpdate,
    },
    commit::CommitBuilder,
    document::{Document, IndexedDocument},
    geometry::{FracVal, GridPoint, GridRect, GridSize, GridVec, PinSlot, Waypoint},
    hash::AssetHash,
    id::{AreaId, BlockId, ImageId, PinId, RouteId, RouteLabelId, TextId},
    opcode::{Crud, OpCodes},
};
use blockworx_geom::{Rect, Vec2};

use crate::edit::create::PathOrdinal;
use crate::edit::lower::slot_capacity;
use crate::grid::{
    artwork_rect, grid_point, grid_rect, grid_u32, grid_vec, px_rect, px_u, px_vec, screen_rect,
};
use crate::shape::block::{contain_rect, icon_rect_after_resize, resize_pin_shift};
use crate::shape::port::PORT_HEIGHT;

/// What a drag grabbed. An icon is named by the block that owns it, as it
/// has no id of its own.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub enum Shape {
    Block(BlockId),
    Port(PinId),
    Text(TextId),
    Area(AreaId),
    Image(ImageId),
    Icon(BlockId),
}

/// The widget layer's [`ShapeId`](crate::shape::ShapeId) is the same six
/// variants over the same ids — one enum in two modules until the shape
/// layer can name this one directly. Encoded here so preview and commit
/// cannot disagree about which shape a gesture grabbed.
impl From<crate::shape::ShapeId> for Shape {
    fn from(id: crate::shape::ShapeId) -> Self {
        use crate::shape::ShapeId;
        match id {
            ShapeId::Rect(id) => Shape::Block(id),
            ShapeId::Port(id) => Shape::Port(id),
            ShapeId::Text(id) => Shape::Text(id),
            ShapeId::Area(id) => Shape::Area(id),
            ShapeId::Image(id) => Shape::Image(id),
            ShapeId::Icon(id) => Shape::Icon(id),
        }
    }
}

impl Shape {
    /// Whether moving this shape can change routing. Only blocks
    /// (obstacles) and ports (endpoints) are in the routing graph;
    /// annotations neither reroute nor block a neighbour's move.
    fn affects_routing(self) -> bool {
        matches!(self, Shape::Block(_) | Shape::Port(_))
    }
}

/// The scope a routing shape occupies with its rect: a block sits in its
/// parent's interior, a port body in its owner's. Rects only compare
/// within one scope — two scopes are two coordinate spaces.
pub fn placement(doc: &Document, shape: Shape) -> Option<(BlockId, GridRect)> {
    match shape {
        Shape::Block(id) => {
            let block = doc.block(&id)?;
            Some((block.parent, block.rect))
        }
        Shape::Port(id) => {
            let pin = doc.pin(&id)?;
            Some((pin.owner, pin.rect))
        }
        Shape::Text(_) | Shape::Area(_) | Shape::Image(_) | Shape::Icon(_) => None,
    }
}

/// Every routing shape drawn in `scope`, with its rect — the obstacle set
/// a move is tested against. The document root is a scope like any other,
/// holding top-level blocks and no ports.
fn scope_shapes<'a>(
    indexed: &'a IndexedDocument<'a>,
    scope: BlockId,
) -> impl Iterator<Item = (Shape, GridRect)> + 'a {
    let entry = indexed.index.scope(scope);
    let children = entry
        .into_iter()
        .flat_map(|entry| entry.children.iter())
        .filter_map(|&id| Some((Shape::Block(id), indexed.doc.block(&id)?.rect)));
    let ports = entry
        .into_iter()
        .flat_map(|entry| entry.pins.iter())
        .filter_map(|&id| Some((Shape::Port(id), indexed.doc.pin(&id)?.rect)));
    children.chain(ports)
}

/// Which rule a move is judged by — the gesture, not the count: a group of
/// one is still a group, and is still exempt from the overlap it already had.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Moving {
    /// One shape dragged on its own: any overlap at the destination refuses
    /// it, even one it already had.
    Alone,
    /// A selection moved together: only an overlap the move *creates*
    /// refuses it, so a freshly pasted group sitting on its neighbour can
    /// still be nudged, and the group keeps its own layout.
    AsAGroup,
}

/// Whether moving `shapes` by `delta` would be refused.
///
/// The one resolver, so a drag's preview and the commit it previews cannot
/// come to different answers: a refusal the preview did not show is a
/// gesture that undoes itself on release, in silence.
pub fn move_refused(
    indexed: &IndexedDocument<'_>,
    shapes: &[Shape],
    delta: Vec2,
    moving: Moving,
) -> bool {
    !move_conflicts(indexed, shapes, delta, moving).is_empty()
}

/// The cells a move would have to share with something the router routes
/// around — every overlap that refuses it, not merely that one does.
///
/// Only the overlaps that *refuse* the move: on a group move an overlap the
/// selection already had refuses nothing, and returning it would have the
/// drawing claim a refusal that is not happening.
pub fn move_conflicts(
    indexed: &IndexedDocument<'_>,
    shapes: &[Shape],
    delta: Vec2,
    moving: Moving,
) -> Vec<GridRect> {
    let grid = grid_vec(delta);
    match (moving, shapes) {
        (_, []) => Vec::new(),
        (Moving::Alone, [one]) => {
            placement(indexed.doc, *one).map_or_else(Vec::new, |(scope, rect)| {
                let dst = rect.translate(grid);
                scope_shapes(indexed, scope)
                    .filter(|&(other, _)| other != *one)
                    .filter_map(|(_, obstacle)| dst.intersection(obstacle))
                    .collect()
            })
        }
        // A lone drag carries one shape; anything else is the group gesture,
        // whatever it holds.
        (Moving::Alone | Moving::AsAGroup, _) => {
            let set: HashSet<Shape> = shapes.iter().copied().collect();
            let moved: Vec<(BlockId, GridRect, GridRect)> = shapes
                .iter()
                .filter(|shape| shape.affects_routing())
                .filter_map(|&shape| placement(indexed.doc, shape))
                .map(|(scope, src)| (scope, src, src.translate(grid)))
                .collect();
            let scopes: HashSet<BlockId> = moved.iter().map(|&(scope, ..)| scope).collect();
            let mut conflicts = Vec::new();
            for scope in scopes {
                let obstacles: Vec<GridRect> = scope_shapes(indexed, scope)
                    .filter(|(other, _)| !set.contains(other))
                    .map(|(_, obstacle)| obstacle)
                    .collect();
                for obstacle in obstacles {
                    // `member_scope == scope` as the group rule has it: a
                    // member of another scope is not an obstacle's neighbour.
                    conflicts.extend(
                        moved
                            .iter()
                            .filter(|&&(member_scope, ..)| member_scope == scope)
                            .filter(|&&(_, src, _)| !src.intersects(obstacle))
                            .filter_map(|&(_, _, dst)| dst.intersection(obstacle)),
                    );
                }
            }
            conflicts
        }
    }
}

/// The single-shape rule: a destination overlapping any other routing shape
/// rejects the move, even one the shape already overlapped.
pub fn move_blocked(
    indexed: &IndexedDocument<'_>,
    moving: Shape,
    scope: BlockId,
    dst: GridRect,
) -> bool {
    scope_shapes(indexed, scope).any(|(other, rect)| other != moving && dst.intersects(rect))
}

/// The group rule: only a *new* overlap rejects, so a selection already
/// sitting on its neighbour (a fresh paste) can still be nudged. Intra-group
/// overlaps are ignored — the group keeps its layout.
pub fn group_move_blocked(
    indexed: &IndexedDocument<'_>,
    members: &HashSet<Shape>,
    moved: &[(BlockId, GridRect, GridRect)],
) -> bool {
    let scopes: HashSet<BlockId> = moved.iter().map(|&(scope, ..)| scope).collect();
    scopes.into_iter().any(|scope| {
        scope_shapes(indexed, scope)
            .filter(|(other, _)| !members.contains(other))
            .any(|(_, obstacle)| {
                moved.iter().any(|&(member_scope, src, dst)| {
                    member_scope == scope && dst.intersects(obstacle) && !src.intersects(obstacle)
                })
            })
    })
}

/// The artwork an icon value holds, or `None` for the zero icon — the
/// null asset is the "no image" zero, so an empty box must never be
/// written as if it were artwork.
pub(crate) fn artwork(icon: &Icon) -> Option<&Icon> {
    (icon.asset != AssetHash::default()).then_some(icon)
}

/// Artwork carried by a translation of `delta` world px.
pub(crate) fn shifted_icon(icon: &Icon, delta: Vec2) -> Icon {
    Icon {
        rect: screen_rect(artwork_rect(icon.rect).translate(delta)),
        ..icon.clone()
    }
}

fn icon_of(block: &Block) -> Option<&Icon> {
    artwork(&block.icon)
}

/// The block's icon carried by a translation of `delta` world px.
fn carried_icon(block: &Block, delta: Vec2) -> Option<Icon> {
    Some(shifted_icon(icon_of(block)?, delta))
}

/// A block's icon after a free-pixel drag of its own: shifted, then held
/// inside the block.
fn contained_icon(block: &Block, delta: Vec2) -> Option<Icon> {
    let moved = carried_icon(block, delta)?;
    Some(Icon {
        rect: screen_rect(contain_rect(artwork_rect(moved.rect), px_rect(block.rect))),
        ..moved
    })
}

fn push_icon(block_id: BlockId, block: &Block, icon: Option<Icon>, builder: &mut CommitBuilder) {
    let Some(icon) = icon.filter(|icon| *icon != block.icon) else {
        return;
    };
    builder.push(OpCodes::Block(
        block_id,
        Crud::Update(BlockUpdate::Icon(icon)),
    ));
}

/// The per-kind translation every move shares, collision already decided.
/// `grid` is the snapped cell delta and `px` its world-space twin, so the
/// block body and the icon riding it cannot disagree.
fn translate(doc: &Document, shape: Shape, delta: (GridVec, Vec2), builder: &mut CommitBuilder) {
    let (grid, px) = delta;
    match shape {
        Shape::Block(id) => {
            let Some(block) = doc.block(&id) else {
                return;
            };
            let rect = block.rect;
            if grid != GridVec::ZERO {
                builder.push(OpCodes::Block(
                    id,
                    Crud::Update(BlockUpdate::Rect(rect.translate(grid))),
                ));
            }
            push_icon(id, block, carried_icon(block, px), builder);
        }
        Shape::Port(id) => {
            let Some(pin) = doc.pin(&id) else {
                return;
            };
            if grid != GridVec::ZERO {
                builder.push(OpCodes::Pin(
                    id,
                    Crud::Update(PinUpdate::Rect(pin.rect.translate(grid))),
                ));
            }
        }
        Shape::Text(id) => {
            let Some(live) = doc.text(&id) else {
                return;
            };
            if grid != GridVec::ZERO {
                builder.push(OpCodes::Text(
                    id,
                    Crud::Update(TextUpdate::Pos(live.pos + grid)),
                ));
            }
        }
        Shape::Area(id) => {
            let Some(live) = doc.area(&id) else {
                return;
            };
            if grid != GridVec::ZERO {
                builder.push(OpCodes::Area(
                    id,
                    Crud::Update(AreaUpdate::Rect(live.rect.translate(grid))),
                ));
            }
        }
        Shape::Image(id) => {
            let Some(live) = doc.image(&id) else {
                return;
            };
            let rect = screen_rect(artwork_rect(live.rect).translate(px));
            if rect != live.rect {
                builder.push(OpCodes::Image(id, Crud::Update(ImageUpdate::Rect(rect))));
            }
        }
        Shape::Icon(id) => {
            let Some(block) = doc.block(&id) else {
                return;
            };
            push_icon(id, block, contained_icon(block, px), builder);
        }
    }
}

/// Inventory row "Move Shape": drag one shape to a new position. Blocks,
/// ports, text, and areas commit on the grid; artwork — a free-floating
/// image or a block's icon — moves in free pixels, and an icon is held
/// inside the block it belongs to.
pub fn move_shape(
    indexed: &IndexedDocument<'_>,
    shape: Shape,
    delta: Vec2,
    builder: &mut CommitBuilder,
) {
    let grid = grid_vec(delta);
    if move_refused(indexed, &[shape], delta, Moving::Alone) {
        return;
    }
    // Artwork never snaps on a single drag (the inventory's single-move
    // exception); every other kind rides the snapped delta.
    let px = match shape {
        Shape::Image(_) | Shape::Icon(_) => delta,
        Shape::Block(_) | Shape::Port(_) | Shape::Text(_) | Shape::Area(_) => px_vec(grid),
    };
    translate(indexed.doc, shape, (grid, px), builder);
}

/// Inventory row "Move Group": one shared snapped delta across a marquee
/// selection — images included, unlike a single move — with the wires the
/// selection touches kept coherent.
pub fn move_group(
    indexed: &IndexedDocument<'_>,
    members: &[Shape],
    delta: Vec2,
    builder: &mut CommitBuilder,
) {
    let grid = grid_vec(delta);
    if move_refused(indexed, members, delta, Moving::AsAGroup) {
        return;
    }
    let set: HashSet<Shape> = members.iter().copied().collect();
    let moved: Vec<(BlockId, GridRect, GridRect)> = members
        .iter()
        .filter(|shape| shape.affects_routing())
        .filter_map(|&shape| placement(indexed.doc, shape))
        .map(|(scope, src)| (scope, src, src.translate(grid)))
        .collect();
    // The wires a move reconciles are the ones drawn *where it happened*. A
    // block's own pins are its boundary ports, which are endpoints at two
    // levels at once — its interior wires anchor to the same ids — and the
    // interior did not move, so it must not be reconciled.
    let scopes: HashSet<BlockId> = moved.iter().map(|&(scope, ..)| scope).collect();
    for &shape in members {
        // An icon travels with its block, so one that is co-selected with
        // its own block has already moved — shifting it again would double
        // the delta.
        if matches!(shape, Shape::Icon(id) if set.contains(&Shape::Block(id))) {
            continue;
        }
        translate(indexed.doc, shape, (grid, px_vec(grid)), builder);
    }
    push_route_riders(
        indexed,
        &riding_pins(indexed, members),
        &scopes,
        grid,
        builder,
    );
}

/// The pins that ride a move: a moved block carries its whole boundary,
/// and a moved port is one pin of its own.
fn riding_pins(indexed: &IndexedDocument<'_>, members: &[Shape]) -> HashSet<PinId> {
    let mut pins = HashSet::new();
    for &shape in members {
        match shape {
            Shape::Block(id) => {
                if let Some(entry) = indexed.index.blocks.get(&id) {
                    pins.extend(entry.pins.iter().copied());
                }
            }
            Shape::Port(id) => {
                if indexed.doc.pin(&id).is_some() {
                    pins.insert(id);
                }
            }
            Shape::Text(_) | Shape::Area(_) | Shape::Image(_) | Shape::Icon(_) => {}
        }
    }
    pins
}

/// Which end of a wire rode the move — the side whose approach corners
/// went stale.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum RouteEnd {
    From,
    To,
}

/// Port of `AutoRoute::approach_waypoint_ids` (`src/document/auto_route.rs:
/// 162`): the polyline minus up to two unlocked corners nearest the moved
/// end, stopping at the first locked one so a hand-placed bend survives.
pub fn trimmed_approach(waypoints: &[Waypoint], end: RouteEnd) -> Vec<Waypoint> {
    fn doomed<'a>(corners: impl Iterator<Item = &'a Waypoint>) -> usize {
        const APPROACH: usize = 2;
        corners.take(APPROACH).take_while(|wp| !wp.locked).count()
    }
    match end {
        RouteEnd::From => waypoints[doomed(waypoints.iter())..].to_vec(),
        RouteEnd::To => waypoints[..waypoints.len() - doomed(waypoints.iter().rev())].to_vec(),
    }
}

/// The corners [`trimmed_approach`] drops, by path ordinal — the same rule
/// read from the preview's side, which routes *around* them instead of
/// removing them. A trim is a prefix or a suffix, so the surviving count
/// names the dropped set exactly.
pub fn trimmed_ordinals(waypoints: &[Waypoint], end: RouteEnd) -> Vec<PathOrdinal> {
    let kept = trimmed_approach(waypoints, end).len();
    let range = match end {
        RouteEnd::From => 0..waypoints.len() - kept,
        RouteEnd::To => kept..waypoints.len(),
    };
    range.map(PathOrdinal::new).collect()
}

/// Whether the wire reverses direction at `cur`: the `prev → cur` and
/// `cur → next` runs share an axis and point opposite ways. A 90° turn or
/// a straight run through `cur` is not a reversal.
fn reverses_at(prev: GridPoint, cur: GridPoint, next: GridPoint) -> bool {
    let (ax, ay) = (cur.x - prev.x, cur.y - prev.y);
    let (bx, by) = (next.x - cur.x, next.y - cur.y);
    (ay == 0 && by == 0 && ax != 0 && bx != 0 && (ax > 0) != (bx > 0))
        || (ax == 0 && bx == 0 && ay != 0 && by != 0 && (ay > 0) != (by > 0))
}

/// The corners a backtracking prune drops from the polyline running
/// `start → waypoints → end`: a 180° kink the wire doubles back on, which
/// strict waypoint routing leaves behind when a corner sits *behind* its
/// neighbours. Iterative, because dropping one can expose a reversal
/// between its former neighbours; ordinals name the survivors' original
/// positions, so the preview can route around exactly what the commit
/// would remove. Locks do not protect a corner — a user bend that only
/// makes the wire reverse is still a kink.
pub fn backtracking_ordinals(
    waypoints: &[Waypoint],
    start: GridPoint,
    end: GridPoint,
) -> Vec<PathOrdinal> {
    let mut seq: Vec<(usize, GridPoint)> = waypoints
        .iter()
        .enumerate()
        .map(|(i, wp)| (i, wp.pos))
        .collect();
    let mut doomed = Vec::new();
    loop {
        let hit = (0..seq.len()).find(|&i| {
            let prev = if i == 0 { start } else { seq[i - 1].1 };
            let next = if i + 1 == seq.len() {
                end
            } else {
                seq[i + 1].1
            };
            reverses_at(prev, seq[i].1, next)
        });
        match hit {
            Some(i) => doomed.push(PathOrdinal::new(seq.remove(i).0)),
            None => break,
        }
    }
    doomed
}

/// The polyline with `doomed` dropped — the prune applied, for the commit
/// that writes it and the preview that previews it.
pub fn pruned_waypoints(waypoints: &[Waypoint], doomed: &[PathOrdinal]) -> Vec<Waypoint> {
    waypoints
        .iter()
        .enumerate()
        .filter(|(i, _)| !doomed.contains(&PathOrdinal::new(*i)))
        .map(|(_, wp)| *wp)
        .collect()
}

/// The two waypoint riders a move owes its wires: a route with both
/// endpoints riding keeps its shape, so its corners translate rigidly; one
/// that straddles the move drops its stale approach on the moved side so
/// the re-route rebuilds a clean one. Only wires drawn in a scope the move
/// happened in are reconciled — a moved block's interior did not move with
/// it, however many of its pins the wires in there land on.
///
/// With a zero `grid` only the straddlers change: what a single shape's
/// drop and a pin drag owe their wires.
pub(crate) fn push_route_riders(
    indexed: &IndexedDocument<'_>,
    moved: &HashSet<PinId>,
    scopes: &HashSet<BlockId>,
    grid: GridVec,
    builder: &mut CommitBuilder,
) {
    let touched: HashSet<RouteId> = moved
        .iter()
        .filter_map(|pin| indexed.index.routes_by_endpoint.get(pin))
        .flatten()
        .copied()
        .collect();
    let mut touched: Vec<RouteId> = touched.into_iter().collect();
    touched.sort();
    for id in touched {
        let Some(route) = indexed.doc.route(&id) else {
            continue;
        };
        if !scopes.contains(&route.owner) {
            continue;
        }
        let stored = route.waypoints.clone();
        let waypoints = match (moved.contains(&route.from), moved.contains(&route.to)) {
            (true, true) => stored
                .iter()
                .map(|wp| Waypoint {
                    pos: wp.pos + grid,
                    ..*wp
                })
                .collect(),
            (true, false) => trimmed_approach(&stored, RouteEnd::From),
            (false, true) => trimmed_approach(&stored, RouteEnd::To),
            (false, false) => continue,
        };
        if waypoints != stored {
            builder.push(OpCodes::Route(
                id,
                Crud::Update(RouteUpdate::Waypoints(waypoints)),
            ));
        }
    }
}

/// What a handle drag resizes. Text boxes are absent: their extent follows
/// their content, so they carry no handles. An icon is named by the block
/// that owns it, as it has no id of its own.
#[derive(Clone, Copy, Debug)]
pub enum ResizeTarget {
    Block(BlockId),
    Port(PinId),
    Area(AreaId),
    Image(ImageId),
    Icon(BlockId),
    Text(TextId),
}

fn owned_pins<'a>(
    indexed: &'a IndexedDocument<'a>,
    owner: BlockId,
) -> impl Iterator<Item = (PinId, &'a Pin)> + 'a {
    indexed
        .index
        .blocks
        .get(&owner)
        .into_iter()
        .flat_map(|entry| entry.pins.iter())
        .filter_map(|&id| Some((id, indexed.doc.pin(&id)?)))
}

/// Owned pins in a stable order, so a rider's ops read the same on every
/// run (the index's sets iterate by hash).
fn owned_pins_ordered<'a>(
    indexed: &'a IndexedDocument<'a>,
    owner: BlockId,
) -> Vec<(PinId, &'a Pin)> {
    let mut pins: Vec<(PinId, &Pin)> = owned_pins(indexed, owner).collect();
    pins.sort_by_key(|&(id, _)| id);
    pins
}

/// Inventory row "Resize Shape": the gesture resolved the final rect —
/// minimum sizes, the block-height ladder, aspect snapping, magnetism —
/// and this writes it with the riders it carries: a block's pins ride up
/// when the new height no longer holds the lowest slot, and its icon rides
/// the center and is held inside the new box.
pub fn resize(
    indexed: &IndexedDocument<'_>,
    target: ResizeTarget,
    to: Rect,
    builder: &mut CommitBuilder,
) {
    match target {
        ResizeTarget::Block(id) => {
            let Some(block) = indexed.doc.block(&id) else {
                return;
            };
            let old = block.rect;
            let new = grid_rect(to.min, to.max);
            let pins = owned_pins_ordered(indexed, id);
            let shift = resize_pin_shift(
                pins.iter().map(|(_, pin)| pin.slot.offset),
                px_u(new.size.h),
            );
            if shift > 0 {
                for (pin_id, pin) in pins {
                    let slot = pin.slot;
                    builder.push(OpCodes::Pin(
                        pin_id,
                        Crud::Update(PinUpdate::Slot(PinSlot {
                            offset: slot.offset.saturating_sub(shift),
                            ..slot
                        })),
                    ));
                }
            }
            if new != old {
                builder.push(OpCodes::Block(id, Crud::Update(BlockUpdate::Rect(new))));
            }
            let resized = icon_of(block).map(|icon| Icon {
                rect: screen_rect(icon_rect_after_resize(
                    artwork_rect(icon.rect),
                    px_rect(old),
                    px_rect(new),
                )),
                ..icon.clone()
            });
            push_icon(id, block, resized, builder);
        }
        ResizeTarget::Port(id) => {
            let Some(pin) = indexed.doc.pin(&id) else {
                return;
            };
            let rect = pin.rect;
            // Only the width moves: a port keeps the slot row it sits on
            // and the canonical body height.
            let new = GridRect {
                top_left: GridPoint {
                    x: grid_point(to.min).x,
                    y: rect.top(),
                },
                size: GridSize {
                    w: grid_u32(to.width()),
                    h: PORT_HEIGHT,
                },
            };
            if new != rect {
                builder.push(OpCodes::Pin(id, Crud::Update(PinUpdate::Rect(new))));
            }
        }
        ResizeTarget::Area(id) => {
            let Some(live) = indexed.doc.area(&id) else {
                return;
            };
            let new = grid_rect(to.min, to.max);
            if new != live.rect {
                builder.push(OpCodes::Area(id, Crud::Update(AreaUpdate::Rect(new))));
            }
        }
        // Only the width is the user's: the height follows the rows the
        // text wraps into at that width.
        ResizeTarget::Text(id) => {
            let Some(live) = indexed.doc.text(&id) else {
                return;
            };
            let pos = grid_point(to.min);
            if pos != live.pos {
                builder.push(OpCodes::Text(id, Crud::Update(TextUpdate::Pos(pos))));
            }
            let width = Some(crate::render::text_box::BoxWidth::spanning(to));
            if width != live.width {
                builder.push(OpCodes::Text(id, Crud::Update(TextUpdate::Width(width))));
            }
        }
        ResizeTarget::Image(id) => {
            let Some(live) = indexed.doc.image(&id) else {
                return;
            };
            let new = screen_rect(to);
            if new != live.rect {
                builder.push(OpCodes::Image(id, Crud::Update(ImageUpdate::Rect(new))));
            }
        }
        // An icon never leaves the block it belongs to, however its corners
        // were dragged — the same containment [`move_shape`] applies. The
        // resize gesture clamps to the block as well, so this is the rule
        // stated where it holds rather than a second clamp.
        ResizeTarget::Icon(id) => {
            let Some(block) = indexed.doc.block(&id) else {
                return;
            };
            let resized = icon_of(block).map(|icon| Icon {
                rect: screen_rect(contain_rect(to, px_rect(block.rect))),
                ..icon.clone()
            });
            push_icon(id, block, resized, builder);
        }
    }
}

/// Inventory row "Move Pin": drag a pin to another slot or the opposite
/// edge. The slot the drop resolved to arrives decided (the gesture picks
/// between the nearest slot and its neighbour against the live preview);
/// a destination another pin already holds writes nothing.
pub fn move_pin(
    indexed: &IndexedDocument<'_>,
    pin: PinId,
    to: PinSlot,
    builder: &mut CommitBuilder,
) {
    // No lock check: which slot a pin sits in is presentation, and a lock
    // freezes the interface's meaning rather than its layout
    // (`crate::edit::lock`).
    let Some(live) = indexed.doc.pin(&pin) else {
        return;
    };
    if live.slot == to {
        return;
    }
    let owner = live.owner;
    if owned_pins(indexed, owner).any(|(id, other)| id != pin && other.slot == to) {
        return;
    }
    builder.push(OpCodes::Pin(pin, Crud::Update(PinUpdate::Slot(to))));
}

/// One pin's destination in a group relocation.
#[derive(Clone, Copy, Debug)]
pub struct PinMove {
    pub pin: PinId,
    pub to: PinSlot,
}

/// Whether every destination is free and in bounds — an all-or-nothing
/// precheck. The group's own vacated slots count as free, since the movers
/// leave them in the same commit; two movers may not share one.
pub fn relocation_fits(indexed: &IndexedDocument<'_>, moves: &[PinMove]) -> bool {
    let movers: HashSet<PinId> = moves.iter().map(|m| m.pin).collect();
    let mut destinations: HashSet<(BlockId, PinSlot)> = HashSet::new();
    moves.iter().all(|m| {
        let Some(pin) = indexed.doc.pin(&m.pin) else {
            return false;
        };
        let owner = pin.owner;
        let Some(block) = indexed.doc.block(&owner) else {
            return false;
        };
        destinations.insert((owner, m.to))
            && m.to.offset <= slot_capacity(block.rect.size.h)
            && !owned_pins(indexed, owner)
                .any(|(id, other)| !movers.contains(&id) && other.slot == m.to)
    })
}

/// Inventory row "Relocate Pin Group": move a multi-pin selection rigidly
/// to new slots. All or nothing — one destination that is taken, out of
/// bounds, or on a frozen interface leaves the whole group where it is.
pub fn relocate_pins(
    indexed: &IndexedDocument<'_>,
    moves: &[PinMove],
    builder: &mut CommitBuilder,
) {
    if !relocation_fits(indexed, moves) {
        return;
    }
    for m in moves {
        let Some(pin) = indexed.doc.pin(&m.pin) else {
            continue;
        };
        if pin.slot != m.to {
            builder.push(OpCodes::Pin(m.pin, Crud::Update(PinUpdate::Slot(m.to))));
        }
    }
}

/// A whole-slot keyboard shift, negative upward.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SlotDelta(i32);

impl SlotDelta {
    pub fn new(slots: i32) -> Self {
        Self(slots)
    }
}

impl From<SlotDelta> for i32 {
    fn from(delta: SlotDelta) -> i32 {
        delta.0
    }
}

/// Inventory row "Nudge Pins": shift a pin group by whole slots, clamped
/// to the tightest range that keeps every pin on its own block, then
/// relocated as a group.
pub fn nudge_pins(
    indexed: &IndexedDocument<'_>,
    pins: &[PinId],
    delta: SlotDelta,
    builder: &mut CommitBuilder,
) {
    let (mut lowest, mut highest) = (i32::MIN, i32::MAX);
    let mut moving: Vec<(PinId, PinSlot)> = Vec::new();
    for &id in pins {
        let Some(pin) = indexed.doc.pin(&id) else {
            continue;
        };
        let Some(owner) = indexed.doc.block(&pin.owner) else {
            continue;
        };
        let slot = pin.slot;
        lowest = lowest.max(-(slot.offset as i32));
        highest = highest.min(slot_capacity(owner.rect.size.h) as i32 - slot.offset as i32);
        moving.push((id, slot));
    }
    if lowest > highest {
        return;
    }
    let delta = i32::from(delta).clamp(lowest, highest);
    if delta == 0 {
        return;
    }
    let moves: Vec<PinMove> = moving
        .into_iter()
        .map(|(pin, slot)| PinMove {
            pin,
            to: PinSlot {
                offset: (slot.offset as i32 + delta).max(0) as u32,
                ..slot
            },
        })
        .collect();
    relocate_pins(indexed, &moves, builder);
}

/// What a left/right mirror flips.
#[derive(Clone, Copy, Debug)]
pub enum FlipTarget {
    Block(BlockId),
    Port(PinId),
}

/// Inventory row "Flip Shape Pins": mirror a shape's pins left↔right.
///
/// A block moves every pin to the opposite edge while freezing how each
/// port body faces, so descending into the block shows the same boundary
/// as before; a port turns its own body around and stays on its slot.
/// Both come out as a toggle of `flip_lr`: the register reads `false` as
/// "faces `slot.side` flipped" and `true` as "faces `slot.side`", so a pin
/// whose edge flips must swap the flag to keep pointing the same way, and
/// a body told to turn around swaps it too.
pub fn flip_pins(indexed: &IndexedDocument<'_>, target: FlipTarget, builder: &mut CommitBuilder) {
    match target {
        FlipTarget::Block(id) => {
            // No lock check: which way a block's pins face is presentation
            // (`crate::edit::lock`) — the same pins, the same signals, drawn
            // the other way round.
            if indexed.doc.block(&id).is_none() {
                return;
            }
            for (pin_id, pin) in owned_pins_ordered(indexed, id) {
                let slot = pin.slot;
                builder.push(OpCodes::Pin(
                    pin_id,
                    Crud::Update(PinUpdate::Slot(PinSlot {
                        side: slot.side.flip(),
                        ..slot
                    })),
                ));
                builder.push(OpCodes::Pin(
                    pin_id,
                    Crud::Update(PinUpdate::FlipLR(!pin.flip_lr)),
                ));
            }
        }
        FlipTarget::Port(id) => {
            let Some(pin) = indexed.doc.pin(&id) else {
                return;
            };
            builder.push(OpCodes::Pin(
                id,
                Crud::Update(PinUpdate::FlipLR(!pin.flip_lr)),
            ));
        }
    }
}

/// Inventory row "Flip Block Vertical": mirror a block's pins top↔bottom
/// about its own slot capacity, keeping each pin's edge. An exact
/// involution, so a double flip is the identity.
pub fn flip_vertical(indexed: &IndexedDocument<'_>, block: BlockId, builder: &mut CommitBuilder) {
    // No lock check, as [`flip_pins`]: mirroring the pin order is
    // presentation.
    let Some(live) = indexed.doc.block(&block) else {
        return;
    };
    let capacity = slot_capacity(live.rect.size.h);
    for (id, pin) in owned_pins_ordered(indexed, block) {
        let slot = pin.slot;
        let mirrored = PinSlot {
            offset: capacity.saturating_sub(slot.offset),
            ..slot
        };
        if mirrored != slot {
            builder.push(OpCodes::Pin(id, Crud::Update(PinUpdate::Slot(mirrored))));
        }
    }
}

/// Inventory row "Move Wire Label": slide a wire's name label along its
/// route, to the arc length the drag settled on.
pub fn place_wire_label(
    doc: &Document,
    label: RouteLabelId,
    pos: FracVal,
    builder: &mut CommitBuilder,
) {
    let Some(live) = doc.route_label(&label) else {
        return;
    };
    if live.pos == pos {
        return;
    }
    builder.push(OpCodes::RouteLabel(
        label,
        Crud::Update(RouteLabelUpdate::Pos(pos)),
    ));
}

/// A finished hand-edit of a wire's path: the corner list the drag
/// promoted, and each label re-projected onto the geometry that list
/// solves to.
#[derive(Clone, Debug)]
pub struct RouteEdit<'a> {
    pub route: RouteId,
    pub waypoints: Vec<Waypoint>,
    pub anchors: &'a [(RouteLabelId, FracVal)],
}

/// Inventory row "Edit Route (commit)": the drag's one document write. The
/// polyline is one atomic value, so the promoted corners land wholesale.
pub fn commit_route_edit(doc: &Document, edit: RouteEdit<'_>, builder: &mut CommitBuilder) {
    let Some(route) = doc.route(&edit.route) else {
        return;
    };
    if edit.waypoints != route.waypoints {
        builder.push(OpCodes::Route(
            edit.route,
            Crud::Update(RouteUpdate::Waypoints(edit.waypoints)),
        ));
    }
    for &(label, pos) in edit.anchors {
        place_wire_label(doc, label, pos, builder);
    }
}

/// Inventory row "Reroute Wire / Block": drop the user's corners on `route`
/// and let the router solve afresh. Under the log the clear and the
/// re-promotion are one write of the solved list; a route the solver left
/// out is the bare clear.
///
/// One wire per call, deliberately: the block-wide form is
/// `Drawing::reroute_block`, which picks the wires *drawn on the level being
/// viewed* and calls this for each. Deliberately not every wire ending on the
/// block: those drawn a level down have nothing re-laying them, so a
/// document-wide rule would disagree with what the user is looking at.
pub fn reroute(
    indexed: &IndexedDocument<'_>,
    route: RouteId,
    solved: &[(RouteId, Vec<Waypoint>)],
    builder: &mut CommitBuilder,
) {
    let Some(live) = indexed.doc.route(&route) else {
        return;
    };
    let stored = live.waypoints.clone();
    let waypoints: Vec<Waypoint> = solved
        .iter()
        .find_map(|(id, list)| (*id == route).then(|| list.clone()))
        .unwrap_or_default();
    if waypoints != stored {
        builder.push(OpCodes::Route(
            route,
            Crud::Update(RouteUpdate::Waypoints(waypoints)),
        ));
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::edit::harness::{
        block_create, fold, image_create, pin_create, route_create, route_label_create,
        seals_to_nothing, wired,
    };
    use crate::grid::GRID_SIZE;
    use blockworx_doc::document::DocIndex;
    use blockworx_doc::{
        block_model::{Area, Image, Text},
        fixtures::{area_id, block_id, image_id, pin_id, route_id, route_label_id, text_id},
        values::PinSide,
    };
    use blockworx_geom::{pos2, vec2};

    /// A drag delta, in whole grid cells.
    fn by(x: f32, y: f32) -> Vec2 {
        vec2(x * GRID_SIZE, y * GRID_SIZE)
    }

    /// A world-space box, in whole grid cells.
    fn cells(min: (f32, f32), max: (f32, f32)) -> Rect {
        Rect::from_min_max(
            pos2(min.0 * GRID_SIZE, min.1 * GRID_SIZE),
            pos2(max.0 * GRID_SIZE, max.1 * GRID_SIZE),
        )
    }

    fn rect(x: i32, y: i32, w: u32, h: u32) -> GridRect {
        GridRect {
            top_left: GridPoint { x, y },
            size: GridSize { w, h },
        }
    }

    fn slot(side: PinSide, offset: u32) -> PinSlot {
        PinSlot { side, offset }
    }

    /// A corner the router solved, free to be re-solved.
    fn corner(x: i32, y: i32) -> Waypoint {
        Waypoint {
            pos: GridPoint { x, y },
            locked: false,
        }
    }

    /// A corner the user placed, which a trim must respect.
    fn pinned(x: i32, y: i32) -> Waypoint {
        Waypoint {
            locked: true,
            ..corner(x, y)
        }
    }

    /// A payload hash standing in for real artwork (the payload op itself
    /// is `assets`' business); only a non-null asset reads as "this block
    /// has an icon".
    fn asset() -> AssetHash {
        AssetHash::of(b"icon")
    }

    fn place_block(id: u32, to: GridRect) -> OpCodes {
        OpCodes::Block(block_id(id), Crud::Update(BlockUpdate::Rect(to)))
    }

    fn reparent(child: u32, parent: u32) -> OpCodes {
        OpCodes::Block(
            block_id(child),
            Crud::Update(BlockUpdate::Parent(block_id(parent))),
        )
    }

    fn lock(id: u32) -> OpCodes {
        OpCodes::Block(block_id(id), Crud::Update(BlockUpdate::Locked(true)))
    }

    fn set_icon(id: u32, to: Rect) -> OpCodes {
        OpCodes::Block(
            block_id(id),
            Crud::Update(BlockUpdate::Icon(Icon {
                asset: asset(),
                rect: screen_rect(to),
            })),
        )
    }

    fn place_pin(id: u32, to: GridRect) -> OpCodes {
        OpCodes::Pin(pin_id(id), Crud::Update(PinUpdate::Rect(to)))
    }

    fn seat_pin(id: u32, to: PinSlot) -> OpCodes {
        OpCodes::Pin(pin_id(id), Crud::Update(PinUpdate::Slot(to)))
    }

    fn place_image(id: u32, to: Rect) -> OpCodes {
        OpCodes::Image(
            image_id(id),
            Crud::Update(ImageUpdate::Rect(screen_rect(to))),
        )
    }

    fn place_area(id: u32, to: GridRect) -> OpCodes {
        OpCodes::Area(area_id(id), Crud::Update(AreaUpdate::Rect(to)))
    }

    fn wire(id: u32, waypoints: Vec<Waypoint>) -> OpCodes {
        OpCodes::Route(
            route_id(id),
            Crud::Update(RouteUpdate::Waypoints(waypoints)),
        )
    }

    fn block_of(doc: &Document, id: u32) -> &Block {
        doc.block(&block_id(id)).expect("the scene's block exists")
    }

    fn pin_of(doc: &Document, id: u32) -> &Pin {
        doc.pin(&pin_id(id)).expect("the scene's pin exists")
    }

    fn text_of(doc: &Document, id: u32) -> &Text {
        doc.text(&text_id(id)).expect("the scene's text exists")
    }

    fn area_of(doc: &Document, id: u32) -> &Area {
        doc.area(&area_id(id)).expect("the scene's area exists")
    }

    fn image_of(doc: &Document, id: u32) -> &Image {
        doc.image(&image_id(id)).expect("the scene's image exists")
    }

    fn box_of(doc: &Document, id: u32) -> GridRect {
        block_of(doc, id).rect
    }

    fn icon_box(doc: &Document, id: u32) -> Rect {
        artwork_rect(
            icon_of(block_of(doc, id))
                .expect("the block carries an icon")
                .rect,
        )
    }

    fn corners_of(doc: &Document, id: u32) -> Vec<Waypoint> {
        doc.route(&route_id(id))
            .expect("the scene's wire exists")
            .waypoints
            .clone()
    }

    /// Block 1 as the scope: child blocks 10 and 11 side by side, block
    /// 1's own port body parked clear of both, a wire between the children
    /// (16) and one running from 11 out to that port (17).
    fn scene() -> Document {
        let doc = wired();
        let mut builder = CommitBuilder::new("Furnished an interior");
        builder.extend([
            block_create(10),
            block_create(11),
            reparent(10, 1),
            reparent(11, 1),
            place_block(1, rect(0, 0, 40, 40)),
            place_block(10, rect(0, 0, 8, 16)),
            place_block(11, rect(20, 0, 8, 16)),
            place_pin(3, rect(10, 20, 4, 2)),
            pin_create(12, 10),
            pin_create(13, 11),
            pin_create(14, 11),
            seat_pin(12, slot(PinSide::East, 0)),
            seat_pin(13, slot(PinSide::West, 0)),
            seat_pin(14, slot(PinSide::East, 1)),
            route_create(16, 1, 12, 13),
            route_create(17, 1, 14, 3),
            wire(16, vec![corner(9, 4), corner(15, 4), corner(19, 4)]),
            wire(17, vec![corner(30, 4), corner(35, 4), corner(38, 4)]),
        ]);
        let doc = fold(builder, &doc);
        assert!(
            !box_of(&doc, 10).intersects(box_of(&doc, 11)),
            "precondition: the two children start clear of each other"
        );
        assert!(
            !box_of(&doc, 10).intersects(pin_of(&doc, 3).rect)
                && !box_of(&doc, 11).intersects(pin_of(&doc, 3).rect),
            "precondition: the scope's own port body obstructs neither child"
        );
        doc
    }

    #[test]
    fn move_shape_translates_a_block_and_the_icon_riding_it() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Gave the block an icon");
        builder.push(set_icon(10, cells((2.0, 4.0), (6.0, 8.0))));
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Moved a block");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(10)),
            by(0.0, 2.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(box_of(&doc, 10), rect(0, 2, 8, 16));
        assert_eq!(
            icon_box(&doc, 10),
            cells((2.0, 6.0), (6.0, 10.0)),
            "the icon travels with its block"
        );
    }

    #[test]
    fn a_single_move_is_rejected_by_any_overlap_at_its_destination() {
        let doc = scene();
        let mut index = DocIndex::default();
        let destination = box_of(&doc, 10).translate(GridVec::new(20, 0));
        assert!(
            destination.intersects(box_of(&doc, 11)),
            "precondition: the destination lands on the neighbour"
        );

        let mut builder = CommitBuilder::new("Moved a block onto its neighbour");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(10)),
            by(20.0, 0.0),
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    /// The preview and the commit ask one resolver, so a drag cannot show a
    /// landing the release then refuses — which is the whole of the paper cut
    /// "dropping a block onto another block silently authors nothing".
    #[test]
    fn what_the_preview_calls_refused_is_what_the_commit_refuses() {
        let doc = scene();
        let mut index = DocIndex::default();
        let onto_the_neighbour = by(20.0, 0.0);
        let into_the_clear = by(0.0, 40.0);
        let moving = Shape::Block(block_id(10));
        assert!(
            box_of(&doc, 10)
                .translate(GridVec::new(20, 0))
                .intersects(box_of(&doc, 11)),
            "precondition: one destination lands on the neighbour and one does not",
        );
        assert!(
            !box_of(&doc, 10)
                .translate(GridVec::new(0, 40))
                .intersects(box_of(&doc, 11)),
        );

        let view = index.view(&doc);
        assert!(
            move_refused(&view, &[moving], onto_the_neighbour, Moving::Alone),
            "the preview would have shown a landing the commit refuses",
        );
        assert!(!move_refused(
            &view,
            &[moving],
            into_the_clear,
            Moving::Alone
        ));

        // And the commit agrees, both ways.
        let mut refused = CommitBuilder::new("Moved a block onto its neighbour");
        move_shape(&view, moving, onto_the_neighbour, &mut refused);
        seals_to_nothing(refused);

        let mut taken = CommitBuilder::new("Moved a block into the clear");
        move_shape(&view, moving, into_the_clear, &mut taken);
        assert!(
            taken.seal().is_some(),
            "a move the preview called free authored nothing",
        );
    }

    /// The drawing marks the cells, so the cells are what the rule has to
    /// hand back — and a destination can conflict with more than one shape.
    #[test]
    fn a_move_hands_back_every_overlap_that_refuses_it() {
        let doc = scene();
        let mut index = DocIndex::default();
        let view = index.view(&doc);
        let moving = Shape::Block(block_id(10));

        let clear = move_conflicts(&view, &[moving], by(0.0, 40.0), Moving::Alone);
        assert!(
            clear.is_empty(),
            "a move into the clear conflicts with nothing"
        );

        let onto = move_conflicts(&view, &[moving], by(20.0, 0.0), Moving::Alone);
        assert_eq!(onto.len(), 1, "one neighbour, one overlap: {onto:?}");
        let overlap = onto[0];
        let destination = box_of(&doc, 10).translate(GridVec::new(20, 0));
        assert!(
            overlap.intersects(destination) && overlap.intersects(box_of(&doc, 11)),
            "the overlap is the cells the two would share, not either shape",
        );
        assert!(
            overlap.size.w <= destination.size.w && overlap.size.h <= destination.size.h,
            "an overlap cannot be bigger than what is moving",
        );
    }

    /// The group rule exempts the overlap a selection arrived with, so the
    /// drawing must not mark it: hatching one would claim a refusal that is
    /// not happening.
    #[test]
    fn a_group_reports_only_the_overlaps_its_move_creates() {
        let doc = scene();
        let mut builder = CommitBuilder::new("Parked the pair on each other");
        builder.push(place_block(11, rect(4, 0, 8, 16)));
        let doc = fold(builder, &doc);
        let mut index = DocIndex::default();
        let view = index.view(&doc);
        let pair = [Shape::Block(block_id(10)), Shape::Block(block_id(11))];
        assert!(
            box_of(&doc, 10).intersects(box_of(&doc, 11)),
            "precondition: the two already overlap, as a fresh paste leaves them",
        );

        assert!(
            move_conflicts(&view, &pair, by(0.0, 40.0), Moving::AsAGroup).is_empty(),
            "the overlap they arrived with is not a conflict the move created",
        );
    }

    /// A group of one is still a group: the gesture decides which rule
    /// applies, not how many shapes it happens to carry.
    #[test]
    fn a_group_of_one_keeps_the_group_rule() {
        let doc = scene();
        let mut index = DocIndex::default();
        let view = index.view(&doc);
        let sitting_on_it = Shape::Block(block_id(10));
        let onto_the_neighbour = by(20.0, 0.0);

        assert!(
            move_refused(&view, &[sitting_on_it], onto_the_neighbour, Moving::Alone),
            "precondition: dragged alone, this destination is refused",
        );
        assert!(
            !move_refused(&view, &[sitting_on_it], by(0.0, 40.0), Moving::AsAGroup),
            "a group move into the clear is taken whatever its size",
        );
    }

    #[test]
    fn only_a_group_move_exempts_an_overlap_the_shapes_already_had() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Parked the pair on each other");
        builder.push(place_block(11, rect(4, 0, 8, 16)));
        let doc = fold(builder, &doc);
        assert!(
            box_of(&doc, 10).intersects(box_of(&doc, 11)),
            "precondition: the two already overlap, so only a *new* overlap can be created"
        );

        let mut builder = CommitBuilder::new("Nudged one of them");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(10)),
            by(-1.0, 0.0),
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Nudged it as a group");
        move_group(
            &index.view(&doc),
            &[Shape::Block(block_id(10))],
            by(-1.0, 0.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(
            box_of(&doc, 10),
            rect(-1, 0, 8, 16),
            "the group rule rejects only the overlaps a move creates"
        );
    }

    #[test]
    fn move_shape_slides_a_port_body_a_text_box_and_an_area_on_the_grid() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Sized the area");
        builder.push(place_area(8, rect(2, 2, 6, 4)));
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Moved the annotations");
        move_shape(
            &index.view(&doc),
            Shape::Port(pin_id(3)),
            by(2.0, 3.0),
            &mut builder,
        );
        move_shape(
            &index.view(&doc),
            Shape::Text(text_id(7)),
            by(1.4, -0.4),
            &mut builder,
        );
        move_shape(
            &index.view(&doc),
            Shape::Area(area_id(8)),
            by(1.0, 1.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(pin_of(&doc, 3).rect, rect(12, 23, 4, 2));
        assert_eq!(
            text_of(&doc, 7).pos,
            GridPoint { x: 1, y: 0 },
            "a raw drag commits at the cell it snapped to"
        );
        assert_eq!(area_of(&doc, 8).rect, rect(3, 3, 6, 4));
    }

    #[test]
    fn artwork_moves_in_free_pixels_and_an_icon_stays_inside_its_block() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Placed the artwork");
        builder.extend([
            image_create(20, 1),
            place_image(20, cells((10.0, 10.0), (14.0, 14.0))),
            set_icon(10, cells((2.0, 4.0), (6.0, 8.0))),
        ]);
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Nudged the artwork");
        move_shape(
            &index.view(&doc),
            Shape::Image(image_id(20)),
            vec2(7.5, -3.25),
            &mut builder,
        );
        move_shape(
            &index.view(&doc),
            Shape::Icon(block_id(10)),
            vec2(1000.0, 1000.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(
            artwork_rect(image_of(&doc, 20).rect),
            cells((10.0, 10.0), (14.0, 14.0)).translate(vec2(7.5, -3.25)),
            "an image keeps the pixels the drag gave it — no snap"
        );
        let block = px_rect(box_of(&doc, 10));
        let icon = icon_box(&doc, 10);
        assert!(
            block.contains_rect(icon),
            "the icon is held inside the block it belongs to"
        );
        assert_eq!(
            icon,
            Rect::from_min_max(block.max - vec2(60.0, 60.0), block.max),
            "a shove past the corner shifts the icon back, without shrinking it"
        );
    }

    #[test]
    fn a_move_of_nothing_and_a_move_of_a_ghost_push_nothing() {
        let doc = scene();
        let mut index = DocIndex::default();

        let mut builder = CommitBuilder::new("Moved a block by nothing");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(10)),
            Vec2::ZERO,
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Moved a block by half a cell");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(10)),
            by(0.4, 0.0),
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Moved a ghost");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(99)),
            by(1.0, 0.0),
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Moved a ghost group");
        move_group(
            &index.view(&doc),
            &[Shape::Image(image_id(99)), Shape::Block(block_id(99))],
            by(1.0, 0.0),
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn move_group_shifts_every_member_by_one_snapped_delta() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Placed the annotations");
        builder.extend([
            image_create(20, 1),
            place_image(20, cells((10.0, 10.0), (14.0, 14.0))),
            place_area(8, rect(2, 2, 6, 4)),
        ]);
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Moved a selection");
        move_group(
            &index.view(&doc),
            &[
                Shape::Block(block_id(10)),
                Shape::Block(block_id(11)),
                Shape::Text(text_id(7)),
                Shape::Area(area_id(8)),
                Shape::Image(image_id(20)),
            ],
            by(1.4, 0.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(box_of(&doc, 10), rect(1, 0, 8, 16));
        assert_eq!(box_of(&doc, 11), rect(21, 0, 8, 16));
        assert_eq!(text_of(&doc, 7).pos, GridPoint { x: 1, y: 0 });
        assert_eq!(area_of(&doc, 8).rect, rect(3, 2, 6, 4));
        assert_eq!(
            artwork_rect(image_of(&doc, 20).rect),
            cells((11.0, 10.0), (15.0, 14.0)),
            "an image in a group takes the shared snapped delta, unlike a single move"
        );
    }

    #[test]
    fn a_group_move_onto_a_clear_neighbour_is_rejected_wholesale() {
        let doc = scene();
        let mut index = DocIndex::default();
        let destination = box_of(&doc, 10).translate(GridVec::new(20, 0));
        assert!(
            !box_of(&doc, 10).intersects(box_of(&doc, 11))
                && destination.intersects(box_of(&doc, 11)),
            "precondition: the neighbour is clear now and covered at the destination"
        );

        let mut builder = CommitBuilder::new("Moved a selection onto a neighbour");
        move_group(
            &index.view(&doc),
            &[Shape::Block(block_id(10)), Shape::Text(text_id(7))],
            by(20.0, 0.0),
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn a_wire_with_both_ends_riding_translates_its_corners_rigidly() {
        let doc = scene();
        let mut index = DocIndex::default();
        assert_eq!(
            (
                pin_of(&doc, 12).owner,
                pin_of(&doc, 13).owner,
                pin_of(&doc, 3).owner
            ),
            (block_id(10), block_id(11), block_id(1)),
            "precondition: wire 16 runs between the two moved blocks and wire 17 leaves them"
        );

        let mut builder = CommitBuilder::new("Moved the pair");
        move_group(
            &index.view(&doc),
            &[Shape::Block(block_id(10)), Shape::Block(block_id(11))],
            by(0.0, 4.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(
            corners_of(&doc, 16),
            vec![corner(9, 8), corner(15, 8), corner(19, 8)],
            "a wire that keeps its shape shifts its corners by the same cell delta"
        );
        assert_eq!(
            corners_of(&doc, 17),
            vec![corner(38, 4)],
            "the straddling wire drops its stale approach on the moved side"
        );
    }

    #[test]
    fn a_straddling_wire_trims_from_the_end_that_moved() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Moved one block");
        move_group(
            &index.view(&doc),
            &[Shape::Block(block_id(11))],
            by(0.0, 4.0),
            &mut builder,
        );
        let moved = fold(builder, &doc);

        assert_eq!(
            corners_of(&moved, 16),
            vec![corner(9, 4)],
            "wire 16 ends on the moved block, so its trailing corners go"
        );
        assert_eq!(
            corners_of(&moved, 17),
            vec![corner(38, 4)],
            "wire 17 starts on the moved block, so its leading corners go"
        );
    }

    #[test]
    fn a_trim_stops_at_the_first_corner_the_user_placed() {
        let trimmed = |corners: Vec<Waypoint>| {
            let doc = scene();
            let mut builder = CommitBuilder::new("Pinned a corner");
            builder.push(wire(17, corners));
            let doc = fold(builder, &doc);

            let mut builder = CommitBuilder::new("Moved one block");
            move_group(
                &DocIndex::default().view(&doc),
                &[Shape::Block(block_id(11))],
                by(0.0, 4.0),
                &mut builder,
            );
            corners_of(&fold(builder, &doc), 17)
        };

        assert_eq!(
            trimmed(vec![pinned(30, 4), corner(35, 4), corner(38, 4)]),
            vec![pinned(30, 4), corner(35, 4), corner(38, 4)],
            "a locked corner nearest the moved end stops the trim before it starts"
        );
        assert_eq!(
            trimmed(vec![corner(30, 4), pinned(35, 4), corner(38, 4)]),
            vec![pinned(35, 4), corner(38, 4)],
            "the trim stops at the first locked corner"
        );
        assert_eq!(
            trimmed(vec![
                corner(30, 4),
                corner(35, 4),
                corner(38, 4),
                corner(39, 4)
            ]),
            vec![corner(38, 4), corner(39, 4)],
            "at most two corners go, however many are stale"
        );
    }

    #[test]
    fn a_dragged_port_trims_the_wires_that_end_on_it() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Moved a port body");
        move_group(
            &index.view(&doc),
            &[Shape::Port(pin_id(3))],
            by(1.0, 0.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(pin_of(&doc, 3).rect, rect(11, 20, 4, 2));
        assert_eq!(
            corners_of(&doc, 17),
            vec![corner(30, 4)],
            "the port is wire 17's far end, so the trim comes off the back"
        );
    }

    /// A block's boundary pins are endpoints at two levels: the parent's
    /// wires land on them, and so do the block's own interior wires. Moving
    /// the block in the parent moves neither the interior nor its wires, so
    /// the reconciliation must not reach them.
    #[test]
    fn a_move_leaves_the_moved_blocks_interior_wires_alone() {
        let doc = scene();
        let mut index = DocIndex::default();
        // A grandchild inside block 11, wired to block 11's own pin 13 — an
        // interior wire owned by 11, anchored to a pin the parent also sees.
        let mut builder = CommitBuilder::new("Wired the interior");
        builder.extend([
            block_create(30),
            reparent(30, 11),
            pin_create(31, 30),
            route_create(32, 11, 13, 31),
            wire(32, vec![corner(2, 2), corner(4, 2)]),
        ]);
        let doc = fold(builder, &doc);
        let interior = corners_of(&doc, 32);
        assert_eq!(interior.len(), 2, "precondition: the interior wire bends");
        assert!(
            index.view(&doc).index.routes_by_endpoint[&pin_id(13)].contains(&route_id(32)),
            "precondition: the interior wire really lands on the moved block's pin"
        );

        let mut builder = CommitBuilder::new("Moved the block in its parent");
        move_group(
            &index.view(&doc),
            &[Shape::Block(block_id(11))],
            by(0.0, 4.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(
            corners_of(&doc, 32),
            interior,
            "the interior wire is drawn in a scope the move never touched"
        );
    }

    #[test]
    fn an_icon_co_selected_with_its_block_shifts_once() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Gave the block an icon");
        builder.push(set_icon(10, cells((2.0, 4.0), (6.0, 8.0))));
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Moved a block with its icon selected");
        move_group(
            &index.view(&doc),
            &[Shape::Block(block_id(10)), Shape::Icon(block_id(10))],
            by(2.0, 0.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(
            icon_box(&doc, 10),
            cells((4.0, 4.0), (8.0, 8.0)),
            "the icon shifts by one block move, not by two"
        );
    }

    /// Block 10 tall enough for five slots, with pins near the top and the
    /// bottom of that range — the span a shrink has to preserve.
    fn spanned() -> Document {
        let doc = scene();
        let mut builder = CommitBuilder::new("Spread the pins");
        builder.extend([
            pin_create(15, 10),
            seat_pin(12, slot(PinSide::East, 4)),
            seat_pin(15, slot(PinSide::West, 2)),
        ]);
        let doc = fold(builder, &doc);
        assert_eq!(
            slot_capacity(box_of(&doc, 10).size.h),
            4,
            "precondition: the block is exactly tall enough for its lowest pin"
        );
        doc
    }

    #[test]
    fn resize_writes_the_new_box_and_rides_the_pins_up_when_they_stop_fitting() {
        let doc = spanned();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Gave the block an icon");
        builder.push(set_icon(10, cells((2.0, 4.0), (6.0, 8.0))));
        let doc = fold(builder, &doc);
        assert_eq!(
            slot_capacity(4),
            0,
            "precondition: four cells hold slot 0 alone"
        );

        let mut builder = CommitBuilder::new("Shrank a block");
        resize(
            &index.view(&doc),
            ResizeTarget::Block(block_id(10)),
            cells((0.0, 0.0), (8.0, 4.0)),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(box_of(&doc, 10), rect(0, 0, 8, 4));
        assert_eq!(
            (pin_of(&doc, 12).slot.offset, pin_of(&doc, 15).slot.offset),
            (2, 0),
            "the group rides up by the highest pin's own offset, keeping its span"
        );
        assert_eq!(
            pin_of(&doc, 12).slot,
            slot(PinSide::East, 2),
            "a pin keeps the edge it sits on"
        );
        assert_eq!(
            icon_box(&doc, 10),
            cells((2.0, 0.0), (6.0, 4.0)),
            "the icon rides the block's center, then is held inside the smaller box"
        );
    }

    #[test]
    fn a_resize_that_still_fits_its_pins_leaves_them_alone() {
        let doc = spanned();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Widened a block");
        resize(
            &index.view(&doc),
            ResizeTarget::Block(block_id(10)),
            cells((0.0, 0.0), (12.0, 16.0)),
            &mut builder,
        );
        let commit = builder.seal().expect("the block widened");
        assert_eq!(
            commit.ops().len(),
            1,
            "a resize with room to spare is one write"
        );
        let doc = doc
            .try_apply(&commit)
            .expect("the fold accepts the gesture");

        assert_eq!(box_of(&doc, 10), rect(0, 0, 12, 16));
        assert_eq!(pin_of(&doc, 12).slot.offset, 4);
    }

    #[test]
    fn resize_keeps_a_ports_slot_row_and_canonical_height() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Widened a port body");
        resize(
            &index.view(&doc),
            ResizeTarget::Port(pin_id(3)),
            cells((9.0, 0.0), (15.0, 9.0)),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(
            pin_of(&doc, 3).rect,
            rect(9, 20, 6, PORT_HEIGHT),
            "only the left edge and the width move"
        );
    }

    #[test]
    fn resize_writes_an_area_on_the_grid_and_an_image_in_free_pixels() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Placed an image");
        builder.extend([
            image_create(20, 1),
            place_image(20, cells((10.0, 10.0), (14.0, 14.0))),
        ]);
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Resized the annotations");
        resize(
            &index.view(&doc),
            ResizeTarget::Area(area_id(8)),
            cells((1.0, 1.0), (5.4, 4.0)),
            &mut builder,
        );
        resize(
            &index.view(&doc),
            ResizeTarget::Image(image_id(20)),
            Rect::from_min_max(pos2(150.0, 150.0), pos2(207.5, 190.0)),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(area_of(&doc, 8).rect, rect(1, 1, 4, 3));
        assert_eq!(
            artwork_rect(image_of(&doc, 20).rect),
            Rect::from_min_max(pos2(150.0, 150.0), pos2(207.5, 190.0)),
            "artwork resizes off the grid"
        );
    }

    #[test]
    fn a_resize_to_the_box_it_already_has_pushes_nothing() {
        let doc = scene();
        let mut index = DocIndex::default();

        let mut builder = CommitBuilder::new("Resized a block to itself");
        resize(
            &index.view(&doc),
            ResizeTarget::Block(block_id(10)),
            cells((0.0, 0.0), (8.0, 16.0)),
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Resized a ghost");
        resize(
            &index.view(&doc),
            ResizeTarget::Area(area_id(99)),
            cells((0.0, 0.0), (4.0, 4.0)),
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn move_pin_takes_a_free_slot_and_declines_a_taken_one() {
        let doc = scene();
        let mut index = DocIndex::default();
        assert_eq!(
            pin_of(&doc, 14).slot,
            slot(PinSide::East, 1),
            "precondition: the destination below is already held by a sibling"
        );

        let mut builder = CommitBuilder::new("Dropped a pin on a taken slot");
        move_pin(
            &index.view(&doc),
            pin_id(13),
            slot(PinSide::East, 1),
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Dropped a pin where it already sits");
        move_pin(
            &index.view(&doc),
            pin_id(13),
            slot(PinSide::West, 0),
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Dropped a pin on a free slot");
        move_pin(
            &index.view(&doc),
            pin_id(13),
            slot(PinSide::East, 0),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(pin_of(&doc, 13).slot, slot(PinSide::East, 0));
    }

    /// The scene with the pins' owner frozen — the arm every slot edit
    /// must decline.
    fn frozen() -> Document {
        let doc = scene();
        let mut builder = CommitBuilder::new("Locked a block");
        builder.push(lock(11));
        let doc = fold(builder, &doc);
        assert!(
            block_of(&doc, 11).locked,
            "precondition: the owner is locked"
        );
        doc
    }

    /// A lock freezes what a pin *is*, not where it sits. Slot edits and
    /// flips are presentation (`crate::edit::lock`), so a frozen interface
    /// takes them — the same pins, the same signals, drawn differently.
    #[test]
    fn a_frozen_interface_still_takes_every_slot_edit() {
        let doc = frozen();
        let mut index = DocIndex::default();

        let mut builder = CommitBuilder::new("Dropped a frozen pin");
        move_pin(
            &index.view(&doc),
            pin_id(13),
            slot(PinSide::East, 0),
            &mut builder,
        );
        assert!(builder.seal().is_some(), "a locked pin still moves slots");

        let mut builder = CommitBuilder::new("Relocated a frozen group");
        relocate_pins(
            &index.view(&doc),
            &[PinMove {
                pin: pin_id(13),
                to: slot(PinSide::East, 0),
            }],
            &mut builder,
        );
        assert!(builder.seal().is_some(), "and relocates as a group");

        let mut builder = CommitBuilder::new("Nudged a frozen group");
        nudge_pins(
            &index.view(&doc),
            &[pin_id(13), pin_id(14)],
            SlotDelta::new(1),
            &mut builder,
        );
        assert!(builder.seal().is_some(), "and nudges");

        let mut builder = CommitBuilder::new("Flipped a frozen block");
        flip_pins(
            &index.view(&doc),
            FlipTarget::Block(block_id(11)),
            &mut builder,
        );
        assert!(builder.seal().is_some(), "and flips left/right");

        let mut builder = CommitBuilder::new("Flipped a frozen port");
        flip_pins(
            &index.view(&doc),
            FlipTarget::Port(pin_id(13)),
            &mut builder,
        );
        assert!(builder.seal().is_some(), "port included");

        let mut builder = CommitBuilder::new("Mirrored a frozen block");
        flip_vertical(&index.view(&doc), block_id(11), &mut builder);
        assert!(builder.seal().is_some(), "and mirrors top/bottom");
    }

    /// The lock freezes the pin interface, not the canvas: a locked block
    /// still moves and resizes.
    #[test]
    fn a_frozen_interface_still_moves_and_resizes() {
        let doc = frozen();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Moved and resized a locked block");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(11)),
            by(1.0, 0.0),
            &mut builder,
        );
        resize(
            &index.view(&doc),
            ResizeTarget::Block(block_id(11)),
            cells((20.0, 0.0), (30.0, 16.0)),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(
            box_of(&doc, 11),
            rect(20, 0, 10, 16),
            "the resize is the later write of the two"
        );
    }

    #[test]
    fn relocate_pins_swaps_a_group_through_the_slots_it_vacates() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Swapped two pins");
        relocate_pins(
            &index.view(&doc),
            &[
                PinMove {
                    pin: pin_id(13),
                    to: slot(PinSide::East, 1),
                },
                PinMove {
                    pin: pin_id(14),
                    to: slot(PinSide::West, 0),
                },
            ],
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(pin_of(&doc, 13).slot, slot(PinSide::East, 1));
        assert_eq!(pin_of(&doc, 14).slot, slot(PinSide::West, 0));
    }

    #[test]
    fn a_group_relocation_is_all_or_nothing() {
        let doc = scene();
        let mut index = DocIndex::default();
        let indexed = index.view(&doc);
        let refused = |moves: &[PinMove], label: &'static str| {
            let mut builder = CommitBuilder::new(label);
            relocate_pins(&indexed, moves, &mut builder);
            seals_to_nothing(builder);
        };

        refused(
            &[PinMove {
                pin: pin_id(13),
                to: slot(PinSide::East, 1),
            }],
            "Moved one pin onto a sibling that stays put",
        );
        assert_eq!(
            slot_capacity(box_of(&doc, 11).size.h),
            4,
            "precondition: slot 5 is past the block's own capacity"
        );
        refused(
            &[
                PinMove {
                    pin: pin_id(13),
                    to: slot(PinSide::West, 1),
                },
                PinMove {
                    pin: pin_id(14),
                    to: slot(PinSide::East, 5),
                },
            ],
            "Moved a group off the end of its block",
        );
        refused(
            &[
                PinMove {
                    pin: pin_id(13),
                    to: slot(PinSide::West, 2),
                },
                PinMove {
                    pin: pin_id(14),
                    to: slot(PinSide::West, 2),
                },
            ],
            "Moved two pins onto one slot",
        );
        refused(
            &[PinMove {
                pin: pin_id(99),
                to: slot(PinSide::West, 2),
            }],
            "Moved a ghost",
        );
    }

    #[test]
    fn nudge_pins_shifts_a_group_rigidly_and_clamps_at_the_block_edges() {
        let doc = scene();
        let mut index = DocIndex::default();
        assert_eq!(
            (pin_of(&doc, 13).slot.offset, pin_of(&doc, 14).slot.offset),
            (0, 1),
            "precondition: the group starts against the top edge"
        );
        let group = [pin_id(13), pin_id(14)];

        let mut builder = CommitBuilder::new("Nudged the group up");
        nudge_pins(&index.view(&doc), &group, SlotDelta::new(-1), &mut builder);
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Nudged the group down");
        nudge_pins(&index.view(&doc), &group, SlotDelta::new(1), &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(
            (pin_of(&doc, 13).slot.offset, pin_of(&doc, 14).slot.offset),
            (1, 2)
        );

        let mut builder = CommitBuilder::new("Nudged the group off the bottom");
        nudge_pins(&index.view(&doc), &group, SlotDelta::new(10), &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(
            (pin_of(&doc, 13).slot.offset, pin_of(&doc, 14).slot.offset),
            (3, 4),
            "the shift clamps to the tightest range that keeps every pin on its block"
        );
    }

    /// Inventory row "Keyboard Nudge": arrow keys are a one-cell shape
    /// delta and a one-slot pin delta, so the rows above cover it whole.
    #[test]
    fn a_keyboard_nudge_is_one_cell_or_one_slot_through_the_rows_above() {
        let doc = scene();
        let mut index = DocIndex::default();

        let mut builder = CommitBuilder::new("Nudged a block");
        move_shape(
            &index.view(&doc),
            Shape::Block(block_id(10)),
            by(-1.0, 0.0),
            &mut builder,
        );
        let moved = fold(builder, &doc);
        assert_eq!(box_of(&moved, 10), rect(-1, 0, 8, 16));

        let mut builder = CommitBuilder::new("Nudged a selection");
        move_group(
            &index.view(&doc),
            &[Shape::Block(block_id(10)), Shape::Block(block_id(11))],
            by(0.0, 1.0),
            &mut builder,
        );
        let moved = fold(builder, &doc);
        assert_eq!(box_of(&moved, 10), rect(0, 1, 8, 16));
        assert_eq!(box_of(&moved, 11), rect(20, 1, 8, 16));

        let mut builder = CommitBuilder::new("Nudged a pin");
        nudge_pins(
            &index.view(&doc),
            &[pin_id(14)],
            SlotDelta::new(1),
            &mut builder,
        );
        let moved = fold(builder, &doc);
        assert_eq!(pin_of(&moved, 14).slot, slot(PinSide::East, 2));
    }

    #[test]
    fn flip_pins_moves_every_pin_to_the_far_edge_and_freezes_how_it_faces() {
        let doc = scene();
        let mut index = DocIndex::default();
        assert!(
            !pin_of(&doc, 13).flip_lr,
            "precondition: the pins face the default way — opposite their own edge"
        );

        let mut builder = CommitBuilder::new("Flipped a block");
        flip_pins(
            &index.view(&doc),
            FlipTarget::Block(block_id(11)),
            &mut builder,
        );
        let flipped = fold(builder, &doc);

        assert_eq!(pin_of(&flipped, 13).slot, slot(PinSide::East, 0));
        assert_eq!(pin_of(&flipped, 14).slot, slot(PinSide::West, 1));
        assert!(
            pin_of(&flipped, 13).flip_lr && pin_of(&flipped, 14).flip_lr,
            "the body keeps pointing the way it did, which on the far edge reads as flipped"
        );

        let mut builder = CommitBuilder::new("Flipped it back");
        flip_pins(
            &index.view(&flipped),
            FlipTarget::Block(block_id(11)),
            &mut builder,
        );
        let back = fold(builder, &flipped);
        for id in [13, 14] {
            assert_eq!(pin_of(&back, id).slot, pin_of(&doc, id).slot);
            assert_eq!(
                pin_of(&back, id).flip_lr,
                pin_of(&doc, id).flip_lr,
                "a double flip is the identity"
            );
        }
    }

    #[test]
    fn flipping_a_port_turns_its_body_around_and_leaves_its_slot() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Flipped a port");
        flip_pins(
            &index.view(&doc),
            FlipTarget::Port(pin_id(13)),
            &mut builder,
        );
        let flipped = fold(builder, &doc);

        assert!(pin_of(&flipped, 13).flip_lr);
        assert_eq!(
            pin_of(&flipped, 13).slot,
            slot(PinSide::West, 0),
            "a port stays on the slot it occupies as a pin"
        );

        let mut builder = CommitBuilder::new("Flipped it back");
        flip_pins(
            &index.view(&flipped),
            FlipTarget::Port(pin_id(13)),
            &mut builder,
        );
        let back = fold(builder, &flipped);
        assert!(!pin_of(&back, 13).flip_lr);
    }

    #[test]
    fn flip_vertical_mirrors_the_slots_about_the_blocks_capacity() {
        let doc = scene();
        let mut index = DocIndex::default();
        let capacity = slot_capacity(box_of(&doc, 11).size.h);
        assert_eq!(capacity, 4, "precondition: the block holds five slots");

        let mut builder = CommitBuilder::new("Mirrored a block");
        flip_vertical(&index.view(&doc), block_id(11), &mut builder);
        let flipped = fold(builder, &doc);

        assert_eq!(pin_of(&flipped, 13).slot, slot(PinSide::West, 4));
        assert_eq!(pin_of(&flipped, 14).slot, slot(PinSide::East, 3));

        let mut builder = CommitBuilder::new("Mirrored it back");
        flip_vertical(&index.view(&flipped), block_id(11), &mut builder);
        let back = fold(builder, &flipped);
        for id in [13, 14] {
            assert_eq!(
                pin_of(&back, id).slot,
                pin_of(&doc, id).slot,
                "a double mirror is the identity"
            );
        }
    }

    #[test]
    fn place_wire_label_writes_the_arc_length_once() {
        let doc = scene();
        let mut builder = CommitBuilder::new("Labelled a wire");
        builder.push(route_label_create(6, 16));
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Slid the label");
        place_wire_label(&doc, route_label_id(6), FracVal::from(12.5), &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(
            doc.route_label(&route_label_id(6))
                .expect("the label exists")
                .pos,
            FracVal::from(12.5)
        );

        let mut builder = CommitBuilder::new("Slid it nowhere");
        place_wire_label(&doc, route_label_id(6), FracVal::from(12.5), &mut builder);
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Slid a ghost label");
        place_wire_label(&doc, route_label_id(99), FracVal::from(1.0), &mut builder);
        seals_to_nothing(builder);
    }

    #[test]
    fn commit_route_edit_writes_the_promoted_corners_and_re_anchors_the_labels() {
        let doc = scene();
        let mut builder = CommitBuilder::new("Labelled a wire twice");
        builder.extend([route_label_create(6, 16), route_label_create(9, 16)]);
        let doc = fold(builder, &doc);

        let promoted = vec![pinned(9, 6), corner(15, 6), corner(19, 6)];
        let mut builder = CommitBuilder::new("Edited a route");
        commit_route_edit(
            &doc,
            RouteEdit {
                route: route_id(16),
                waypoints: promoted.clone(),
                anchors: &[
                    (route_label_id(6), FracVal::from(4.5)),
                    (route_label_id(9), FracVal::default()),
                ],
            },
            &mut builder,
        );
        let commit = builder.seal().expect("the edit produced ops");
        assert_eq!(
            commit.ops().len(),
            2,
            "a label already at its distance takes no write of its own"
        );
        let doc = doc
            .try_apply(&commit)
            .expect("the fold accepts the gesture");

        assert_eq!(corners_of(&doc, 16), promoted);
        assert_eq!(
            doc.route_label(&route_label_id(6))
                .expect("the label exists")
                .pos,
            FracVal::from(4.5)
        );

        let mut builder = CommitBuilder::new("Edited it to the shape it has");
        commit_route_edit(
            &doc,
            RouteEdit {
                route: route_id(16),
                waypoints: promoted,
                anchors: &[],
            },
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn reroute_writes_the_re_solved_list_for_one_wire() {
        let doc = scene();
        let mut index = DocIndex::default();
        let solved = vec![corner(12, 2)];
        let mut builder = CommitBuilder::new("Rerouted a wire");
        reroute(
            &index.view(&doc),
            route_id(16),
            &[(route_id(16), solved.clone())],
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(corners_of(&doc, 16), solved);
        assert_eq!(
            corners_of(&doc, 17).len(),
            3,
            "the wire that was not asked for is untouched"
        );

        let mut builder = CommitBuilder::new("Rerouted it to what it has");
        reroute(
            &index.view(&doc),
            route_id(16),
            &[(route_id(16), solved)],
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    /// `Drawing::reroute_block` calls this with an empty solved list and lets
    /// the next pass re-lay the wire, so "no solution offered" has to mean
    /// "drop the corners" rather than "leave them".
    #[test]
    fn a_wire_the_solver_left_out_keeps_the_bare_clear() {
        let doc = scene();
        let mut index = DocIndex::default();
        assert!(
            !corners_of(&doc, 16).is_empty(),
            "precondition: the wire has corners to lose"
        );

        let mut builder = CommitBuilder::new("Rerouted a wire");
        reroute(&index.view(&doc), route_id(16), &[], &mut builder);
        let doc = fold(builder, &doc);

        assert!(corners_of(&doc, 16).is_empty());
    }
}