blockworx/edit/

create.rs

//! The create family (`docs/op-emitter-playbook.md`, 10c): the emitters
//! that mint entities. Every one takes its new ids pre-minted — ops land
//! with concrete ids, so a compound gesture (a wire and the pin it lands
//! on) is one commit.

use ahash::HashSet;
use blockworx_doc::{
    block_model::{Area, Block, BlockUpdate, Icon, Label, Pin, Route, RouteLabel, Text},
    commit::CommitBuilder,
    document::{Document, IndexedDocument, TitleBlockUpdate},
    geometry::{FracVal, GridPoint, GridRect, GridSize, GridVec, PinSlot, Waypoint},
    id::{AreaId, BlockId, PinId, RouteId, RouteLabelId, TextId},
    opcode::{Crud, OpCodes},
    values::{LabelSide, PinDir, PinSide, Role},
};
use blockworx_geom::{Pos2, Rect};

use crate::edit::lock::UnlockedScope;
use crate::edit::lower::{block_rect, slot_capacity};
use crate::grid::{
    DEFAULT_SCALE_FOR_NEW_VIEW, GRID_SIZE, PIN_PITCH_GRID, PIN_TOP_MARGIN, ceil_block_height,
    grid_point, grid_rect, pin_offset_y, px_rect, snap_block_height_cells,
};
use crate::path::{Resolved, Scope, resolve};
use crate::shape::port::{PORT_HEIGHT, width_for_labels};

/// The name a freshly drawn area carries into its rename editor. A block
/// gets a numbered one instead ([`BLOCK_PREFIX`]) — an area never appears
/// in a breadcrumb, a hierarchy row or a PDF outline, which is where
/// same-named neighbours were confusing.
const UNTITLED: &str = "Untitled";

/// The auto-name a freshly drawn block carries, numbered across the whole
/// document. The user ruled out the shared "Untitled" on 2026-08-31 — *"If
/// the user declines to name a block, the fact that they are all named
/// 'Untitled' is confusing"* — so a block is born with a name that already
/// tells it apart (playbook R17).
const BLOCK_PREFIX: &str = "Block ";

/// The auto-name every stamped pin takes, numbered per owner.
const PORT_PREFIX: &str = "Port ";

/// A fresh label at its kind's legacy resting side: a block title sits at
/// the bottom (`BlockLabel::default`), a type label and an area title at
/// the top (`BlockLabel::upper_left`, `Area::new`).
fn label(name: &str, side: LabelSide) -> Label {
    Label {
        name: name.into(),
        side,
        offset: FracVal::default(),
        hidden: false,
    }
}

/// The block a drag drew: where it lands, and the two corners it spans.
/// A struct like [`NewPin`] and [`NewPort`], because the emitter also needs
/// the document to name it and seven loose arguments say nothing.
#[derive(Clone, Copy, Debug)]
pub struct NewBlock {
    pub id: BlockId,
    pub scope: Scope,
    pub start: Pos2,
    pub end: Pos2,
}

/// Inventory row "New Block": a drag stamps a child block on `scope` — the
/// document root is a scope like any other. The parent's child list is
/// derived, so `parent` is the whole structural write.
///
/// The block is born named (R17), which is why this needs the document: the
/// number is the first one no other block's title claims. Naming it here
/// rather than at each surface means the canvas, the breadcrumb, the
/// hierarchy, the palette and the PDF outline are all fixed by one policy,
/// and the name is a real, editable, journalled one rather than a label
/// five renderers have to agree on.
pub fn block(doc: &Document, new: NewBlock, builder: &mut CommitBuilder) {
    let NewBlock {
        id,
        scope,
        start,
        end,
    } = new;
    builder.push(OpCodes::Block(
        id,
        Crud::Create(Block {
            parent: scope.wire_id(),
            rect: block_rect(start, end),
            locked: false,
            role: Role::default(),
            title: label(&next_free_title(doc, BLOCK_PREFIX), LabelSide::Bottom),
            type_label: label("", LabelSide::Top),
            icon: Icon::default(),
        }),
    ));
}

/// The box a block dropped on the canvas takes, anchored top-left at the
/// drop point. A drop names one corner and a block needs two, so the extent
/// is the one the document already gives a block nobody sized
/// ([`TOP_BLOCK_DEFAULT_RECT`]) — deliberately small and fixed.
pub fn stamped_block(at: Pos2) -> Rect {
    stamped(at, TOP_BLOCK_DEFAULT_RECT.size)
}

/// A default extent hung off a grid-snapped drop point — the arithmetic the
/// `stamped_*` defaults share.
fn stamped(at: Pos2, size: GridSize) -> Rect {
    px_rect(GridRect {
        top_left: grid_point(at),
        size,
    })
}

/// Inventory row "New Area": a drag stamps a boundary annotation box.
/// Unlike a block, an area holds no pins, so its height is whatever the
/// drag drew.
pub fn area(id: AreaId, owner: Scope, start: Pos2, end: Pos2, builder: &mut CommitBuilder) {
    builder.push(OpCodes::Area(
        id,
        Crud::Create(Area {
            owner: owner.wire_id(),
            rect: grid_rect(start, end),
            role: Role::default(),
            title: label(UNTITLED, LabelSide::Top),
        }),
    ));
}

/// The box an area dropped on the canvas takes, on [`stamped_block`]'s
/// terms. Wider than a block and free of its pin ladder: an area's job is to
/// enclose a few of them.
pub fn stamped_area(at: Pos2) -> Rect {
    stamped(at, STAMPED_AREA)
}

const STAMPED_AREA: GridSize = GridSize { w: 20, h: 14 };

/// Inventory row "New Text Box": a click places an empty text annotation
/// and opens its editor; emptying it there is what deletes it
/// (`naming::edit_text`).
pub fn text_box(id: TextId, owner: Scope, pos: Pos2, builder: &mut CommitBuilder) {
    builder.push(OpCodes::Text(
        id,
        Crud::Create(Text {
            owner: owner.wire_id(),
            text: String::new(),
            pos: grid_point(pos),
            role: Role::default(),
        }),
    ));
}

