blockworx_editor/edit/

clipboard.rs

//! The clipboard family: copy, cut, and the two pastes.
//!
//! The clipboard holds a **value snapshot** — every copied entity's source
//! id and its creation values — never live references. Those source ids are
//! what makes a
//! cut-and-paste a *move*: the cut removes exactly them, so a paste that
//! finds none of them here re-creates them under their own ids rather than
//! building copies. Every other paste duplicates, with fresh ids and every
//! internal reference remapped onto them.

use ahash::{HashMap, HashMapExt, HashSet};
use blockworx_doc::{
    block_model::{Area, Asset, Block, BlockUpdate, Icon, Image, Pin, Route, RouteLabel, Text},
    commit::CommitBuilder,
    document::{Document, IndexedDocument},
    geometry::{GridPoint, GridVec, PinSlot, ScreenRect, Waypoint},
    hash::AssetHash,
    id::{Allocator, AreaId, BlockId, Id, IdKind, ImageId, PinId, RouteId, RouteLabelId, TextId},
    opcode::{Crud, OpCodes},
};
use blockworx_geom::Vec2;

use serde::{Deserialize, Serialize};

use crate::edit::assets::push_payload;
use crate::edit::create::{first_free_slot, grown_to_fit, owner_pins};
use crate::edit::delete::{Closure, Target, closure};
use crate::edit::geometry::{Shape, artwork, shifted_icon};
use crate::grid::{artwork_rect, grid_point, px_vec, screen_rect};

use crate::path::Scope;
use blockworx_store::doc::DocumentNonce;

/// The copied closure as values: each entity's source id beside the init
/// that rebuilds it, plus the artwork payloads the copies reference. Self
/// contained — blocks carry their parent links as copied, pins their
/// slots, wires their endpoints and corners — so a paste needs nothing of
/// the document it came from.
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
pub struct Snapshot {
    pub blocks: Vec<(BlockId, Block)>,
    pub pins: Vec<(PinId, Pin)>,
    pub routes: Vec<(RouteId, Route)>,
    pub labels: Vec<(RouteLabelId, RouteLabel)>,
    pub texts: Vec<(TextId, Text)>,
    pub areas: Vec<(AreaId, Area)>,
    pub images: Vec<(ImageId, Image)>,
    pub assets: Vec<Asset>,
}

impl Snapshot {
    /// Every entity of `closure`, cloned whole as it stands, so a field
    /// added to a kind travels on the clipboard without anyone
    /// remembering to add it here.
    fn of(doc: &Document, closure: &Closure) -> Self {
        let blocks: Vec<(BlockId, Block)> = closure
            .blocks
            .iter()
            .filter_map(|&id| Some((id, doc.block(&id)?.clone())))
            .collect();
        let images: Vec<(ImageId, Image)> = closure
            .images
            .iter()
            .filter_map(|&id| Some((id, doc.image(&id)?.clone())))
            .collect();
        let referenced = blocks
            .iter()
            .map(|(_, block)| block.icon.asset)
            .chain(images.iter().map(|(_, image)| image.asset));
        Self {
            pins: closure
                .pins
                .iter()
                .filter_map(|&id| Some((id, doc.pin(&id)?.clone())))
                .collect(),
            routes: closure
                .routes
                .iter()
                .filter_map(|&id| Some((id, doc.route(&id)?.clone())))
                .collect(),
            labels: closure
                .labels
                .iter()
                .filter_map(|&id| Some((id, doc.route_label(&id)?.clone())))
                .collect(),
            texts: closure
                .texts
                .iter()
                .filter_map(|&id| Some((id, doc.text(&id)?.clone())))
                .collect(),
            areas: closure
                .areas
                .iter()
                .filter_map(|&id| Some((id, doc.area(&id)?.clone())))
                .collect(),
            assets: payloads(doc, referenced),
            blocks,
            images,
        }
    }

    /// The top-left corner of what a paste would *drop*: the roots — the
    /// entities whose owner did not travel with them. The nested structure
    /// inside a copied block rides that block, so it never widens the box
    /// the drop is aligned by.
    pub fn origin(&self) -> Option<GridPoint> {
        let carried: HashSet<BlockId> = self.blocks.iter().map(|(id, _)| *id).collect();
        let root = |owner: &BlockId| !carried.contains(owner);
        let corners = self
            .blocks
            .iter()
            .filter(|(_, init)| root(&init.parent))
            .map(|(_, init)| init.rect.top_left)
            .chain(
                self.pins
                    .iter()
                    .filter(|(_, init)| root(&init.owner))
                    .map(|(_, init)| init.rect.top_left),
            )
            .chain(
                self.texts
                    .iter()
                    .filter(|(_, init)| root(&init.owner))
                    .map(|(_, init)| init.pos),
            )
            .chain(
                self.areas
                    .iter()
                    .filter(|(_, init)| root(&init.owner))
                    .map(|(_, init)| init.rect.top_left),
            )
            .chain(
                self.images
                    .iter()
                    .filter(|(_, init)| root(&init.owner))
                    .map(|(_, init)| grid_point(artwork_rect(init.rect).min)),
            );
        corners.reduce(|a, b| GridPoint {
            x: a.x.min(b.x),
            y: a.y.min(b.y),
        })
    }

    pub fn is_empty(&self) -> bool {
        self.blocks.is_empty()
            && self.pins.is_empty()
            && self.routes.is_empty()
            && self.texts.is_empty()
            && self.areas.is_empty()
            && self.images.is_empty()
    }
}

/// Which gesture made a payload, and — for a cut — the document it was
/// taken out of.
///
/// A cut is the only payload whose ids a paste may keep, and only where it
/// has come home: the ids in a snapshot from *another* document name
/// entities that document minted, and re-creating them here would plant a
/// foreign numbering in a document that never issued it. Every
/// cross-document flow re-mints (`docs/log-vs-snapshot.md` §5.1), and this
/// is what keeps that true now that "deleted" and "never here" are one
/// state.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
pub enum Origin {
    Copy,
    Cut { from: DocumentNonce },
}

/// The clipboard payload, versioned per variant: a payload from a newer
/// build fails to deserialize here rather than being reinterpreted, and
/// clipboard text that is not ours at all refuses the same way — which is
/// what keeps an ordinary text paste from being read as a diagram.
///
/// The two live variants are the same snapshot under different *gestures*:
/// a shape copy lands its roots where they are dropped, a pin copy slots
/// its pins onto a boundary. Which one a payload is cannot be read off its
/// contents — copying a lone boundary port yields a snapshot of exactly one
/// pin either way — so the copy that made it says so here.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub enum Clipboard {
    V2 { snapshot: Snapshot, origin: Origin },
    PinsV2 { snapshot: Snapshot, origin: Origin },
}

impl Clipboard {
    /// The OS clipboard carries text, so the payload travels as JSON.
    /// `None` only where the payload cannot be written at all.
    pub fn to_json(&self) -> Option<String> {
        serde_json::to_string(self).ok()
    }

    /// `None` for anything that is not one of our payloads: unrelated
    /// text, a truncated blob, or a version this build does not know.
    pub fn from_json(text: &str) -> Option<Self> {
        serde_json::from_str(text).ok()
    }

    pub fn snapshot(&self) -> &Snapshot {
        match self {
            Clipboard::V2 { snapshot, .. } | Clipboard::PinsV2 { snapshot, .. } => snapshot,
        }
    }

    pub fn origin(&self) -> Origin {
        match self {
            Clipboard::V2 { origin, .. } | Clipboard::PinsV2 { origin, .. } => *origin,
        }
    }

    /// The same payload read as a pin copy — what a pin selection's copy or
    /// cut hands the OS clipboard.
    #[must_use]
    pub fn into_pins(self) -> Self {
        match self {
            Clipboard::V2 { snapshot, origin } | Clipboard::PinsV2 { snapshot, origin } => {
                Clipboard::PinsV2 { snapshot, origin }
            }
        }
    }