/// A pin the gesture stamped on a block edge: [`pin`]'s parameters, and
/// the rider [`route`] carries when a wire lands on a free slot.
#[derive(Clone, Copy, Debug)]
pub struct NewPin {
    pub id: PinId,
    /// The scope that takes it — as proof rather than as a name, because
    /// adding a pin is a material edit and a locked block refuses one
    /// (`crate::edit::lock`). A `NewPin` for a locked owner is
    /// unconstructible.
    pub owner: UnlockedScope,
    pub slot: PinSlot,
}

/// A boundary port the gesture stamped: the block whose boundary it joins,
/// and the two corners of the body box drawn for it. Its slot is searched,
/// not given.
#[derive(Clone, Copy, Debug)]
pub struct NewPort {
    pub id: PinId,
    /// As [`NewPin::owner`].
    pub owner: UnlockedScope,
    pub start: Pos2,
    pub end: Pos2,
}

pub(crate) fn owner_pins<'a>(
    indexed: &'a IndexedDocument<'a>,
    owner: Scope,
) -> impl Iterator<Item = &'a Pin> + 'a {
    indexed
        .index
        .blocks
        .get(&owner.wire_id())
        .into_iter()
        .flat_map(|entry| entry.pins.iter())
        .filter_map(|id| indexed.doc.pin(id))
}

/// The auto-name a stamped pin takes (`"Port N"`, tag `"N"` —
/// `Drawing::add_port_auto_named`, `add_named_pin`). Ids count per
/// document, not per block, so the number is read back off the owner's
/// pins: one past the highest they already carry.
fn next_pin_ordinal(indexed: &IndexedDocument<'_>, owner: Scope) -> u32 {
    owner_pins(indexed, owner)
        .filter_map(|pin| {
            pin.name
                .strip_prefix(PORT_PREFIX)
                .and_then(|ordinal| ordinal.parse::<u32>().ok())
        })
        .max()
        .unwrap_or(0)
        + 1
}

/// Where a stamped pin's port body sits inside its owner's own interior
/// view, ported from `Block::default_port_rect` (`src/shape/block.rs:
/// 288-318`): the owner's rect magnified by [`DEFAULT_SCALE_FOR_NEW_VIEW`]
/// so the expanded view has room for child blocks, the body hugging the
/// edge its slot sits on and tracking the slot down that edge. A body
/// landing on an existing one steps outward by its own width until clear —
/// bounded, like the legacy, so a pathological interior cannot spin.
///
/// Shared with the port emitters, which
/// reconstructs the same placement for a pin whose file omitted it, the
/// way `Block::fill_missing_port_rects` does on the legacy load.
pub(crate) fn default_port_rect(
    rect: GridRect,
    siblings: &[GridRect],
    name: &str,
    slot: PinSlot,
) -> GridRect {
    let origin = rect.top_left;
    let scaled_w = rect.size.w as i32 * DEFAULT_SCALE_FOR_NEW_VIEW;
    let width = width_for_labels(name, "");
    let top = origin.y + slot.offset as i32 * PIN_PITCH_GRID * DEFAULT_SCALE_FOR_NEW_VIEW;
    let (left, step) = match slot.side {
        PinSide::East => (
            (origin.x + scaled_w - width as i32).max(origin.x),
            width as i32,
        ),
        PinSide::West => (origin.x, -(width as i32)),
    };
    let mut candidate = GridRect {
        top_left: GridPoint { x: left, y: top },
        size: GridSize {
            w: width,
            h: PORT_HEIGHT,
        },
    };
    let mut steps = 0;
    while siblings.iter().any(|body| candidate.intersects(*body)) && steps <= siblings.len() {
        candidate = candidate.translate(GridVec::new(step, 0));
        steps += 1;
    }
    candidate
}

/// The pin a stamp lands as.
///
/// The owner is a [`UnlockedScope`], so "a locked block keeps its interface
/// frozen" and "a block the document does not hold takes nothing" are both
/// answered before this is called — there is no `NewPin` for either.
fn pin_init(indexed: &IndexedDocument<'_>, new: NewPin) -> Pin {
    // The document root is a scope without an entity behind it (F9): it holds
    // pins, is never locked, and has no rect to place a body against — the
    // only gesture that stamps one there is [`port`], which draws the body
    // itself and overwrites the placement below.
    let owner = resolve(indexed, new.owner.scope());
    let ordinal = next_pin_ordinal(indexed, new.owner.scope());
    let name = format!("{PORT_PREFIX}{ordinal}");
    let siblings: Vec<GridRect> = owner_pins(indexed, new.owner.scope())
        .map(|pin| pin.rect)
        .collect();
    Pin {
        owner: new.owner.scope().wire_id(),
        rect: match owner {
            Resolved::Block(block) => default_port_rect(block.rect, &siblings, &name, new.slot),
            Resolved::Root | Resolved::Absent => GridRect::default(),
        },
        name,
        type_name: String::new(),
        tag: ordinal.to_string(),
        tag_hidden: false,
        slot: new.slot,
        dir: PinDir::InOut,
        port_accent: Role::default(),
        flip_lr: false,
    }
}

/// Inventory row "Add Pin (block edge)": a click on a slot marker — or a
/// wire pulled out of one — stamps a pin there.
pub fn pin(indexed: &IndexedDocument<'_>, new: NewPin, builder: &mut CommitBuilder) {
    let init = pin_init(indexed, new);
    builder.push(OpCodes::Pin(new.id, Crud::Create(init)));
}

/// The shortest block, in cells, that still offers slot `slot`: the slot's
/// own row plus the clearance [`max_pin_slot`](crate::grid::max_pin_slot)
/// keeps below it.
fn height_for_slot(slot: u32) -> u32 {
    (ceil_block_height(pin_offset_y(0.0, slot) + PIN_TOP_MARGIN) / GRID_SIZE).round() as u32
}

/// The first slot the owner's pins leave free, scanning top-down and West
/// before East (the legacy `Block::new_pin_locations` order). Total: each
/// offset offers two slots, so some slot at an offset in `0..=n` escapes
/// `n` occupants.
///
/// Shared with the clipboard (10g): a paste slots its pins by the same
/// policy a stamp does, group at a time.
pub(crate) fn first_free_slot(occupied: &HashSet<PinSlot>) -> PinSlot {
    (0..=occupied.len() as u32)
        .flat_map(|offset| [PinSide::West, PinSide::East].map(|side| PinSlot { side, offset }))
        .find(|slot| !occupied.contains(slot))
        .unwrap_or_default()
}

/// The growth rider: a block too short for `slot` grows two cells at a
/// time until it fits (legacy `add_port_auto_named`'s loop). `None` when
/// it already fits.
pub(crate) fn grown_to_fit(block: &Block, slot: PinSlot) -> Option<GridRect> {
    let rect = block.rect;
    let mut height = rect.size.h;
    while slot_capacity(height) < slot.offset {
        height += 2;
    }
    (height != rect.size.h).then_some(GridRect {
        size: GridSize {
            h: height,
            ..rect.size
        },
        ..rect
    })
}

/// The body box a port dropped on the canvas takes, on [`stamped_block`]'s
/// terms — and the width a port *drawn* falls back to when the drag is
/// narrower than one. The height is [`PORT_HEIGHT`], which [`port`] forces
/// on whatever box it is handed anyway.
pub fn stamped_port(at: Pos2) -> Rect {
    stamped(
        at,
        GridSize {
            w: STAMPED_PORT_WIDTH,
            h: PORT_HEIGHT,
        },
    )
}

pub const STAMPED_PORT_WIDTH: u32 = 4;

/// Inventory row "Add Port (boundary)": stamp a port on the scope's own
/// boundary at the first free slot, growing the block until that slot
/// fits.
pub fn port(indexed: &IndexedDocument<'_>, new: NewPort, builder: &mut CommitBuilder) {
    let owner = resolve(indexed, new.owner.scope());
    if let Resolved::Absent = owner {
        return;
    }
    let occupied: HashSet<PinSlot> = owner_pins(indexed, new.owner.scope())
        .map(|pin| pin.slot)
        .collect();
    let slot = first_free_slot(&occupied);
    let stamp = NewPin {
        id: new.id,
        owner: new.owner,
        slot,
    };
    let init = pin_init(indexed, stamp);
    let body = grid_rect(new.start, new.end);
    builder.push(OpCodes::Pin(
        new.id,
        Crud::Create(Pin {
            // A port is drawn, not auto-placed: the gesture box replaces
            // the interior placement, keeping only the fixed body height.
            rect: GridRect {
                size: GridSize {
                    h: PORT_HEIGHT,
                    ..body.size
                },
                ..body
            },
            ..init
        }),
    ));
    // The root scope has no box to grow: its ports sit where they are drawn.
    if let Resolved::Block(block) = owner
        && let Some(rect) = grown_to_fit(block, slot)
    {
        builder.push(OpCodes::Block(
            new.owner.scope().wire_id(),
            Crud::Update(BlockUpdate::Rect(rect)),
        ));
    }
}

/// Where a drawn wire landed: on a pin that already exists, or on a free
/// slot marker, which stamps the destination pin in the same commit.
#[derive(Clone, Copy, Debug)]
pub enum RouteEnd {
    Pin(PinId),
    Fresh(NewPin),
}

/// One wire the gesture drew.
#[derive(Clone, Debug)]
pub struct NewRoute {
    pub id: RouteId,
    pub owner: Scope,
    pub from: PinId,
    pub to: RouteEnd,
    /// The corners the router solved, in path order.
    pub waypoints: Vec<Waypoint>,
}

/// Inventory row "New Route (wire)": connect two pins along the solved
/// path. A wire landing on a free slot carries its destination pin, and a
/// destination the owner refuses takes the wire with it — a rejected route
/// must never leave an orphan pin (legacy `RouteTool::commit`).
pub fn route(indexed: &IndexedDocument<'_>, new: NewRoute, builder: &mut CommitBuilder) {
    let to = match new.to {
        RouteEnd::Pin(id) => id,
        RouteEnd::Fresh(stamp) => {
            // No refusal to handle: the stamp carries an `UnlockedScope`, so
            // a wire cannot arrive here proposing a pin on a frozen block.
            let init = pin_init(indexed, stamp);
            builder.push(OpCodes::Pin(stamp.id, Crud::Create(init)));
            stamp.id
        }
    };
    builder.push(OpCodes::Route(
        new.id,
        Crud::Create(Route {
            owner: new.owner.wire_id(),
            name: String::new(),
            from: new.from,
            to,
            role: Role::default(),
            waypoints: new.waypoints,
        }),
    ));
}

/// Where a grabbed corner lands in a route's polyline — the arc-length
/// ordinal the gesture classified against solved geometry the emitter
/// cannot see. Past the end clamps to the end.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PathOrdinal(usize);

impl PathOrdinal {
    pub fn new(index: usize) -> Self {
        Self(index)
    }
}

impl From<PathOrdinal> for usize {
    fn from(ordinal: PathOrdinal) -> usize {
        ordinal.0
    }
}

/// Inventory row "Add Wire Label": drop a name label on a wire, at the arc
/// length the click projected onto its polyline.
pub fn wire_label(
    doc: &Document,
    id: RouteLabelId,
    route: RouteId,
    pos: FracVal,
    builder: &mut CommitBuilder,
) {
    if doc.route(&route).is_none() {
        return;
    }
    builder.push(OpCodes::RouteLabel(
        id,
        Crud::Create(RouteLabel { owner: route, pos }),
    ));
}

pub(crate) const TOP_BLOCK_DEFAULT_WIDTH: u32 = 8;
pub(crate) const TOP_BLOCK_DEFAULT_HEIGHT: u32 = 16;