    /// Whether a paste of this payload slots pins onto a boundary rather
    /// than dropping shapes at the paste target.
    pub fn is_pin_paste(&self) -> bool {
        matches!(self, Clipboard::PinsV2 { .. })
    }
}

/// The bytes behind the hashes the copies reference, each carried once —
/// a payload the document does not hold cannot travel, and its reference
/// pastes as the "no artwork" zero it already is.
fn payloads(doc: &Document, hashes: impl Iterator<Item = AssetHash>) -> Vec<Asset> {
    let mut carried: Vec<AssetHash> = hashes.collect();
    carried.sort_unstable();
    carried.dedup();
    carried
        .iter()
        .filter_map(|hash| doc.asset(hash).cloned())
        .collect()
}

/// Inventory rows "Paste" / "Cut Selection"'s read half: the value
/// snapshot of a selection, taken from the same closure a delete cascades
/// over (`delete::Closure`) — so a copied block brings its subtree, the
/// wires landing on any of their pins with their labels, and the
/// annotations they own.
pub fn copy(indexed: &IndexedDocument<'_>, targets: &[Target]) -> Clipboard {
    Clipboard::V2 {
        snapshot: Snapshot::of(indexed.doc, &Closure::of(indexed, targets)),
        origin: Origin::Copy,
    }
}

/// Cut: the snapshot and the cascade delete in one commit.
///
/// What the delete declines — a pin whose owner froze its interface — the
/// copy declines too, which is why this walks the delete's own closure
/// rather than [`copy`]'s. A cut that left something on the clipboard it
/// also left in the document would make the next paste read a mix of held
/// and departed sources, and duplicate where the user asked for a move.
pub fn cut(
    indexed: &IndexedDocument<'_>,
    targets: &[Target],
    from: DocumentNonce,
    builder: &mut CommitBuilder,
) -> Clipboard {
    let cascade = closure(indexed, targets);
    let snapshot = Snapshot::of(indexed.doc, &cascade);
    cascade.push_deletes(builder);
    Clipboard::V2 {
        snapshot,
        origin: Origin::Cut { from },
    }
}

/// Where a paste lands: the scope its roots join, and the whole-cell delta
/// the drop applies to them.
#[derive(Clone, Copy, Debug)]
pub struct PasteTarget {
    pub scope: Scope,
    pub offset: GridVec,
}

/// One paste gesture — the payload, the session document it is landing
/// in, and where in that document it lands. Bundled because the emitter's
/// other three parameters are the document, the id source, and the
/// builder.
#[derive(Clone, Copy, Debug)]
pub struct Paste<'a> {
    pub clip: &'a Clipboard,
    /// The document being pasted into, which is what a cut payload
    /// compares itself against ([`Origin`]).
    pub into: DocumentNonce,
    pub target: PasteTarget,
}

/// The Paste Pins gesture: copied pins, and the block whose boundary they
/// join.
#[derive(Clone, Copy, Debug)]
pub struct PinPaste<'a> {
    pub pins: &'a [(PinId, Pin)],
    pub owner: Scope,
}

/// Which paste this is. Two questions, and a move needs both answered:
/// the payload must be the *cut this document made* ([`Origin`]), and
/// every source it names must still be gone from it — a source standing
/// again is a second paste of that cut, and duplicates.
///
/// A document that keeps no tombstones cannot tell "here but dead" from
/// "not here at all", so the payload carries which document it came out
/// of and the paste believes it or mints.
///
/// A partial state (some gone, some standing) duplicates **wholesale**,
/// never a mixed move: half a snapshot re-created and half re-minted would
/// wire a copied route across one original endpoint and one duplicate.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Mode {
    Move,
    Duplicate,
}

fn mode(doc: &Document, clip: &Clipboard, into: DocumentNonce) -> Mode {
    let Origin::Cut { from } = clip.origin() else {
        return Mode::Duplicate;
    };
    let snapshot = clip.snapshot();
    let gone_from_here = from == into
        && snapshot
            .blocks
            .iter()
            .all(|(id, _)| doc.block(id).is_none())
        && snapshot.pins.iter().all(|(id, _)| doc.pin(id).is_none())
        && snapshot
            .routes
            .iter()
            .all(|(id, _)| doc.route(id).is_none())
        && snapshot
            .labels
            .iter()
            .all(|(id, _)| doc.route_label(id).is_none())
        && snapshot.texts.iter().all(|(id, _)| doc.text(id).is_none())
        && snapshot.areas.iter().all(|(id, _)| doc.area(id).is_none())
        && snapshot
            .images
            .iter()
            .all(|(id, _)| doc.image(id).is_none());
    if gone_from_here {
        Mode::Move
    } else {
        Mode::Duplicate
    }
}

/// Where one copied entity lands.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Landing {
    /// Inside the structure that carried it — a nested interior travels
    /// with its parent, so nothing of it shifts.
    Carried(BlockId),
    /// At the target scope, as a root of the paste, riding the drop
    /// offset.
    Root,
}

impl Landing {
    fn of(carried: Option<BlockId>) -> Self {
        carried.map_or(Landing::Root, Landing::Carried)
    }

    fn owner(self, target: PasteTarget) -> Scope {
        match self {
            Landing::Carried(owner) => Scope::Block(owner),
            Landing::Root => target.scope,
        }
    }

    fn shift(self, target: PasteTarget) -> GridVec {
        match self {
            Landing::Carried(_) => GridVec::ZERO,
            Landing::Root => target.offset,
        }
    }
}

fn translated(waypoints: &[Waypoint], shift: GridVec) -> Vec<Waypoint> {
    waypoints
        .iter()
        .map(|wp| Waypoint {
            pos: wp.pos + shift,
            ..*wp
        })
        .collect()
}

fn shifted_artwork(rect: ScreenRect, delta: Vec2) -> ScreenRect {
    screen_rect(artwork_rect(rect).translate(delta))
}

/// A copied icon at the paste offset; the zero icon is no artwork, so it
/// has no box to carry.
fn pasted_icon(icon: &Icon, delta: Vec2) -> Icon {
    artwork(icon).map_or_else(Icon::default, |icon| shifted_icon(icon, delta))
}

/// The boundary a paste slots pins onto: the slots the owner's pins hold,
/// plus the ones this gesture has handed out, and the growth that keeps
/// the block tall enough for them — the 10c policy
/// ([`first_free_slot`], [`grown_to_fit`]) driven by a whole group rather
/// than one stamp. A block the document does not hold, or one whose
/// interface is frozen, offers no slots at all.
struct Boundary<'a> {
    scope: Scope,
    block: Option<&'a Block>,
    occupied: HashSet<PinSlot>,
    last: Option<PinSlot>,
}

impl<'a> Boundary<'a> {
    fn of(indexed: &'a IndexedDocument<'a>, scope: Scope) -> Self {
        Self {
            scope,
            block: indexed
                .doc
                .block(&scope.wire_id())
                .filter(|block| !block.locked),
            occupied: owner_pins(indexed, scope).map(|pin| pin.slot).collect(),
            last: None,
        }
    }

    /// The boundary of a block this same commit is creating: it has no row
    /// in the index to be found by, and nothing stands on it yet.
    fn fresh(scope: Scope, block: &'a Block) -> Self {
        Self {
            scope,
            block: Some(block),
            occupied: HashSet::default(),
            last: None,
        }
    }

    fn take(&mut self) -> Option<PinSlot> {
        self.block?;
        let slot = first_free_slot(&self.occupied);
        self.occupied.insert(slot);
        self.last = Some(slot);
        Some(slot)
    }