/// The rect a top block is born with: deliberately small and fixed rather
/// than derived from what it holds.
const TOP_BLOCK_DEFAULT_RECT: GridRect = GridRect {
    top_left: GridPoint { x: 0, y: 0 },
    size: GridSize {
        w: TOP_BLOCK_DEFAULT_WIDTH,
        h: TOP_BLOCK_DEFAULT_HEIGHT,
    },
};

/// The auto-name a wrapped level takes (legacy `next_top_name`).
const TOP_PREFIX: &str = "top_";

/// The lowest `{prefix}<n>` from 1 up that no live block titles itself, so
/// two blocks the user has not named are still told apart wherever their
/// titles are listed — the nav breadcrumb, the hierarchy, the PDF outline.
///
/// The search reads the titles the document actually holds rather than
/// counting blocks, so it stays deterministic and collision-free after a
/// delete or a paste: a document that lost `Block 2` mints that name again
/// instead of climbing past it forever.
fn next_free_title(doc: &Document, prefix: &str) -> String {
    let taken: HashSet<&str> = doc
        .blocks()
        .map(|(_, block)| block.title.name.as_str())
        .collect();
    // One more candidate than there are blocks, so at least one is free;
    // the fallback keeps the search total instead of unwrapping.
    let last = taken.len() + 1;
    (1..=last)
        .map(|n| format!("{prefix}{n}"))
        .find(|candidate| !taken.contains(candidate.as_str()))
        .unwrap_or_else(|| format!("{prefix}{}", last + 1))
}

/// The rect the old root shows as once demoted: the one it already has,
/// made tall enough that its lowest pin slot still fits. Its size is *not*
/// derived from what it contains — a block as large as the whole drawing
/// is unwieldy — and a degenerate rect (a root written before tops were
/// born with a size) falls back to the default rather than demoting to an
/// invisible sliver.
fn demoted_rect(block: &Block, lowest_slot: u32) -> GridRect {
    let own = block.rect;
    let width = if own.size.w == 0 {
        TOP_BLOCK_DEFAULT_WIDTH
    } else {
        own.size.w
    };
    let height = if own.size.h == 0 {
        TOP_BLOCK_DEFAULT_HEIGHT
    } else {
        own.size.h
    };
    GridRect {
        top_left: own.top_left,
        size: GridSize {
            w: width,
            h: snap_block_height_cells(height.max(height_for_slot(lowest_slot))),
        },
    }
}

/// Inventory row "Wrap Top": add a level above the whole document — a
/// fresh root whose sole child is the old one, which demotes to a child
/// rect. A document with no root yet (`top` is `NULL`) has nothing to
/// demote, so the wrap is just the new root.
pub fn wrap_top(indexed: &IndexedDocument<'_>, new_root: BlockId, builder: &mut CommitBuilder) {
    builder.push(OpCodes::Block(
        new_root,
        Crud::Create(Block {
            parent: Scope::Root.wire_id(),
            rect: TOP_BLOCK_DEFAULT_RECT,
            locked: false,
            role: Role::default(),
            title: label(&next_free_title(indexed.doc, TOP_PREFIX), LabelSide::Bottom),
            type_label: label("", LabelSide::Top),
            icon: Icon::default(),
        }),
    ));
    let old_root = indexed.doc.title_block().top;
    if let Some(old) = indexed.doc.block(&old_root) {
        builder.push(OpCodes::Block(
            old_root,
            Crud::Update(BlockUpdate::Parent(new_root)),
        ));
        let lowest_slot = owner_pins(indexed, Scope::Block(old_root))
            .map(|pin| pin.slot.offset)
            .max()
            .unwrap_or(0);
        let demoted = demoted_rect(old, lowest_slot);
        if demoted != old.rect {
            builder.push(OpCodes::Block(
                old_root,
                Crud::Update(BlockUpdate::Rect(demoted)),
            ));
        }
    }
    builder.push(OpCodes::Document(TitleBlockUpdate::Top(new_root)));
}

#[cfg(test)]
mod tests {
    use super::*;
    use blockworx_geom::pos2;

    /// The proof a create takes, for a test whose owner is unlocked. A locked
    /// one is `UnlockedScope::of(...) == None`, which is the point of the
    /// type and is asserted where it matters.
    fn scope(indexed: &IndexedDocument<'_>, owner: Scope) -> UnlockedScope {
        UnlockedScope::of(indexed, owner).expect("the owner is unlocked")
    }
    use crate::edit::harness::{fold, seals_to_nothing, wired};
    use blockworx_doc::document::DocIndex;
    use blockworx_doc::{
        block_model::PinUpdate,
        fixtures::{area_id, block_id, pin_id, route_id, route_label_id, text_id},
    };