    /// The growth rider, once for the whole group: the search hands out
    /// slots in ascending order, so the last one taken is the lowest the
    /// block has to reach.
    fn push_growth(&self, builder: &mut CommitBuilder) {
        let (Some(block), Some(slot)) = (self.block, self.last) else {
            return;
        };
        if let Some(rect) = grown_to_fit(block, slot) {
            builder.push(OpCodes::Block(
                self.scope.wire_id(),
                Crud::Update(BlockUpdate::Rect(rect)),
            ));
        }
    }
}

/// Inventory row "Paste": insert a snapshot at the target scope, as a
/// move or as a duplicate (`Mode`). Returns the roots — what the caller
/// selects — leaving the nested structure that travelled inside them
/// unnamed.
pub fn paste(
    indexed: &IndexedDocument<'_>,
    paste: Paste<'_>,
    fresh: &mut Allocator,
    builder: &mut CommitBuilder,
) -> Vec<Shape> {
    let naming = match mode(indexed.doc, paste.clip, paste.into) {
        Mode::Move => Naming::Keep,
        Mode::Duplicate => Naming::Mint(fresh),
    };
    let boundary = Boundary::of(indexed, paste.target.scope);
    let insertion = Insertion {
        clip: paste.clip,
        target: paste.target,
    };
    insert(indexed, insertion, naming, boundary, builder)
}

/// Paste into a block this same commit is creating — what an embedded
/// document lands in ([`crate::edit::embed`]).
///
/// The scope has no row in the index to find a boundary by, so the one its
/// root ports slot onto is the fresh block's own: empty, and grown to fit
/// what lands on it. Looking it up the way [`paste`] does would find no
/// block, hand out no slot, and drop every port the document carried.
///
/// Always re-mints. A snapshot reaching a scope that does not exist yet came
/// from another document, and every cross-document flow re-mints
/// ([`Origin`]).
pub fn paste_into_fresh(
    indexed: &IndexedDocument<'_>,
    clip: &Clipboard,
    scope: FreshScope<'_>,
    fresh: &mut Allocator,
    builder: &mut CommitBuilder,
) -> Vec<Shape> {
    let target = PasteTarget {
        scope: Scope::Block(scope.id),
        offset: GridVec::ZERO,
    };
    insert(
        indexed,
        Insertion { clip, target },
        Naming::Mint(fresh),
        Boundary::fresh(target.scope, scope.block),
        builder,
    )
}

/// The block a paste lands in that this same commit is creating: its id, and
/// the value being created under it. Both, because the index has no row to
/// look the second up by yet.
#[derive(Clone, Copy, Debug)]
pub struct FreshScope<'a> {
    pub id: BlockId,
    pub block: &'a Block,
}

/// A payload and where it lands — a [`Paste`] with the document it is
/// landing in left off, that being the move-or-duplicate question and
/// answered before anything is inserted.
#[derive(Clone, Copy, Debug)]
struct Insertion<'a> {
    clip: &'a Clipboard,
    target: PasteTarget,
}

/// How a paste names what it inserts. Keeping the ids is what makes a
/// cut and its paste one displacement rather than a deletion and an
/// unrelated arrival: the entity that comes back is the entity that left,
/// so an undo of either half addresses the same thing. Minting is the
/// copying half, and every reference inside the snapshot is remapped onto
/// the mint.
enum Naming<'a> {
    Keep,
    Mint(&'a mut Allocator),
}

impl Naming<'_> {
    fn name<K: IdKind>(&mut self, source: Id<K>) -> Id<K> {
        match self {
            Naming::Keep => source,
            Naming::Mint(fresh) => fresh.mint(),
        }
    }

    /// The endpoint a pasted wire lands on: the pin this paste made from
    /// the one it was drawn to, or — where the ids are kept — the pin it
    /// already names, which the document may still hold outside the
    /// snapshot. `None` leaves the wire nothing to land on.
    fn endpoint(&self, doc: &Document, pasted: Option<PinId>, source: PinId) -> Option<PinId> {
        match self {
            Naming::Keep => pasted.or_else(|| doc.pin(&source).map(|_| source)),
            Naming::Mint(_) => pasted,
        }
    }

    /// The slot a pasted pin takes. It keeps the one it carried unless it
    /// is a *copy* joining the target boundary, which has to find room
    /// among the pins already there.
    fn slot(
        &self,
        landing: Landing,
        carried: PinSlot,
        boundary: &mut Boundary<'_>,
    ) -> Option<PinSlot> {
        match (self, landing) {
            (Naming::Mint(_), Landing::Root) => boundary.take(),
            _ => Some(carried),
        }
    }
}

/// One paste, both halves ([`Naming`]): every entity re-created at its
/// landing, the roots re-pointed at the target scope and shifted by the
/// drop.
fn insert(
    indexed: &IndexedDocument<'_>,
    insertion: Insertion<'_>,
    mut naming: Naming<'_>,
    mut boundary: Boundary<'_>,
    builder: &mut CommitBuilder,
) -> Vec<Shape> {
    let Insertion { clip, target } = insertion;
    let snapshot = clip.snapshot();
    let doc = indexed.doc;
    let mut roots = Vec::new();

    for asset in &snapshot.assets {
        push_payload(doc, asset, builder);
    }

    // Ancestors first (the closure's own order), so a child's parent is
    // always named by the time the child needs it.
    let mut blocks: HashMap<BlockId, BlockId> = HashMap::new();
    for (src, init) in &snapshot.blocks {
        let landing = Landing::of(blocks.get(&init.parent).copied());
        let shift = landing.shift(target);
        let id = naming.name(*src);
        blocks.insert(*src, id);
        if landing == Landing::Root {
            roots.push(Shape::Block(id));
        }
        builder.push(OpCodes::Block(
            id,
            Crud::Create(Block {
                parent: landing.owner(target).wire_id(),
                rect: init.rect.translate(shift),
                icon: pasted_icon(&init.icon, px_vec(shift)),
                ..init.clone()
            }),
        ));
    }

    let mut pins: HashMap<PinId, PinId> = HashMap::new();
    for (src, init) in &snapshot.pins {
        let landing = Landing::of(blocks.get(&init.owner).copied());
        let Some(slot) = naming.slot(landing, init.slot, &mut boundary) else {
            continue;
        };
        let id = naming.name(*src);
        pins.insert(*src, id);
        if landing == Landing::Root {
            roots.push(Shape::Port(id));
        }
        builder.push(OpCodes::Pin(
            id,
            Crud::Create(Pin {
                owner: landing.owner(target).wire_id(),
                rect: init.rect.translate(landing.shift(target)),
                slot,
                ..init.clone()
            }),
        ));
    }
    boundary.push_growth(builder);

    let mut routes: HashMap<RouteId, RouteId> = HashMap::new();
    for (src, init) in &snapshot.routes {
        // An endpoint the paste did not carry leaves the wire nothing to
        // land on, so the wire is dropped and its labels with it.
        let (Some(from), Some(to)) = (
            naming.endpoint(doc, pins.get(&init.from).copied(), init.from),
            naming.endpoint(doc, pins.get(&init.to).copied(), init.to),
        ) else {
            continue;
        };
        let landing = Landing::of(blocks.get(&init.owner).copied());
        let id = naming.name(*src);
        routes.insert(*src, id);
        builder.push(OpCodes::Route(
            id,
            Crud::Create(Route {
                owner: landing.owner(target).wire_id(),
                from,
                to,
                waypoints: translated(&init.waypoints, landing.shift(target)),
                ..init.clone()
            }),
        ));
    }
    report_omissions(snapshot, pins.len(), routes.len());

    for (src, init) in &snapshot.labels {
        let Some(owner) = routes.get(&init.owner).copied() else {
            continue;
        };
        builder.push(OpCodes::RouteLabel(
            naming.name(*src),
            Crud::Create(RouteLabel { owner, ..*init }),
        ));
    }

    for (src, init) in &snapshot.texts {
        let landing = Landing::of(blocks.get(&init.owner).copied());
        let id = naming.name(*src);
        if landing == Landing::Root {
            roots.push(Shape::Text(id));
        }
        builder.push(OpCodes::Text(
            id,
            Crud::Create(Text {
                owner: landing.owner(target).wire_id(),
                pos: init.pos + landing.shift(target),
                ..init.clone()
            }),
        ));
    }

    for (src, init) in &snapshot.areas {
        let landing = Landing::of(blocks.get(&init.owner).copied());
        let id = naming.name(*src);
        if landing == Landing::Root {
            roots.push(Shape::Area(id));
        }
        builder.push(OpCodes::Area(
            id,
            Crud::Create(Area {
                owner: landing.owner(target).wire_id(),
                rect: init.rect.translate(landing.shift(target)),
                ..init.clone()
            }),
        ));
    }

    for (src, init) in &snapshot.images {
        let landing = Landing::of(blocks.get(&init.owner).copied());
        let id = naming.name(*src);
        if landing == Landing::Root {
            roots.push(Shape::Image(id));
        }
        builder.push(OpCodes::Image(
            id,
            Crud::Create(Image {
                owner: landing.owner(target).wire_id(),
                rect: shifted_artwork(init.rect, px_vec(landing.shift(target))),
                ..*init
            }),
        ));
    }

    roots
}