    /// A gesture point, in whole grid cells.
    fn at(x: f32, y: f32) -> Pos2 {
        pos2(x * GRID_SIZE, y * 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 put where it is, which re-routing must respect.
    fn pinned(x: i32, y: i32) -> Waypoint {
        Waypoint {
            locked: true,
            ..corner(x, y)
        }
    }

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

    /// The width every stamp in these tests places, since each takes a
    /// six-character auto-name.
    fn body_width() -> u32 {
        width_for_labels("Port 1", "")
    }

    /// Block 1 at a real size — the interior a stamped pin's body is
    /// placed in.
    fn sized() -> Document {
        let doc = wired();
        let mut builder = CommitBuilder::new("Sized the block");
        builder.push(OpCodes::Block(
            block_id(1),
            Crud::Update(BlockUpdate::Rect(rect(0, 0, 8, 16))),
        ));
        let doc = fold(builder, &doc);
        assert!(
            8 * DEFAULT_SCALE_FOR_NEW_VIEW > body_width() as i32,
            "precondition: the scaled interior is wider than a port body, \
             so the two edges are distinguishable placements"
        );
        doc
    }

    /// Block 1 four cells tall — one pin slot — with both of that slot's
    /// places taken, so a fresh port has to grow it.
    fn packed() -> Document {
        let doc = wired();
        let mut builder = CommitBuilder::new("Packed the boundary");
        builder.push(OpCodes::Block(
            block_id(1),
            Crud::Update(BlockUpdate::Rect(rect(0, 0, 8, 4))),
        ));
        builder.push(OpCodes::Pin(
            pin_id(3),
            Crud::Update(PinUpdate::Slot(slot(PinSide::West, 0))),
        ));
        builder.push(OpCodes::Pin(
            pin_id(4),
            Crud::Update(PinUpdate::Slot(slot(PinSide::East, 0))),
        ));
        let doc = fold(builder, &doc);
        assert_eq!(
            slot_capacity(4),
            0,
            "precondition: a four-cell block offers slot 0 and nothing else"
        );
        doc
    }

    /// The scene with its block's pin interface frozen — the arm every pin
    /// stamp must decline.
    fn locked_scene() -> Document {
        let doc = wired();
        let mut builder = CommitBuilder::new("Locked the block");
        builder.push(OpCodes::Block(
            block_id(1),
            Crud::Update(BlockUpdate::Locked(true)),
        ));
        let doc = fold(builder, &doc);
        assert!(
            block_of(&doc, 1).locked,
            "precondition: the owner is locked"
        );
        doc
    }

    #[test]
    fn block_stamps_a_numbered_child_on_the_height_ladder() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Drew a block");
        block(
            &doc,
            NewBlock {
                id: block_id(10),
                scope: Scope::Block(block_id(1)),
                start: at(1.0, 2.0),
                end: at(9.0, 7.0),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = block_of(&doc, 10);
        assert_eq!(new.parent, block_id(1));
        assert_eq!(
            new.rect,
            rect(1, 2, 8, 4),
            "the drag's five-cell height settles onto the ladder's first rung"
        );
        assert_eq!(new.title.name, "Block 1");
        assert_eq!(new.title.side, LabelSide::Bottom);
        assert_eq!(new.type_label.side, LabelSide::Top);
        assert_eq!(new.type_label.name, "");
        assert!(!new.locked);
        assert_eq!(new.role, Role::Accent0);
        assert_eq!(new.icon, Icon::default());
        assert!(
            DocIndex::of(&doc).blocks[&block_id(1)]
                .children
                .contains(&block_id(10)),
            "the scope's child list is presentation from the parent register"
        );
    }

    #[test]
    fn a_block_at_the_document_root_takes_the_null_parent() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Drew a top-level block");
        block(
            &doc,
            NewBlock {
                id: block_id(10),
                scope: Scope::Root,
                start: at(0.0, 0.0),
                end: at(4.0, 4.0),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(Scope::from_wire(block_of(&doc, 10).parent), Scope::Root);
        assert!(
            DocIndex::of(&doc).blocks[&Scope::Root.wire_id()]
                .children
                .contains(&block_id(10))
        );
    }

    /// R17: an unnamed block is told apart by its own title, not by the
    /// surface listing it. The number is the lowest one free, so consecutive
    /// stamps count up — and a stamp after a delete refills the gap rather
    /// than climbing past it, which is what makes the name deterministic
    /// however the document got to where it is.
    #[test]
    fn a_stamped_block_takes_the_lowest_free_number_and_refills_gaps() {
        let stamp = |doc: &Document, id: u32| {
            let mut builder = CommitBuilder::new("Drew a block");
            block(
                doc,
                NewBlock {
                    id: block_id(id),
                    scope: Scope::Root,
                    start: at(0.0, 0.0),
                    end: at(4.0, 4.0),
                },
                &mut builder,
            );
            fold(builder, doc)
        };
        let doc = stamp(&wired(), 10);
        assert_eq!(block_of(&doc, 10).title.name, "Block 1");

        let doc = stamp(&doc, 11);
        assert_eq!(
            block_of(&doc, 11).title.name,
            "Block 2",
            "a second stamp reused the first block's name",
        );

        let mut builder = CommitBuilder::new("Deleted a block");
        let mut index = DocIndex::default();
        crate::edit::delete::selection(
            &index.view(&doc),
            &[crate::edit::delete::Target::Block(block_id(10))],
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert!(
            doc.block(&block_id(10)).is_none(),
            "precondition: the block holding \"Block 1\" is gone",
        );

        let doc = stamp(&doc, 12);
        assert_eq!(
            block_of(&doc, 12).title.name,
            "Block 1",
            "the freed number was climbed past instead of reused",
        );
    }

    #[test]
    fn area_stamps_an_untitled_box_off_the_height_ladder() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Drew an area");
        area(
            area_id(10),
            Scope::Block(block_id(1)),
            at(1.0, 2.0),
            at(9.0, 7.0),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = doc.area(&area_id(10)).expect("the area exists");
        assert_eq!(new.owner, block_id(1));
        assert_eq!(
            new.rect,
            rect(1, 2, 8, 5),
            "an area holds no pins, so its height is the one drawn"
        );
        assert_eq!(new.title.name, "Untitled");
        assert_eq!(new.title.side, LabelSide::Top);
        assert_eq!(new.role, Role::Accent0);
    }

    #[test]
    fn text_box_stamps_an_empty_box_at_the_snapped_click() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Placed a text box");
        text_box(
            text_id(10),
            Scope::Block(block_id(1)),
            at(3.4, 5.6),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = doc.text(&text_id(10)).expect("the text exists");
        assert_eq!(new.owner, block_id(1));
        assert_eq!(new.text, "");
        assert_eq!(new.pos, GridPoint { x: 3, y: 6 });
        assert_eq!(new.role, Role::Accent0);
    }

    #[test]
    fn port_takes_the_first_free_slot_and_grows_the_block_to_fit() {
        let doc = packed();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Stamped a port");
        let view = index.view(&doc);
        port(
            &view,
            NewPort {
                id: pin_id(10),
                owner: scope(&view, Scope::Block(block_id(1))),
                start: at(2.0, 2.0),
                end: at(7.0, 5.0),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = pin_of(&doc, 10);
        assert_eq!(
            new.slot,
            slot(PinSide::West, 1),
            "slot 0 is taken on both sides, so the next offset's West place wins"
        );
        assert_eq!(new.name, "Port 1");
        assert_eq!(new.tag, "1");
        assert_eq!(new.dir, PinDir::InOut);
        assert_eq!(
            new.rect,
            rect(2, 2, 5, PORT_HEIGHT),
            "the gesture box places and widens the body; its height is fixed"
        );

        assert_eq!(
            slot_capacity(6),
            0,
            "precondition: one two-cell step is not enough, so the loop must run twice"
        );
        assert_eq!(
            block_of(&doc, 1).rect.size,
            GridSize { w: 8, h: 8 },
            "the owner grew two cells at a time until the slot fit"
        );
    }

    #[test]
    fn ports_number_themselves_from_the_owners_pins() {
        let doc = packed();
        let stamp = |doc: &Document, id: u32| {
            let mut builder = CommitBuilder::new("Stamped a port");
            let mut index = DocIndex::default();
            let view = index.view(doc);
            port(
                &view,
                NewPort {
                    id: pin_id(id),
                    owner: scope(&view, Scope::Block(block_id(1))),
                    start: at(0.0, 0.0),
                    end: at(5.0, 2.0),
                },
                &mut builder,
            );
            fold(builder, doc)
        };
        assert!(
            !pin_of(&doc, 3).name.starts_with(PORT_PREFIX),
            "precondition: the scene's hand-named pins carry no ordinal"
        );

        let doc = stamp(&doc, 10);
        let doc = stamp(&doc, 11);
        assert_eq!(pin_of(&doc, 10).name, "Port 1");
        assert_eq!(pin_of(&doc, 11).name, "Port 2");
        assert_eq!(pin_of(&doc, 11).tag, "2");
        assert_ne!(
            pin_of(&doc, 10).slot,
            pin_of(&doc, 11).slot,
            "each stamp takes a slot the last one left free"
        );
    }

    #[test]
    fn pin_stamps_at_the_given_slot() {
        let doc = sized();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Stamped a pin");
        let view = index.view(&doc);
        pin(
            &view,
            NewPin {
                id: pin_id(10),
                owner: scope(&view, Scope::Block(block_id(1))),
                slot: slot(PinSide::East, 2),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = pin_of(&doc, 10);
        assert_eq!(new.owner, block_id(1));
        assert_eq!(new.slot, slot(PinSide::East, 2));
        assert_eq!(new.name, "Port 1");
        assert_eq!(new.tag, "1");
        assert_eq!(new.dir, PinDir::InOut);
        assert!(!new.tag_hidden);
        assert!(!new.flip_lr);
        assert_eq!(
            block_of(&doc, 1).rect.size,
            GridSize { w: 8, h: 16 },
            "a pin at a named slot never grows its block"
        );
    }

    #[test]
    fn a_stamped_pins_body_hugs_the_edge_its_slot_sits_on() {
        let doc = sized();
        let stamp = |doc: &Document, id: u32, side| {
            let mut builder = CommitBuilder::new("Stamped a pin");
            let mut index = DocIndex::default();
            let view = index.view(doc);
            pin(
                &view,
                NewPin {
                    id: pin_id(id),
                    owner: scope(&view, Scope::Block(block_id(1))),
                    slot: slot(side, 1),
                },
                &mut builder,
            );
            fold(builder, doc)
        };

        let doc = stamp(&doc, 10, PinSide::West);
        let doc = stamp(&doc, 11, PinSide::East);
        let interior = block_of(&doc, 1).rect;
        let west = pin_of(&doc, 10).rect;
        let east = pin_of(&doc, 11).rect;

        assert_eq!(
            west,
            rect(
                interior.left(),
                interior.top() + PIN_PITCH_GRID * DEFAULT_SCALE_FOR_NEW_VIEW,
                body_width(),
                PORT_HEIGHT
            ),
            "a West slot's body hugs the left of the magnified interior, one slot down"
        );
        assert_eq!(
            east.right(),
            interior.left() + interior.size.w as i32 * DEFAULT_SCALE_FOR_NEW_VIEW,
            "an East slot's body hugs the right of the magnified interior"
        );
        assert_eq!(east.top(), west.top(), "both track the same slot");
        assert!(
            west.right() < east.left(),
            "the two edges are placements apart, not the same box"
        );
    }

    #[test]
    fn a_body_that_would_cover_a_sibling_steps_outward() {
        let doc = sized();
        let mut index = DocIndex::default();
        let taken = default_port_rect(
            block_of(&doc, 1).rect,
            &[],
            "Port 1",
            slot(PinSide::West, 1),
        );
        let mut builder = CommitBuilder::new("Parked a body in the way");
        builder.push(OpCodes::Pin(
            pin_id(3),
            Crud::Update(PinUpdate::Rect(taken)),
        ));
        let doc = fold(builder, &doc);
        assert!(
            default_port_rect(
                block_of(&doc, 1).rect,
                &[],
                "Port 1",
                slot(PinSide::West, 1),
            )
            .intersects(taken),
            "precondition: unstepped, the stamp would land on the parked body"
        );

        let mut builder = CommitBuilder::new("Stamped a pin behind it");
        let view = index.view(&doc);
        pin(
            &view,
            NewPin {
                id: pin_id(10),
                owner: scope(&view, Scope::Block(block_id(1))),
                slot: slot(PinSide::West, 1),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let stepped = pin_of(&doc, 10).rect;
        assert!(
            !stepped.intersects(taken),
            "the body stepped clear of its sibling"
        );
        assert_eq!(
            stepped,
            taken.translate(GridVec::new(-(body_width() as i32), 0)),
            "a West body steps outward by its own width — away from the interior"
        );
    }

    /// F9: the document root is a scope with no entity behind it, and a
    /// serverless boot starts there — so the port stamp has to land without
    /// an owner block to read a lock, a box, or a growth from.
    #[test]
    fn the_document_root_takes_a_port_though_it_has_no_block() {
        let doc = packed();
        let mut index = DocIndex::default();
        assert!(
            doc.block(&Scope::Root.wire_id()).is_none(),
            "precondition: the root is a scope, not an entity"
        );

        let mut builder = CommitBuilder::new("Stamped a port on the root");
        let view = index.view(&doc);
        port(
            &view,
            NewPort {
                id: pin_id(10),
                owner: scope(&view, Scope::Root),
                start: at(2.0, 2.0),
                end: at(7.0, 5.0),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = pin_of(&doc, 10);
        assert_eq!(Scope::from_wire(new.owner), Scope::Root);
        assert_eq!(
            new.slot,
            slot(PinSide::West, 0),
            "the root held no pins, so the first slot is free"
        );
        assert_eq!(
            new.rect,
            rect(2, 2, 5, PORT_HEIGHT),
            "the gesture box places the body; the root has none to place it in"
        );
    }

    /// A locked owner stamps nothing — and now says so by refusing the proof,
    /// so there is no `NewPin` to hand the emitter at all.
    #[test]
    fn a_locked_owner_stamps_nothing() {
        let doc = locked_scene();
        let mut index = DocIndex::default();
        let view = index.view(&doc);
        assert_eq!(
            UnlockedScope::of(&view, Scope::Block(block_id(1))),
            None,
            "a locked block hands out no proof, so a stamp cannot name it",
        );

        // A proof carries the scope it was minted from, so it cannot be
        // pointed at the frozen block: stamping with the root's proof lands
        // the pin at the root, which is the only place that proof allows.
        let stamp = NewPin {
            id: pin_id(10),
            owner: scope(&view, Scope::Root),
            slot: slot(PinSide::East, 2),
        };
        let mut builder = CommitBuilder::new("Stamped a pin at the root");
        pin(&view, stamp, &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(
            Scope::from_wire(pin_of(&doc, 10).owner),
            Scope::Root,
            "the stamp landed where the proof came from, not where it was aimed",
        );
        assert!(
            block_of(&doc, 1).locked,
            "and the frozen block is untouched",
        );
    }

    /// A port on a locked block is the same refusal, one emitter along.
    #[test]
    fn a_locked_owner_takes_no_port_either() {
        let doc = locked_scene();
        let mut index = DocIndex::default();
        let view = index.view(&doc);
        assert_eq!(UnlockedScope::of(&view, Scope::Block(block_id(1))), None);
    }

    #[test]
    fn an_absent_owner_hands_out_no_proof() {
        let doc = wired();
        let mut index = DocIndex::default();
        let view = index.view(&doc);
        assert_eq!(
            UnlockedScope::of(&view, Scope::Block(block_id(99))),
            None,
            "a block the document does not hold takes no pin, material or not",
        );
    }

    #[test]
    fn route_stamps_the_wire_along_the_solved_corners() {
        let doc = wired();
        let mut index = DocIndex::default();
        let corners = vec![corner(1, 1), pinned(2, 2)];
        let mut builder = CommitBuilder::new("Drew a wire");
        let view = index.view(&doc);
        route(
            &view,
            NewRoute {
                id: route_id(10),
                owner: Scope::Block(block_id(1)),
                from: pin_id(3),
                to: RouteEnd::Pin(pin_id(4)),
                waypoints: corners.clone(),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = doc.route(&route_id(10)).expect("the wire exists");
        assert_eq!(new.owner, block_id(1));
        assert_eq!(new.from, pin_id(3));
        assert_eq!(new.to, pin_id(4));
        assert_eq!(
            new.name, "",
            "a wire is born unnamed; naming it is the label's job"
        );
        assert_eq!(new.role, Role::Accent0);
        assert_eq!(new.waypoints, corners);
        assert!(
            [new.from, new.to].iter().all(|pin| doc.pin(pin).is_some()),
            "both endpoints stand, so the wire draws"
        );
    }

    #[test]
    fn a_wire_landing_on_a_free_slot_stamps_its_destination_pin() {
        let doc = wired();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Drew a wire onto a fresh pin");
        let view = index.view(&doc);
        route(
            &view,
            NewRoute {
                id: route_id(11),
                owner: Scope::Block(block_id(1)),
                from: pin_id(3),
                to: RouteEnd::Fresh(NewPin {
                    id: pin_id(10),
                    owner: scope(&view, Scope::Block(block_id(1))),
                    slot: slot(PinSide::East, 1),
                }),
                waypoints: Vec::new(),
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);

        assert_eq!(pin_of(&doc, 10).slot, slot(PinSide::East, 1));
        assert_eq!(
            doc.route(&route_id(11)).expect("the wire exists").to,
            pin_id(10),
            "the wire and the pin it landed on arrive in one commit"
        );
    }

    #[test]
    fn an_absent_wire_takes_no_label() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Deleted the wire");
        builder.push(OpCodes::Route(route_id(5), Crud::Delete));
        let doc = fold(builder, &doc);
        assert!(
            doc.route(&route_id(5)).is_none(),
            "precondition: the wire is gone"
        );

        let mut builder = CommitBuilder::new("Labelled a dead wire");
        wire_label(
            &doc,
            route_label_id(10),
            route_id(5),
            FracVal::from(3.5),
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Labelled a wire that never was");
        wire_label(
            &doc,
            route_label_id(10),
            route_id(99),
            FracVal::from(3.5),
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn wire_label_anchors_at_the_arc_length_the_click_projected() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Labelled a wire");
        wire_label(
            &doc,
            route_label_id(10),
            route_id(5),
            FracVal::from(37.5),
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let new = doc
            .route_label(&route_label_id(10))
            .expect("the label exists");
        assert_eq!(new.owner, route_id(5));
        assert_eq!(new.pos, FracVal::from(37.5));
        assert!(
            DocIndex::of(&doc).routes[&route_id(5)]
                .labels
                .contains(&route_label_id(10))
        );
    }

    /// The scene with block 1 designated as the document's root — what
    /// Wrap Top demotes.
    fn rooted() -> Document {
        let doc = wired();
        let mut builder = CommitBuilder::new("Designated the root");
        builder.push(OpCodes::Document(TitleBlockUpdate::Top(block_id(1))));
        let doc = fold(builder, &doc);
        assert_eq!(
            doc.title_block().top,
            block_id(1),
            "precondition: the document has a root to demote"
        );
        doc
    }

    #[test]
    fn wrap_top_creates_a_root_demotes_the_old_one_and_repoints_the_top() {
        let doc = rooted();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Wrapped the top");
        wrap_top(&index.view(&doc), block_id(10), &mut builder);
        let doc = fold(builder, &doc);

        assert_eq!(doc.title_block().top, block_id(10));
        let new_root = block_of(&doc, 10);
        assert_eq!(Scope::from_wire(new_root.parent), Scope::Root);
        assert_eq!(new_root.rect, TOP_BLOCK_DEFAULT_RECT);
        assert_eq!(new_root.title.name, "top_1");
        assert_eq!(
            block_of(&doc, 1).parent,
            block_id(10),
            "the old root demotes to the new one's child"
        );
        assert_eq!(
            block_of(&doc, 1).rect,
            rect(0, 0, TOP_BLOCK_DEFAULT_WIDTH, TOP_BLOCK_DEFAULT_HEIGHT),
            "a root with no size of its own demotes to a visible child, not a sliver"
        );
        assert_eq!(
            DocIndex::of(&doc).blocks[&Scope::Root.wire_id()].children,
            [block_id(10)].into_iter().collect(),
            "the document root holds exactly the new level"
        );
    }

    #[test]
    fn repeated_wraps_name_each_level_distinctly() {
        let doc = rooted();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Wrapped the top");
        wrap_top(&index.view(&doc), block_id(10), &mut builder);
        let doc = fold(builder, &doc);

        let mut builder = CommitBuilder::new("Wrapped it again");
        wrap_top(&index.view(&doc), block_id(11), &mut builder);
        let commit = builder.seal().expect("the wrap produced ops");
        assert_eq!(
            commit.ops().len(),
            3,
            "a root already at its demoted rect takes no geometry write"
        );
        let doc = doc
            .try_apply(&commit)
            .expect("the fold accepts the gesture");

        assert_eq!(block_of(&doc, 11).title.name, "top_2");
        assert_eq!(doc.title_block().top, block_id(11));
        assert_eq!(block_of(&doc, 10).parent, block_id(11));
    }

    #[test]
    fn wrapping_a_rootless_document_just_names_a_root() {
        let doc = wired();
        let mut index = DocIndex::default();
        assert_eq!(
            Scope::from_wire(doc.title_block().top),
            Scope::Root,
            "precondition: the document has no root yet"
        );

        let mut builder = CommitBuilder::new("Wrapped the top");
        wrap_top(&index.view(&doc), block_id(10), &mut builder);
        let commit = builder.seal().expect("the wrap produced ops");
        assert_eq!(commit.ops().len(), 2, "there is nothing to demote");
        let doc = doc
            .try_apply(&commit)
            .expect("the fold accepts the gesture");

        assert_eq!(doc.title_block().top, block_id(10));
        assert_eq!(
            Scope::from_wire(block_of(&doc, 1).parent),
            Scope::Root,
            "a block that was never the root is left where it is"
        );
    }

    #[test]
    fn the_demoted_root_grows_to_fit_its_lowest_pin() {
        let doc = rooted();
        let mut index = DocIndex::default();
        let mut builder = CommitBuilder::new("Sized the root and its pins");
        builder.push(OpCodes::Block(
            block_id(1),
            Crud::Update(BlockUpdate::Rect(rect(0, 0, 8, 4))),
        ));
        builder.push(OpCodes::Pin(
            pin_id(3),
            Crud::Update(PinUpdate::Slot(slot(PinSide::West, 3))),
        ));
        let doc = fold(builder, &doc);
        assert!(
            slot_capacity(4) < 3,
            "precondition: the root is too short for its own lowest pin"
        );

        let mut builder = CommitBuilder::new("Wrapped the top");
        wrap_top(&index.view(&doc), block_id(10), &mut builder);
        let doc = fold(builder, &doc);

        let demoted = block_of(&doc, 1).rect;
        assert_eq!(demoted.size.w, 8, "the demoted root keeps its own width");
        assert!(
            slot_capacity(demoted.size.h) >= 3,
            "the demoted height offers the lowest pin's slot"
        );
        assert_eq!(demoted.size.h, height_for_slot(3));
    }

    #[test]
    fn the_free_slot_search_finds_the_hole_in_a_packed_boundary() {
        let both = |offset| [PinSide::West, PinSide::East].map(|side| slot(side, offset));
        let mut occupied: HashSet<PinSlot> = (0..4).flat_map(both).collect();
        occupied.remove(&slot(PinSide::East, 2));
        assert_eq!(first_free_slot(&occupied), slot(PinSide::East, 2));

        assert_eq!(
            first_free_slot(&HashSet::default()),
            slot(PinSide::West, 0),
            "West comes before East at each offset"
        );
        let full: HashSet<PinSlot> = (0..4).flat_map(both).collect();
        assert_eq!(
            first_free_slot(&full),
            slot(PinSide::West, 4),
            "a full boundary hands back the first slot past its end"
        );
    }

    #[test]
    fn every_rung_of_the_height_ladder_offers_exactly_its_slot() {
        assert_eq!(height_for_slot(0), 4, "the shortest block holds one slot");
        for offset in 0..6 {
            let height = height_for_slot(offset);
            assert_eq!(slot_capacity(height), offset);
            assert_eq!(
                snap_block_height_cells(height),
                height,
                "the fitting height is itself a rung"
            );
        }
    }

    #[test]
    fn a_top_block_is_born_at_a_height_the_resize_snap_keeps() {
        assert_eq!(
            snap_block_height_cells(TOP_BLOCK_DEFAULT_HEIGHT),
            TOP_BLOCK_DEFAULT_HEIGHT
        );
    }
}