/// What a duplicate could not rebuild: a pin the target boundary had no
/// room for, and a wire whose other endpoint the copy did not carry. Both
/// are legitimate — there is nothing to land them on — but a paste that
/// quietly delivers less than was copied is indistinguishable from one that
/// lost it, so it says so.
fn report_omissions(snapshot: &Snapshot, pins: usize, routes: usize) {
    if pins == snapshot.pins.len() && routes == snapshot.routes.len() {
        return;
    }
    tracing::warn!(
        "paste landed {pins} of {} pins and {routes} of {} wires: the rest name a boundary \
         or an endpoint that did not travel with them",
        snapshot.pins.len(),
        snapshot.routes.len(),
    );
}

/// Paste pins: copied pins join `owner`'s boundary, each at the next free
/// slot, growing the block until they fit. A frozen interface takes none of
/// them.
pub fn paste_pins(
    indexed: &IndexedDocument<'_>,
    onto: PinPaste<'_>,
    fresh: &mut Allocator,
    builder: &mut CommitBuilder,
) -> Vec<PinId> {
    let mut boundary = Boundary::of(indexed, onto.owner);
    let mut pasted = Vec::new();
    for (_, init) in onto.pins {
        let Some(slot) = boundary.take() else {
            break;
        };
        let id = fresh.mint();
        pasted.push(id);
        builder.push(OpCodes::Pin(
            id,
            Crud::Create(Pin {
                owner: onto.owner.wire_id(),
                slot,
                ..init.clone()
            }),
        ));
    }
    boundary.push_growth(builder);
    pasted
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::edit::delete;
    use crate::edit::harness::{
        area_create, block_create, fold, image_create, pin_create, route_create,
        route_label_create, seals_to_nothing, text_create, wired,
    };
    use crate::grid::GRID_SIZE;
    use blockworx_doc::document::DocIndex;
    use blockworx_doc::{
        block_model::{ImageUpdate, LabelUpdate, PinUpdate, RouteUpdate},
        document::Document,
        fixtures::{area_id, block_id, image_id, pin_id, route_id, route_label_id, text_id},
        geometry::{GridPoint, GridRect, GridSize, ScreenPoint, ScreenSize},
        values::{PinDir, PinSide, Role},
    };

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

    fn artwork_box(x: f32, y: f32) -> ScreenRect {
        ScreenRect {
            top_left: ScreenPoint {
                x: x.into(),
                y: y.into(),
            },
            size: ScreenSize {
                w: 20.0.into(),
                h: 10.0.into(),
            },
        }
    }

    fn svg(source: &str) -> Asset {
        Asset::Svg(source.as_bytes().into())
    }

    fn empty() -> Document {
        Document::default()
    }

    fn rename(id: u32, name: &str) -> OpCodes {
        OpCodes::Block(
            block_id(id),
            Crud::Update(BlockUpdate::Title(LabelUpdate::Name(name.into()))),
        )
    }

    fn resize(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 reslot(id: u32, to: PinSlot) -> OpCodes {
        OpCodes::Pin(pin_id(id), Crud::Update(PinUpdate::Slot(to)))
    }

    fn rename_pin(id: u32, name: &str) -> OpCodes {
        OpCodes::Pin(pin_id(id), Crud::Update(PinUpdate::Name(name.into())))
    }

    fn waypoints(id: u32, corners: &[(i32, i32)]) -> OpCodes {
        OpCodes::Route(
            route_id(id),
            Crud::Update(RouteUpdate::Waypoints(
                corners
                    .iter()
                    .map(|&(x, y)| Waypoint {
                        pos: GridPoint { x, y },
                        locked: true,
                    })
                    .collect(),
            )),
        )
    }

    /// Block 1 at top level with pins 3 (west) and 4 (east), wire 5
    /// between them carrying label 20, text 7, area 8; block 2 nested
    /// inside it with pins 10 and 11, wire 12 between them (with a
    /// hand-placed corner), text 14, area 15 and image 9. Every name is
    /// distinct, so a projection can name a wire's endpoints and prove a
    /// remap.
    fn scene() -> Document {
        let doc = wired();
        let mut builder = CommitBuilder::new("Furnished two levels");
        builder.extend([
            block_create(2),
            reparent(2, 1),
            pin_create(10, 2),
            pin_create(11, 2),
            route_create(12, 2, 10, 11),
            text_create(14, 2),
            area_create(15, 2),
            image_create(9, 2),
            route_label_create(20, 5),
            route_label_create(21, 12),
            rename(1, "outer"),
            rename(2, "inner"),
            resize(1, rect(0, 0, 10, 10)),
            resize(2, rect(2, 2, 4, 4)),
            reslot(3, slot(PinSide::West, 0)),
            reslot(4, slot(PinSide::East, 0)),
            reslot(10, slot(PinSide::West, 1)),
            reslot(11, slot(PinSide::East, 1)),
            waypoints(5, &[(3, 3)]),
            waypoints(12, &[(4, 4)]),
        ]);
        let doc = fold(builder, &doc);
        assert_eq!(
            doc.block(&block_id(2))
                .expect("the nested block exists")
                .parent,
            block_id(1),
            "precondition: the scene really nests"
        );
        doc
    }

    /// What a subtree looks like with its ids taken away: the values, and
    /// the structure named by the values (a wire by its endpoints' names,
    /// a child by its title). Two subtrees compare equal exactly when one
    /// is a faithful copy of the other.
    #[derive(Debug, PartialEq)]
    struct Projection {
        title: String,
        rect: GridRect,
        locked: bool,
        role: Role,
        icon: Icon,
        pins: Vec<(String, PinSlot, GridRect, PinDir)>,
        routes: Vec<(String, String, String, Vec<Waypoint>)>,
        texts: Vec<(String, GridPoint)>,
        areas: Vec<(String, GridRect)>,
        images: Vec<(AssetHash, ScreenRect)>,
        children: Vec<Projection>,
    }

    fn pin_name(doc: &Document, id: PinId) -> String {
        doc.pin(&id)
            .map(|live| live.name.clone())
            .unwrap_or_default()
    }

    fn project(indexed: &IndexedDocument<'_>, id: BlockId) -> Projection {
        let block = indexed.doc.block(&id).expect("the projected block exists");
        let entry = &indexed.index.blocks[&id];
        let mut pins: Vec<(String, PinSlot, GridRect, PinDir)> = entry
            .pins
            .iter()
            .filter_map(|id| indexed.doc.pin(id))
            .map(|pin| (pin.name.clone(), pin.slot, pin.rect, pin.dir))
            .collect();
        pins.sort_by(|a, b| a.0.cmp(&b.0));
        let mut routes: Vec<(String, String, String, Vec<Waypoint>)> = entry
            .routes
            .iter()
            .filter_map(|id| indexed.doc.route(id))
            .map(|route| {
                (
                    route.name.clone(),
                    pin_name(indexed.doc, route.from),
                    pin_name(indexed.doc, route.to),
                    route.waypoints.clone(),
                )
            })
            .collect();
        routes.sort_by(|a, b| (&a.1, &a.2).cmp(&(&b.1, &b.2)));
        let mut texts: Vec<(String, GridPoint)> = entry
            .texts
            .iter()
            .filter_map(|id| indexed.doc.text(id))
            .map(|text| (text.text.clone(), text.pos))
            .collect();
        texts.sort_by(|a, b| a.0.cmp(&b.0));
        let mut areas: Vec<(String, GridRect)> = entry
            .areas
            .iter()
            .filter_map(|id| indexed.doc.area(id))
            .map(|area| (area.title.name.clone(), area.rect))
            .collect();
        areas.sort_by(|a, b| a.0.cmp(&b.0));
        let mut images: Vec<(AssetHash, ScreenRect)> = entry
            .images
            .iter()
            .filter_map(|id| indexed.doc.image(id))
            .map(|image| (image.asset, image.rect))
            .collect();
        images.sort_by_key(|(asset, _)| *asset);
        let mut children: Vec<Projection> = entry
            .children
            .iter()
            .map(|&child| project(indexed, child))
            .collect();
        children.sort_by(|a, b| a.title.cmp(&b.title));
        Projection {
            title: block.title.name.clone(),
            rect: block.rect,
            locked: block.locked,
            role: block.role,
            icon: block.icon.clone(),
            pins,
            routes,
            texts,
            areas,
            images,
            children,
        }
    }

    fn only_block(roots: &[Shape]) -> BlockId {
        match roots {
            [Shape::Block(id)] => *id,
            other => unreachable!("expected exactly one pasted block, got {other:?}"),
        }
    }

    /// The allocator a paste mints from: the *target* document's marks,
    /// which is what the gesture hands the emitter in the editor.
    fn ids(target: &Document) -> Allocator {
        target.ids()
    }

    /// The session document these probes cut from and paste into — one
    /// value for the whole module, so a probe that wants a *different*
    /// document says so by minting one of its own.
    fn home() -> DocumentNonce {
        static HOME: std::sync::OnceLock<DocumentNonce> = std::sync::OnceLock::new();
        *HOME.get_or_init(DocumentNonce::mint)
    }

    fn drop_at(scope: Scope, dx: i32, dy: i32) -> PasteTarget {
        PasteTarget {
            scope,
            offset: GridVec::new(dx, dy),
        }
    }

    /// The round trip the format exists for: a copied subtree pastes into
    /// a document that has never seen it as the same subtree — new ids,
    /// same everything else, shifted by the drop.
    #[test]
    fn a_copy_pastes_into_an_empty_document_as_the_same_subtree() {
        let source = scene();
        let mut index = DocIndex::default();
        let clip = copy(&index.view(&source), &[delete::Target::Block(block_id(1))]);
        let json = clip.to_json().expect("the payload serializes");
        let clip = Clipboard::from_json(&json).expect("its own payload parses");

        let target = empty();
        let mut builder = CommitBuilder::new("Pasted a subtree");
        let roots = paste(
            &index.view(&target),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 5, 7),
            },
            &mut ids(&target),
            &mut builder,
        );
        let target = fold(builder, &target);

        let root = only_block(&roots);
        assert_eq!(
            root,
            block_id(1),
            "the ids are the empty target's own, counted from 1 — that they \
             coincide with the source's is what an unrelated document means",
        );
        let pasted = project(&index.view(&target), root);
        let expected = project(&index.view(&source), block_id(1));
        assert_eq!(
            pasted,
            Projection {
                rect: expected.rect.translate(GridVec::new(5, 7)),
                ..expected
            },
            "the paste is the source subtree modulo ids and the drop offset"
        );
        assert_eq!(
            pasted.children.len(),
            1,
            "the fixture must nest, or the subtree walk proves nothing"
        );
    }

    /// A nested block travels inside its parent's interior, which did not
    /// move: only the roots ride the drop.
    #[test]
    fn only_the_roots_of_a_paste_ride_the_drop_offset() {
        let source = scene();
        let mut index = DocIndex::default();
        let clip = copy(&index.view(&source), &[delete::Target::Block(block_id(1))]);

        let target = empty();
        let mut builder = CommitBuilder::new("Pasted a subtree");
        let roots = paste(
            &index.view(&target),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 5, 7),
            },
            &mut ids(&target),
            &mut builder,
        );
        let target = fold(builder, &target);
        let pasted = project(&index.view(&target), only_block(&roots));

        assert_eq!(pasted.rect, rect(5, 7, 10, 10), "the root rode the drop");
        assert_eq!(
            pasted.children[0].rect,
            rect(2, 2, 4, 4),
            "the nested block kept its place inside the parent that moved"
        );
        assert_eq!(
            pasted.children[0].routes[0].3,
            vec![Waypoint {
                pos: GridPoint { x: 4, y: 4 },
                locked: true,
            }],
            "a nested wire's corners are interior coordinates and did not shift"
        );
        assert_eq!(
            pasted.routes[0].3,
            vec![Waypoint {
                pos: GridPoint { x: 3, y: 3 },
                locked: true,
            }],
            "the root's own interior did not move either — only its rect did"
        );
    }

    /// Two siblings wired at their parent's level: copying both carries
    /// the wire, which lands at the target scope and so takes its corners
    /// along.
    fn siblings() -> Document {
        let doc = scene();
        let mut builder = CommitBuilder::new("Wired two siblings");
        builder.extend([
            block_create(40),
            reparent(40, 1),
            resize(40, rect(0, 0, 4, 4)),
            block_create(41),
            reparent(41, 1),
            resize(41, rect(8, 0, 4, 4)),
            pin_create(42, 40),
            pin_create(43, 41),
            route_create(44, 1, 42, 43),
            waypoints(44, &[(6, 2)]),
        ]);
        fold(builder, &doc)
    }

    #[test]
    fn a_wire_landing_at_the_target_scope_takes_its_corners_along() {
        let doc = siblings();
        let mut index = DocIndex::default();
        let clip = copy(
            &index.view(&doc),
            &[
                delete::Target::Block(block_id(40)),
                delete::Target::Block(block_id(41)),
            ],
        );
        assert_eq!(
            clip.snapshot().routes.len(),
            1,
            "precondition: the wire between the copied siblings came along"
        );
        assert_eq!(
            clip.snapshot().routes[0].1.owner,
            block_id(1),
            "precondition: the wire is owned outside the copy, so it lands at the target"
        );

        let mut builder = CommitBuilder::new("Pasted two wired blocks");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Block(block_id(2)), 5, 7),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(roots.len(), 2, "both siblings pasted");
        let indexed = index.view(&doc);
        // The destination owns a wire of its own; the copy is the other.
        let landed: Vec<RouteId> = indexed.index.blocks[&block_id(2)]
            .routes
            .iter()
            .copied()
            .filter(|id| *id != route_id(12))
            .collect();
        let [wire] = landed[..] else {
            unreachable!("exactly one wire landed in the target scope: {landed:?}");
        };
        let route = doc.route(&wire).expect("the pasted wire");
        assert_eq!(
            route.waypoints,
            vec![Waypoint {
                pos: GridPoint { x: 11, y: 9 },
                locked: true,
            }],
            "the corners rode the same delta the blocks did"
        );
    }

    /// Cut then paste is a *move*: the entities come back under their own
    /// ids, so the gesture reads as one displacement — and the commit proves
    /// it, minting nothing.
    #[test]
    fn a_cut_and_paste_moves_the_originals_instead_of_recreating_them() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut host = CommitBuilder::new("Added a destination");
        host.push(block_create(30));
        let doc = fold(host, &doc);

        let mut builder = CommitBuilder::new("Cut a subtree");
        let clip = cut(
            &index.view(&doc),
            &[delete::Target::Block(block_id(1))],
            home(),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert!(
            doc.block(&block_id(1)).is_none(),
            "precondition: the cut removed the source"
        );

        let mut builder = CommitBuilder::new("Pasted a subtree");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Block(block_id(30)), 2, 2),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let commit = builder.seal().expect("the move produced ops");
        assert!(
            commit
                .ops()
                .iter()
                .any(|op| matches!(op, OpCodes::Block(id, Crud::Create(_)) if *id == block_id(1))),
            "the moved subtree's own root comes back under its own id"
        );
        assert!(
            !commit.ops().iter().any(|op| matches!(
                op,
                OpCodes::Block(id, _) if *id == block_id(31)
            )),
            "a move mints nothing: {:?}",
            commit.ops()
        );
        let doc = doc.try_apply(&commit).expect("the move folds");

        assert_eq!(
            roots,
            vec![Shape::Block(block_id(1))],
            "the move hands back the ids it moved"
        );
        for id in [block_id(1), block_id(2)] {
            assert!(doc.block(&id).is_some(), "{id} is back under its own id");
        }
        let root = doc.block(&block_id(1)).expect("the root");
        assert_eq!(
            root.parent,
            block_id(30),
            "the move lands its roots in the target scope"
        );
        assert_eq!(root.rect, rect(2, 2, 10, 10), "the drop applied");
        assert_eq!(
            doc.block(&block_id(2)).expect("the child").parent,
            block_id(1),
            "the nested structure kept its own chain"
        );
        assert!(
            doc.route(&route_id(5)).is_some() && doc.route_label(&route_label_id(20)).is_some(),
            "the wires and labels the cut took come back with it"
        );
    }

    /// Every cross-document flow re-mints, and the absence check alone
    /// cannot keep that true: a cut carried to another document names ids
    /// that document is not using either. The payload says which document
    /// it came out of, and a paste anywhere else duplicates however free
    /// the ids look.
    #[test]
    fn a_cut_pasted_into_another_document_duplicates() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Cut a subtree");
        let clip = cut(
            &index.view(&doc),
            &[delete::Target::Block(block_id(1))],
            home(),
            &mut builder,
        );

        // A document that has held — and deleted — blocks up to `b5`: the
        // payload's own ids are absent from it *and* below its marks, so
        // the absence check passes and only the origin can refuse.
        let elsewhere = blockworx_doc::fixtures::commit(
            "Built and cleared another document",
            (1..=5)
                .map(block_create)
                .chain((1..=5).map(|n| OpCodes::Block(block_id(n), Crud::Delete)))
                .collect(),
        );
        let elsewhere = Document::default()
            .try_apply(&elsewhere)
            .expect("the other document folds");
        assert!(
            clip.snapshot()
                .blocks
                .iter()
                .all(|(id, _)| elsewhere.block(id).is_none()),
            "precondition: no source id collides, so only the payload's origin can refuse",
        );

        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Pasted into another document");
        let roots = paste(
            &index.view(&elsewhere),
            Paste {
                clip: &clip,
                into: DocumentNonce::mint(),
                target: drop_at(Scope::Root, 0, 0),
            },
            &mut ids(&elsewhere),
            &mut builder,
        );
        let commit = builder.seal().expect("the paste produced ops");
        assert!(
            !commit
                .ops()
                .iter()
                .any(|op| matches!(op, OpCodes::Block(id, _) if *id == block_id(1))),
            "a foreign cut names none of its source ids: {:?}",
            commit.ops()
        );
        elsewhere
            .try_apply(&commit)
            .expect("the duplicate folds into the other document");
        assert_ne!(only_block(&roots), block_id(1));
    }

    /// The other half of the same rule: a *copy* mints even where its
    /// sources have since left the document, so the discriminator is the
    /// gesture that made the payload rather than what happened afterwards.
    #[test]
    fn a_copy_whose_sources_are_gone_still_duplicates() {
        let doc = scene();
        let mut index = DocIndex::default();
        let clip = copy(&index.view(&doc), &[delete::Target::Block(block_id(1))]);

        let mut builder = CommitBuilder::new("Deleted the copied subtree");
        crate::edit::delete::selection(
            &index.view(&doc),
            &[delete::Target::Block(block_id(1))],
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert!(
            doc.block(&block_id(1)).is_none(),
            "precondition: the copy's sources are gone, as a cut's would be",
        );

        let mut builder = CommitBuilder::new("Pasted the copy");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 0, 0),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let commit = builder.seal().expect("the paste produced ops");
        assert!(
            !commit
                .ops()
                .iter()
                .any(|op| matches!(op, OpCodes::Block(id, _) if *id == block_id(1))),
            "a copy names none of its source ids: {:?}",
            commit.ops()
        );
        assert_ne!(only_block(&roots), block_id(1));
    }

    /// The first paste put the originals back, so the document holds them
    /// again — and a source still standing is a second paste, which
    /// duplicates.
    #[test]
    fn a_second_paste_after_a_move_duplicates() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Cut a subtree");
        let clip = cut(
            &index.view(&doc),
            &[delete::Target::Block(block_id(1))],
            home(),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Pasted a subtree");
        let mut fresh = ids(&doc);
        paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 0, 0),
            },
            &mut fresh,
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert!(
            doc.block(&block_id(1)).is_some(),
            "precondition: the first paste revived the source ids"
        );

        let mut builder = CommitBuilder::new("Pasted it again");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 4, 4),
            },
            &mut fresh,
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let root = only_block(&roots);
        assert_ne!(root, block_id(1), "the second paste minted fresh ids");
        assert!(
            doc.block(&block_id(1)).is_some(),
            "the original stayed where the first paste left it"
        );
        assert_eq!(
            DocIndex::of(&doc).blocks[&Scope::Root.wire_id()].children,
            [block_id(1), root].into_iter().collect(),
            "the level now holds the original and its copy"
        );
    }

    /// Wholesale, never mixed: one source standing again turns the whole
    /// paste into a duplicate, so nothing is half-moved.
    #[test]
    fn a_partially_present_snapshot_duplicates_wholesale() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Cut a subtree");
        let clip = cut(
            &index.view(&doc),
            &[delete::Target::Block(block_id(1))],
            home(),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("A later commit put one block back");
        let (_, nested) = clip
            .snapshot()
            .blocks
            .iter()
            .find(|(id, _)| *id == block_id(2))
            .expect("the cut carried the nested block");
        builder.push(OpCodes::Block(
            block_id(2),
            Crud::Create(Block {
                parent: Scope::Root.wire_id(),
                ..nested.clone()
            }),
        ));
        let doc = fold(builder, &doc);
        assert!(
            doc.block(&block_id(2)).is_some() && doc.block(&block_id(1)).is_none(),
            "precondition: the snapshot's sources are now part present, part gone"
        );

        let mut builder = CommitBuilder::new("Pasted a subtree");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 0, 0),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let commit = builder.seal().expect("the paste produced ops");
        assert!(
            !commit
                .ops()
                .iter()
                .any(|op| matches!(op, OpCodes::Block(id, _) if *id == block_id(1))),
            "a partial state names no source id: {:?}",
            commit.ops()
        );
        let doc = doc.try_apply(&commit).expect("the duplicate folds");

        let root = only_block(&roots);
        assert_ne!(root, block_id(1));
        assert!(
            doc.block(&block_id(1)).is_none(),
            "the source the cut removed stayed gone"
        );
    }

    /// The remap is what a duplicate is for: the copied wire lands on the
    /// copied pins, and the copied label on the copied wire.
    #[test]
    fn a_duplicate_rewires_its_own_copies() {
        let source = scene();
        let mut index = DocIndex::default();
        let clip = copy(&index.view(&source), &[delete::Target::Block(block_id(1))]);

        let mut builder = CommitBuilder::new("Pasted a subtree");
        let roots = paste(
            &index.view(&source),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 20, 0),
            },
            &mut ids(&source),
            &mut builder,
        );
        let doc = fold(builder, &source);

        let root = only_block(&roots);
        let indexed = index.view(&doc);
        let copied_pins = &indexed.index.blocks[&root].pins;
        let copied_routes = &indexed.index.blocks[&root].routes;
        assert_eq!(copied_routes.len(), 1, "the copied level owns one wire");
        let wire = *copied_routes.iter().next().expect("the copied wire");
        let route = doc.route(&wire).expect("the copied wire exists");
        assert!(
            copied_pins.contains(&route.from) && copied_pins.contains(&route.to),
            "the copied wire lands on the copied pins, not the originals"
        );
        assert!(
            ![route.from, route.to].contains(&pin_id(3)),
            "and never on a source id"
        );
        assert_eq!(
            indexed.index.routes[&wire].labels.len(),
            1,
            "the copied label found its copied wire"
        );
    }

    /// A wire whose far endpoint stayed behind has nothing to land on:
    /// dropped, and its labels with it.
    #[test]
    fn a_wire_with_an_uncopied_endpoint_is_dropped_with_its_labels() {
        let doc = scene();
        let mut index = DocIndex::default();
        // Copy only the nested block's pin 10 — wire 12 also lands on pin
        // 11, which stays behind.
        let clip = copy(&index.view(&doc), &[delete::Target::Pin(pin_id(10))]);
        assert_eq!(
            clip.snapshot().routes.len(),
            1,
            "precondition: the closure carried the wire that lands on the copied pin"
        );
        assert_eq!(
            clip.snapshot().labels.len(),
            1,
            "precondition: that wire carries a label"
        );
        assert_eq!(
            clip.snapshot().pins.len(),
            1,
            "precondition: only one of the wire's two endpoints was copied"
        );

        let mut builder = CommitBuilder::new("Pasted a pin");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Block(block_id(2)), 0, 0),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let commit = builder.seal().expect("the paste produced ops");
        assert!(
            commit.ops().iter().all(|op| !matches!(
                op,
                OpCodes::Route(_, Crud::Create(_)) | OpCodes::RouteLabel(_, Crud::Create(_))
            )),
            "the wire and its label vanished with the endpoint that stayed: {:?}",
            commit.ops()
        );
        let doc = doc.try_apply(&commit).expect("the paste folds");
        assert_eq!(roots.len(), 1, "the pin itself still pasted");
        assert_eq!(
            DocIndex::of(&doc).blocks[&block_id(2)].pins.len(),
            3,
            "the destination gained exactly the pasted pin"
        );
    }

    /// The 10e rider through the paste: bytes the target already holds are
    /// referenced, never re-sent, and bytes it lacks travel with the copy.
    #[test]
    fn a_paste_carries_the_payloads_the_target_lacks_and_no_others() {
        let icon = svg("<svg>icon</svg>");
        let mut index = DocIndex::default();
        let picture = svg("<svg>picture</svg>");
        let doc = scene();
        let mut builder = CommitBuilder::new("Dressed the scene");
        builder.extend([
            OpCodes::Asset(icon.hash(), icon.clone()),
            OpCodes::Asset(picture.hash(), picture.clone()),
            OpCodes::Block(
                block_id(1),
                Crud::Update(BlockUpdate::Icon(Icon {
                    asset: icon.hash(),
                    rect: artwork_box(0.0, 0.0),
                })),
            ),
            OpCodes::Image(
                image_id(9),
                Crud::Update(ImageUpdate::Asset(picture.hash())),
            ),
        ]);
        let source = fold(builder, &doc);
        let clip = copy(&index.view(&source), &[delete::Target::Block(block_id(1))]);
        assert_eq!(
            clip.snapshot().assets.len(),
            2,
            "precondition: the copy carries both payloads it references"
        );

        // A destination that already holds the icon's bytes but not the
        // picture's.
        let target = empty();
        let mut builder = CommitBuilder::new("Held one payload already");
        builder.push(OpCodes::Asset(icon.hash(), icon.clone()));
        let target = fold(builder, &target);

        let mut builder = CommitBuilder::new("Pasted a subtree");
        paste(
            &index.view(&target),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Root, 0, 0),
            },
            &mut ids(&target),
            &mut builder,
        );
        let commit = builder.seal().expect("the paste produced ops");
        let payloads: Vec<&OpCodes> = commit
            .ops()
            .iter()
            .filter(|op| matches!(op, OpCodes::Asset(..)))
            .collect();
        assert_eq!(
            payloads,
            [&OpCodes::Asset(picture.hash(), picture.clone())],
            "only the bytes the target lacked travelled"
        );
        let target = target.try_apply(&commit).expect("the paste folds");
        assert!(
            target.asset(&icon.hash()).is_some() && target.asset(&picture.hash()).is_some(),
            "both references resolve in the target"
        );
    }

    /// Pins pasted onto a block take free slots — West before East at each
    /// offset — and the block grows until the last one fits.
    #[test]
    fn pasted_pins_take_free_slots_west_before_east_and_grow_the_block() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Named the pins");
        builder.extend([
            resize(2, rect(2, 2, 4, 4)),
            reslot(10, slot(PinSide::West, 0)),
            reslot(11, slot(PinSide::East, 0)),
            rename_pin(3, "a"),
            rename_pin(4, "b"),
        ]);
        let doc = fold(builder, &doc);
        assert_eq!(
            doc.block(&block_id(2)).expect("the destination").rect.size,
            GridSize { w: 4, h: 4 },
            "precondition: the destination is one slot tall and that slot is full"
        );

        let clip = copy(
            &index.view(&doc),
            &[
                delete::Target::Pin(pin_id(3)),
                delete::Target::Pin(pin_id(4)),
            ],
        );
        let mut builder = CommitBuilder::new("Pasted pins");
        let pasted = paste_pins(
            &index.view(&doc),
            PinPaste {
                pins: &clip.snapshot().pins,
                owner: Scope::Block(block_id(2)),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(pasted.len(), 2, "both pins landed");
        let slots: Vec<(String, PinSlot)> = pasted
            .iter()
            .map(|id| {
                let pin = doc.pin(id).expect("the pasted pin");
                (pin.name.clone(), pin.slot)
            })
            .collect();
        assert_eq!(
            slots,
            vec![
                ("a".to_string(), slot(PinSide::West, 1)),
                ("b".to_string(), slot(PinSide::East, 1)),
            ],
            "the search hands out West before East at the first free offset"
        );
        assert_eq!(
            doc.block(&block_id(2)).expect("the destination").rect.size,
            GridSize { w: 4, h: 8 },
            "one growth rider, sized for the lowest slot the group took"
        );
    }

    /// Legacy `paste_pins_into_block`'s refusal (`src/widget/clipboard.rs:
    /// 605`) and E4's absent target, in one place.
    #[test]
    fn pasting_pins_onto_a_frozen_or_absent_block_pushes_nothing() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Froze the interface");
        builder.push(OpCodes::Block(
            block_id(2),
            Crud::Update(BlockUpdate::Locked(true)),
        ));
        let doc = fold(builder, &doc);
        let clip = copy(&index.view(&doc), &[delete::Target::Pin(pin_id(3))]);

        let mut builder = CommitBuilder::new("Pasted pins onto a frozen block");
        let pasted = paste_pins(
            &index.view(&doc),
            PinPaste {
                pins: &clip.snapshot().pins,
                owner: Scope::Block(block_id(2)),
            },
            &mut ids(&doc),
            &mut builder,
        );
        assert!(pasted.is_empty(), "a frozen interface takes no pins");
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Pasted pins onto a ghost");
        let pasted = paste_pins(
            &index.view(&doc),
            PinPaste {
                pins: &clip.snapshot().pins,
                owner: Scope::Block(block_id(99)),
            },
            &mut ids(&doc),
            &mut builder,
        );
        assert!(pasted.is_empty());
        seals_to_nothing(builder);
    }

    /// The same refusal reached through the whole-selection paste: a pin
    /// landing on the target scope's own boundary needs that boundary
    /// unfrozen, and a wire that loses its endpoint goes with it.
    #[test]
    fn a_paste_onto_a_frozen_scope_drops_the_pins_it_cannot_slot() {
        let doc = scene();
        let mut index = DocIndex::default();
        let clip = copy(&index.view(&doc), &[delete::Target::Pin(pin_id(3))]);
        let mut builder = CommitBuilder::new("Froze the destination");
        builder.push(OpCodes::Block(
            block_id(2),
            Crud::Update(BlockUpdate::Locked(true)),
        ));
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Pasted onto a frozen scope");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Block(block_id(2)), 0, 0),
            },
            &mut ids(&doc),
            &mut builder,
        );
        assert!(roots.is_empty(), "nothing landed");
        seals_to_nothing(builder);
    }

    /// A pin pasted as a port on another block re-slots and rides the drop
    /// with its body.
    #[test]
    fn a_pin_pasted_into_another_block_re_slots_and_rides_the_drop() {
        let doc = scene();
        let mut index = DocIndex::default();
        let clip = copy(&index.view(&doc), &[delete::Target::Pin(pin_id(10))]);
        let body = doc.pin(&pin_id(10)).expect("the copied pin").rect;
        assert_eq!(
            doc.pin(&pin_id(10)).expect("the copied pin").slot,
            slot(PinSide::West, 1),
            "precondition: the source slot is taken on the destination"
        );

        let mut builder = CommitBuilder::new("Pasted a pin");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Block(block_id(1)), 3, 4),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let [Shape::Port(id)] = roots[..] else {
            unreachable!("a pasted pin is a port shape: {roots:?}");
        };
        let pasted = doc.pin(&id).expect("the pasted pin");
        assert_eq!(pasted.owner, block_id(1));
        assert_eq!(
            pasted.slot,
            slot(PinSide::West, 1),
            "the first slot free on the destination, not the one it came from"
        );
        assert_eq!(
            pasted.rect,
            body.translate(GridVec::new(3, 4)),
            "the body rode the drop"
        );
    }

    /// E4 across the family: nothing named, nothing found, nothing to
    /// paste.
    #[test]
    fn absent_targets_and_empty_snapshots_do_nothing() {
        let doc = scene();
        let mut index = DocIndex::default();
        let strangers = [
            delete::Target::Block(block_id(99)),
            delete::Target::Pin(pin_id(98)),
            delete::Target::Route(route_id(97)),
            delete::Target::Text(text_id(96)),
            delete::Target::Area(area_id(95)),
            delete::Target::Image(image_id(94)),
        ];
        let clip = copy(&index.view(&doc), &strangers);
        assert!(
            clip.snapshot().is_empty(),
            "a selection of ghosts copies nothing"
        );

        let mut builder = CommitBuilder::new("Cut ghosts");
        let cut_clip = cut(&index.view(&doc), &strangers, home(), &mut builder);
        assert!(cut_clip.snapshot().is_empty());
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Pasted nothing");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Block(block_id(1)), 2, 2),
            },
            &mut ids(&doc),
            &mut builder,
        );
        assert!(roots.is_empty());
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Pasted no pins");
        let pasted = paste_pins(
            &index.view(&doc),
            PinPaste {
                pins: &[],
                owner: Scope::Block(block_id(1)),
            },
            &mut ids(&doc),
            &mut builder,
        );
        assert!(pasted.is_empty());
        seals_to_nothing(builder);
    }

    /// A cut declines what the delete declines, so the two halves cannot
    /// disagree — the frozen pin stays in the document *and* off the
    /// clipboard.
    #[test]
    fn a_cut_leaves_a_frozen_pin_in_the_document_and_off_the_clipboard() {
        let doc = scene();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Froze the interface");
        builder.push(OpCodes::Block(
            block_id(2),
            Crud::Update(BlockUpdate::Locked(true)),
        ));
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Cut a frozen pin");
        let clip = cut(
            &index.view(&doc),
            &[delete::Target::Pin(pin_id(10))],
            home(),
            &mut builder,
        );
        assert!(clip.snapshot().is_empty(), "the copy declined it too");
        seals_to_nothing(builder);
    }

    /// The decode boundary: our own payload round-trips, and anything else
    /// refuses rather than being reinterpreted.
    #[test]
    fn the_envelope_round_trips_and_refuses_everything_else() {
        let doc = scene();
        let mut index = DocIndex::default();
        let clip = copy(&index.view(&doc), &[delete::Target::Block(block_id(1))]);
        let json = clip.to_json().expect("the payload serializes");
        assert_eq!(
            Clipboard::from_json(&json).as_ref(),
            Some(&clip),
            "our own payload comes back unchanged"
        );

        for refused in [
            "",
            "hello",
            "{}",
            r#"{"V1":{"blocks":[]}}"#,
            r#"{"V3":{"blocks":[]}}"#,
            &json[..json.len() / 2],
        ] {
            assert!(
                Clipboard::from_json(refused).is_none(),
                "{refused:?} is not one of our payloads"
            );
        }
    }

    /// The `V2` tag is the wire name, and a payload written under it must
    /// keep decoding: pin the tag itself, not just the round trip.
    #[test]
    fn the_payload_is_tagged_by_its_version() {
        let json = Clipboard::V2 {
            snapshot: Snapshot::default(),
            origin: Origin::Copy,
        }
        .to_json()
        .expect("the payload serializes");
        assert!(json.starts_with(r#"{"V2":"#), "{json}");
    }

    /// The offset is a whole-cell delta, so the artwork riding it moves by
    /// the same distance in world pixels.
    #[test]
    fn artwork_rides_the_drop_in_world_pixels() {
        let picture = svg("<svg>picture</svg>");
        let mut index = DocIndex::default();
        let doc = scene();
        let mut builder = CommitBuilder::new("Placed artwork at the top level");
        builder.extend([
            OpCodes::Asset(picture.hash(), picture.clone()),
            image_create(40, 1),
            OpCodes::Image(
                image_id(40),
                Crud::Update(ImageUpdate::Asset(picture.hash())),
            ),
            OpCodes::Image(
                image_id(40),
                Crud::Update(ImageUpdate::Rect(artwork_box(30.0, 45.0))),
            ),
        ]);
        let doc = fold(builder, &doc);

        let clip = copy(&index.view(&doc), &[delete::Target::Image(image_id(40))]);
        let mut builder = CommitBuilder::new("Pasted artwork");
        let roots = paste(
            &index.view(&doc),
            Paste {
                clip: &clip,
                into: home(),
                target: drop_at(Scope::Block(block_id(1)), 2, 3),
            },
            &mut ids(&doc),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let [Shape::Image(id)] = roots[..] else {
            unreachable!("a pasted image is an image shape: {roots:?}");
        };
        assert_eq!(
            artwork_rect(doc.image(&id).expect("the copy").rect),
            artwork_rect(artwork_box(30.0, 45.0))
                .translate(Vec2::new(2.0 * GRID_SIZE, 3.0 * GRID_SIZE)),
            "the copy sits one whole-cell delta from its source"
        );
    }
}