blockworx/schema/

project.rs

//! The write direction of the round trip: the folded document back as the
//! schema structs the JSON codec serializes — one format authority for both
//! directions.
//!
//! Order and naming are D11's: entities are numbered and written in **log
//! order** — where each was first created — not by where they sit now. A
//! block that moves therefore diffs as its own changed coordinates and
//! nothing else, which is the whole reason `document.json` is worth reading
//! (F5). The cost, taken deliberately, is that the projection is no longer
//! a history-independent canonical form: the same diagram built in two
//! different orders projects to two different files. `content_hash` is the
//! equality oracle that replaced it.
//!
//! Deliberately lossy, in both directions' favor: asset ids are re-derived
//! from content (a hand-written `"art.svg"` comes back as `"<hash>.svg"`),
//! and port bodies are always written explicitly rather than re-omitted when
//! they match the auto-placement — omission is a read-side reconstruction,
//! and re-running it on export would move geometry the user never touched.

use ahash::HashMap;
use base64::Engine as _;
use blockworx_doc::{
    block_model::{Asset, Block, Icon, Label, Pin},
    commit::Commit,
    document::Document,
    geometry::{GridPoint, GridRect},
    id::{BlockId, Id, IdKind, PinId, RouteId},
    opcode::{Crud, OpCodes},
    repo::Repo,
    values::{LabelSide, PinSide},
};
use uuid::Uuid;

use crate::edit::lower::{
    accent_from_role, artwork_rect, schema_label_side, schema_pin_dir, schema_pin_side,
};
use crate::path::Scope;
use crate::schema::loc::format_loc;
use crate::schema::model as schema;

/// Every naming and ordering decision the projection makes: the generated
/// spellings (`"b<N>"` per block in log order, `"p<N>"` per pin within its
/// owner) and the log order they were taken from, which the entity lists
/// below sort by.
struct Names {
    blocks: HashMap<BlockId, String>,
    pins: HashMap<PinId, (BlockId, String)>,
    created: CreationOrder,
}

impl Names {
    fn rank<K: IdKind>(&self, id: &Id<K>) -> Rank {
        self.created.rank(id)
    }
}

/// Where an entity first appears in the log — the order D11 names and
/// writes by. Not a bare index: the sort keys below say what they order by,
/// and an entity the log never created (which the fold cannot produce, but a
/// hand-built document can) sorts last instead of first.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
struct Rank(usize);

impl Rank {
    const UNCREATED: Rank = Rank(usize::MAX);
}

/// Every entity's [`Rank`], read off the log once per projection.
///
/// One table over every kind: ids are random uuids, so a single uuid space
/// is unambiguous, and creation order is a property of the document rather
/// than of any one namespace.
struct CreationOrder(HashMap<Uuid, Rank>);

impl CreationOrder {
    fn of(log: &[Commit]) -> Self {
        let mut ranks: HashMap<Uuid, Rank> = HashMap::default();
        for id in log.iter().flat_map(Commit::ops).filter_map(minted) {
            let next = Rank(ranks.len());
            ranks.entry(id).or_insert(next);
        }
        Self(ranks)
    }

    fn rank<K: IdKind>(&self, id: &Id<K>) -> Rank {
        self.0.get(&id.uuid()).copied().unwrap_or(Rank::UNCREATED)
    }
}

/// The entity an op mints, if it mints one. A restore is not a first
/// appearance — an entity is named for when it was born, and a name that
/// moved when the entity came back would be exactly the churn D11 removes.
fn minted(op: &OpCodes) -> Option<Uuid> {
    fn born<I, U, K: IdKind>(id: &Id<K>, crud: &Crud<I, U>) -> Option<Uuid> {
        matches!(crud, Crud::Create(_)).then(|| id.uuid())
    }
    match op {
        OpCodes::Block(id, crud) => born(id, crud),
        OpCodes::Pin(id, crud) => born(id, crud),
        OpCodes::Route(id, crud) => born(id, crud),
        OpCodes::RouteLabel(id, crud) => born(id, crud),
        OpCodes::Text(id, crud) => born(id, crud),
        OpCodes::Area(id, crud) => born(id, crud),
        OpCodes::Image(id, crud) => born(id, crud),
        OpCodes::Document(_) | OpCodes::Asset(..) => None,
    }
}

/// The whole document, ordered and named by log order. The inverse of
/// [`super::lower::lower`] up to minted identity.
///
/// Takes the repo rather than the folded document because the names are the
/// log's to give: the fold keeps only the latest write order, which says
/// when an entity last changed, never when it arrived.
pub fn project(repo: &Repo) -> schema::Document {
    let doc = repo.document();
    project_with(doc, CreationOrder::of(repo.log()))
}

/// Serialize `repo`'s document as the JSON document format — the whole
/// export path in one call.
pub fn to_json(repo: &Repo) -> String {
    project(repo).to_json()
}

fn project_with(doc: &Document, created: CreationOrder) -> schema::Document {
    let order = block_order(doc, &created);
    let pins = pins_by_owner(doc, &created);
    let names = Names {
        created,
        blocks: order
            .iter()
            .enumerate()
            .map(|(i, &(id, _))| (id, format!("b{i}")))
            .collect(),
        pins: pins
            .iter()
            .flat_map(|(&owner, pins)| {
                pins.iter()
                    .enumerate()
                    .map(move |(i, &(id, _))| (id, (owner, format!("p{}", i + 1))))
            })
            .collect(),
    };

    let mut assets = AssetIds::default();
    let blocks: Vec<schema::Block> = order
        .iter()
        .map(|&entry| {
            project_block(
                doc,
                entry,
                &names,
                pins.get(&entry.0).map_or(&[][..], Vec::as_slice),
                &mut assets,
            )
        })
        .collect();

    // After the blocks, so a payload's id is minted where a reader meets it
    // first.
    let root = project_scope(doc, Scope::Root, &names, &mut assets);

    let name = doc.title_block().name.as_ref();
    let top = names
        .blocks
        .get(doc.title_block().top.as_ref())
        .or_else(|| order.first().and_then(|(id, _)| names.blocks.get(id)))
        .cloned()
        .unwrap_or_default();
    schema::Document {
        version: schema::CURRENT_VERSION,
        name: (!name.is_empty()).then(|| name.clone()),
        top,
        blocks,
        routes: root.routes,
        texts: root.texts,
        areas: root.areas,
        images: root.images,
        assets: assets.assets,
    }
}

/// Position, then id, as the tiebreak below every log-order sort: two
/// entities the log never created (a hand-built document) still need a
/// total order, and one that is document state rather than a minted uuid
/// keeps the round trip stable.
fn position_key(rect: &GridRect, id: BlockId) -> (i32, i32, BlockId) {
    (rect.top_left.y, rect.top_left.x, id)
}

/// Every live block in log order — the file's own order on the way in, so a
/// re-import mints the same order it read.
fn block_order<'a>(doc: &'a Document, created: &CreationOrder) -> Vec<(BlockId, &'a Block)> {
    let mut live: Vec<(BlockId, &Block)> = doc
        .blocks()
        .filter(|(_, live)| live.is_alive())
        .map(|(id, live)| (id, live.as_ref()))
        .collect();
    live.sort_by_key(|&(id, block)| (created.rank(&id), position_key(block.rect.as_ref(), id)));
    live
}

fn pins_by_owner<'a>(
    doc: &'a Document,
    created: &CreationOrder,
) -> HashMap<BlockId, Vec<(PinId, &'a Pin)>> {
    let mut pins: HashMap<BlockId, Vec<(PinId, &Pin)>> = HashMap::default();
    for (id, live) in doc.pins().filter(|(_, live)| live.is_alive()) {
        let pin = live.as_ref();
        pins.entry(*pin.owner.as_ref()).or_default().push((id, pin));
    }
    for owned in pins.values_mut() {
        // Below the log order: two pins can share a slot (nothing in the
        // format forbids it), so the tiebreak must be document state, not
        // the minted id, or the order changes on every re-lower and the
        // round trip fails on such files. The body rect and then the name
        // settle every pair a reader could tell apart.
        owned.sort_by_key(|(id, pin)| {
            let slot = *pin.slot.as_ref();
            let rect = *pin.rect.as_ref();
            (
                created.rank(id),
                match slot.side {
                    PinSide::West => 0_u8,
                    PinSide::East => 1,
                },
                slot.offset,
                rect.top_left.y,
                rect.top_left.x,
                pin.name.as_ref().clone(),
                *id,
            )
        });
    }
    pins
}

/// Everything a scope holds beyond its blocks, projected. The document root
/// and every block go through [`project_scope`] to fill one of these, so the
/// two scopes cannot project their contents two different ways.
struct ProjectedContents {
    routes: Vec<schema::Route>,
    texts: Vec<schema::Text>,
    areas: Vec<schema::Area>,
    images: Vec<schema::Image>,
}

fn project_scope(
    doc: &Document,
    scope: Scope,
    names: &Names,
    assets: &mut AssetIds,
) -> ProjectedContents {
    let owner = scope.wire_id();

    let mut texts: Vec<(Rank, GridPoint, schema::Text)> = doc
        .texts()
        .filter(|(_, live)| live.is_alive())
        .map(|(text_id, live)| (text_id, live.as_ref()))
        .filter(|(_, text)| *text.owner.as_ref() == owner)
        .map(|(text_id, text)| {
            let pos = *text.pos.as_ref();
            (
                names.rank(&text_id),
                pos,
                schema::Text {
                    text: text.text.as_ref().clone(),
                    x: pos.x,
                    y: pos.y,
                    role: accent_from_role(*text.role.as_ref()),
                },
            )
        })
        .collect();
    texts.sort_by(|(ra, a, ta), (rb, b, tb)| {
        (ra, a.y, a.x, &ta.text).cmp(&(rb, b.y, b.x, &tb.text))
    });

    let mut areas: Vec<(Rank, schema::Area)> = doc
        .areas()
        .filter(|(_, live)| live.is_alive())
        .map(|(area_id, live)| (area_id, live.as_ref()))
        .filter(|(_, area)| *area.owner.as_ref() == owner)
        .map(|(area_id, area)| {
            let rect = *area.rect.as_ref();
            (
                names.rank(&area_id),
                schema::Area {
                    x: rect.top_left.x,
                    y: rect.top_left.y,
                    w: rect.size.w,
                    h: rect.size.h,
                    role: accent_from_role(*area.role.as_ref()),
                    title: project_label(&area.title, LabelSide::Bottom),
                },
            )
        })
        .collect();
    areas.sort_by_key(|(rank, c)| (*rank, c.y, c.x, c.w, c.h));

    let mut images: Vec<(Rank, schema::Image)> = doc
        .images()
        .filter(|(_, live)| live.is_alive())
        .map(|(image_id, live)| (image_id, live.as_ref()))
        .filter(|(_, image)| *image.owner.as_ref() == owner)
        .filter_map(|(image_id, image)| {
            let asset = assets.id_for(doc, *image.asset.as_ref())?;
            Some((
                names.rank(&image_id),
                placement(asset, *image.rect.as_ref()),
            ))
        })
        .collect();
    images.sort_by(|(ra, a), (rb, b)| {
        ra.cmp(rb)
            .then(a.y.total_cmp(&b.y))
            .then(a.x.total_cmp(&b.x))
            .then(a.asset.cmp(&b.asset))
    });

    ProjectedContents {
        routes: project_routes(doc, owner, names),
        texts: texts.into_iter().map(|(_, _, text)| text).collect(),
        areas: areas.into_iter().map(|(_, area)| area).collect(),
        images: images.into_iter().map(|(_, image)| image).collect(),
    }
}

fn project_block(
    doc: &Document,
    (id, block): (BlockId, &Block),
    names: &Names,
    pins: &[(PinId, &Pin)],
    assets: &mut AssetIds,
) -> schema::Block {
    let rect = *block.rect.as_ref();

    let mut children: Vec<(GridRect, BlockId)> = doc
        .blocks()
        .filter(|(_, live)| live.is_alive())
        .filter(|(_, live)| *live.as_ref().parent.as_ref() == id)
        .map(|(kid, live)| (*live.as_ref().rect.as_ref(), kid))
        .collect();
    children.sort_by_key(|&(rect, kid)| (names.rank(&kid), position_key(&rect, kid)));

    let contents = project_scope(doc, Scope::Block(id), names, assets);

    let icon = block.icon.as_ref();
    let icon = (*icon != Icon::default())
        .then(|| Some(placement(assets.id_for(doc, icon.asset)?, icon.rect)))
        .flatten();

    schema::Block {
        id: names.blocks[&id].clone(),
        x: rect.top_left.x,
        y: rect.top_left.y,
        w: rect.size.w,
        h: rect.size.h,
        role: accent_from_role(*block.role.as_ref()),
        locked: *block.locked.as_ref(),
        title: project_label(&block.title, LabelSide::Bottom),
        type_label: project_label(&block.type_label, LabelSide::Top),
        pins: pins
            .iter()
            .map(|&(pin_id, pin)| project_pin(pin_id, pin, names))
            .collect(),
        routes: contents.routes,
        texts: contents.texts,
        areas: contents.areas,
        images: contents.images,
        icon,
        children: children
            .into_iter()
            .map(|(_, kid)| names.blocks[&kid].clone())
            .collect(),
    }
}

fn project_pin(id: PinId, pin: &Pin, names: &Names) -> schema::Pin {
    let slot = *pin.slot.as_ref();
    let rect = *pin.rect.as_ref();
    schema::Pin {
        id: names.pins[&id].1.clone(),
        name: pin.name.as_ref().clone(),
        type_label: pin.type_name.as_ref().clone(),
        tag: pin.tag.as_ref().clone(),
        tag_hidden: *pin.tag_hidden.as_ref(),
        loc: Some(format_loc(schema_pin_side(slot.side), slot.offset)),
        x: Some(rect.top_left.x),
        y: Some(rect.top_left.y),
        w: Some(rect.size.w),
        dir: schema_pin_dir(*pin.dir.as_ref()),
        // Stub and port-pin accents are derived from route roles (swap D2)
        // and are never document state, so they are never exported.
        pin_accent: None,
        port_accent: accent_from_role(*pin.port_accent.as_ref()),
        port_pin_accent: None,
        fliplr: *pin.flip_lr.as_ref(),
    }
}

fn project_routes(doc: &Document, owner: BlockId, names: &Names) -> Vec<schema::Route> {
    // Every anchor names a pin of some *block*, bare on the route's own block
    // and qualified otherwise. A port of the document root has no block to
    // name it, so a route onto one is unspellable and drops below.
    let spell = |pin: PinId| -> Option<String> {
        let (pin_owner, name) = names.pins.get(&pin)?;
        let block = names.blocks.get(pin_owner)?;
        Some(if *pin_owner == owner {
            name.clone()
        } else {
            format!("{block}:{name}")
        })
    };
    let mut labels: HashMap<RouteId, Vec<f32>> = HashMap::default();
    for (_, live) in doc.route_labels().filter(|(_, live)| live.is_alive()) {
        let label = live.as_ref();
        labels
            .entry(*label.owner.as_ref())
            .or_default()
            .push((*label.pos.as_ref()).into());
    }

    let mut routes: Vec<(Rank, schema::Route)> = doc
        .routes()
        .filter(|(_, live)| live.is_alive())
        .filter(|(_, live)| *live.as_ref().owner.as_ref() == owner)
        .filter_map(|(id, live)| {
            let route = live.as_ref();
            let (Some(from), Some(to)) = (spell(route.from), spell(route.to)) else {
                // Unreachable through the fold (it refuses a route whose
                // endpoint is absent), so worth a loud note if it happens.
                tracing::warn!("not exporting a route with an unresolvable endpoint");
                return None;
            };
            let mut positions = labels.remove(&id).unwrap_or_default();
            positions.sort_by(|a, b| a.total_cmp(b));
            Some((
                names.rank(&id),
                schema::Route {
                    name: route.name.as_ref().clone(),
                    from,
                    to,
                    role: accent_from_role(*route.role.as_ref()),
                    waypoints: route
                        .waypoints
                        .as_ref()
                        .iter()
                        .map(|w| schema::Waypoint {
                            x: w.pos.x,
                            y: w.pos.y,
                            locked: w.locked,
                        })
                        .collect(),
                    labels: positions,
                },
            ))
        })
        .collect();
    routes.sort_by(|(ra, a), (rb, b)| {
        (ra, &a.from, &a.to, &a.name).cmp(&(rb, &b.from, &b.to, &b.name))
    });
    routes.into_iter().map(|(_, route)| route).collect()
}

/// A label namespace back as the schema's optional label. Collapses in two
/// steps mirroring the loader's fallbacks: a side equal to the per-kind
/// fallback is omitted, and a label all of whose fields are at their
/// omitted-state values is not written at all.
fn project_label(label: &Label, fallback: LabelSide) -> Option<schema::Label> {
    let name = label.name.as_ref();
    let side = *label.side.as_ref();
    let offset: f32 = (*label.offset.as_ref()).into();
    let hidden = *label.hidden.as_ref();
    if name.is_empty() && side == fallback && offset == 0.0 && !hidden {
        return None;
    }
    Some(schema::Label {
        name: name.clone(),
        side: (side != fallback).then(|| schema_label_side(side)),
        offset,
        hidden,
    })
}

fn placement(asset: String, rect: blockworx_doc::geometry::ScreenRect) -> schema::Image {
    let rect = artwork_rect(rect);
    schema::Image {
        asset,
        x: rect.min.x,
        y: rect.min.y,
        w: rect.width(),
        h: rect.height(),
    }
}

/// Payloads keyed by their content hash, named content-derived
/// (`"<hash16>.<ext>"`) exactly as the legacy writer named them — equal
/// images get equal ids in every document, and an unrelated edit never
/// renumbers anything.
#[derive(Default)]
struct AssetIds {
    ids: Vec<(blockworx_doc::hash::AssetHash, String)>,
    assets: Vec<schema::Asset>,
}

impl AssetIds {
    /// The id naming `hash`, minting (and recording the payload) on first
    /// sight. `None` where the document holds a placement but not the bytes
    /// it names — the fold ought to bar that, so it is worth a loud note.
    fn id_for(&mut self, doc: &Document, hash: blockworx_doc::hash::AssetHash) -> Option<String> {
        if let Some((_, id)) = self.ids.iter().find(|(seen, _)| *seen == hash) {
            return Some(id.clone());
        }
        let Some(asset) = doc.asset(&hash) else {
            tracing::warn!("not exporting a placement of {hash}: the document holds no payload");
            return None;
        };
        let (bytes, ext, image) = match asset {
            Asset::Svg(bytes) => (
                &**bytes,
                "svg",
                schema::ImageData::Svg(String::from_utf8_lossy(bytes).into_owned()),
            ),
            Asset::Png(bytes) => (
                &**bytes,
                "png",
                schema::ImageData::Png(base64::engine::general_purpose::STANDARD.encode(bytes)),
            ),
        };
        let id = format!("{}.{ext}", &blake3::hash(bytes).to_hex()[..16]);
        self.assets.push(schema::Asset {
            id: id.clone(),
            image,
        });
        self.ids.push((hash, id.clone()));
        Some(id)
    }
}

#[cfg(test)]
pub(crate) mod tests {
    use super::*;
    use crate::schema::lower::lower;

    /// `lower`'s own everything-in-one-file fixture, round-tripped here.
    const RICH: &str = crate::schema::lower::tests::RICH;

    /// Lower and fold a parsed document into a repo — the projection's own
    /// oracle for what a session seeded from it would hold, and the log the
    /// sticky names come from. Shared with the round-trip gates
    /// ([`crate::schema::roundtrip`]).
    pub(crate) fn folded_repo(doc: &schema::Document, label: &str) -> Repo {
        let lowered = lower(doc, label);
        Repo::folding(&lowered.commits).expect("the lowered commits fold")
    }

    fn folded(src: &str) -> Repo {
        let parsed = schema::Document::parse_json(src, "project").expect("the fixture parses");
        folded_repo(&parsed, "project")
    }

    fn block_named<'a>(doc: &'a schema::Document, title: &str) -> &'a schema::Block {
        doc.blocks
            .iter()
            .find(|b| b.title.as_ref().is_some_and(|t| t.name == title))
            .unwrap_or_else(|| panic!("no projected block titled {title:?}"))
    }

    /// The projection carries every stored field back out — spot-checked
    /// against the fixture's own values so a field `project` dropped cannot
    /// hide behind the round trip's symmetry.
    #[test]
    fn the_rich_fixture_projects_with_its_fields_intact() {
        let projected = project(&folded(RICH));

        assert_eq!(projected.version, schema::CURRENT_VERSION);
        assert_eq!(projected.name.as_deref(), Some("bridge"));

        let sheet = block_named(&projected, "sheet");
        assert_eq!(projected.top, sheet.id, "the top pointer survives");
        assert_eq!((sheet.x, sheet.y, sheet.w, sheet.h), (0, 0, 30, 20));
        let title = sheet.title.as_ref().expect("the sheet keeps its title");
        assert_eq!(
            (title.side, title.offset, title.hidden),
            (Some(crate::schema::enums::LabelSide::Center), 1.5, true),
        );

        let core = block_named(&projected, "core");
        assert_eq!(sheet.children, vec![core.id.clone()], "nesting survives");
        assert_eq!(core.role, Some(3));
        assert!(core.locked);
        assert_eq!(
            core.type_label.as_ref().map(|t| (t.name.as_str(), t.side)),
            Some(("Add", None)),
            "a type label at its per-kind default side omits the side",
        );

        let pin = |block: &schema::Block, name: &str| -> schema::Pin {
            block
                .pins
                .iter()
                .find(|p| p.name == name)
                .unwrap_or_else(|| panic!("no projected pin named {name:?}"))
                .clone()
        };
        let input = pin(sheet, "in");
        assert_eq!(input.loc.as_deref(), Some("w0"));
        assert_eq!(input.dir, Some(crate::schema::enums::PinType::Input));
        assert_eq!((input.tag.as_str(), input.tag_hidden), ("A", true));
        assert_eq!(input.port_accent, Some(2));
        assert!(input.fliplr);
        assert!(
            input.x.is_some() && input.w.is_some(),
            "an omitted port body exports explicitly once reconstructed",
        );
        let output = pin(sheet, "out");
        assert_eq!((output.x, output.y, output.w), (Some(4), Some(6), Some(5)));
        assert_eq!(output.type_label, "bit");
        assert_eq!(
            pin(core, "a").dir,
            None,
            "an in-out pin omits `dir`, the spelling that reads back as in-out",
        );

        let route = {
            assert_eq!(sheet.routes.len(), 1, "the dangling route stayed dropped");
            &sheet.routes[0]
        };
        assert_eq!(route.name, "net");
        assert_eq!(route.role, Some(1));
        assert_eq!(
            route.from,
            pin(sheet, "in").id,
            "an own-block anchor is bare"
        );
        assert_eq!(
            route.to,
            format!("{}:{}", core.id, pin(core, "a").id),
            "a child anchor is qualified",
        );
        assert_eq!(
            route.waypoints,
            vec![
                schema::Waypoint {
                    x: 12,
                    y: 35,
                    locked: false
                },
                schema::Waypoint {
                    x: 2,
                    y: 41,
                    locked: true
                },
            ],
        );
        assert_eq!(route.labels, vec![7.5]);

        assert_eq!(sheet.texts.len(), 1);
        assert_eq!(
            (sheet.texts[0].x, sheet.texts[0].y, sheet.texts[0].role),
            (10, 5, Some(1)),
        );
        assert_eq!(sheet.areas.len(), 1);
        assert_eq!(
            sheet.areas[0].title.as_ref().map(|t| t.name.as_str()),
            Some("group"),
        );

        assert_eq!(projected.assets.len(), 1, "one payload for two placements");
        let asset = &projected.assets[0];
        assert_eq!(
            asset.id,
            format!("{}.svg", &blake3::hash(b"<svg/>").to_hex()[..16]),
            "the id is content-derived, replacing the file's own spelling",
        );
        assert_eq!(sheet.images.len(), 1);
        assert_eq!(sheet.images[0].asset, asset.id);
        assert_eq!(
            sheet.icon.as_ref().map(|icon| icon.asset.as_str()),
            Some(asset.id.as_str()),
        );
        assert_ne!(
            (sheet.images[0].x, sheet.images[0].y),
            (
                sheet.icon.as_ref().unwrap().x,
                sheet.icon.as_ref().unwrap().y
            ),
            "the two placements keep their own boxes",
        );
    }

    /// The round trip: projected JSON, read back through the real pipeline,
    /// projects identically — lowering mints ids in file order, so the file
    /// order it read is the creation order it writes back.
    #[test]
    fn parse_lower_fold_project_is_identity_on_the_projection() {
        let projected = project(&folded(RICH));
        let reparsed = schema::Document::parse_json(&projected.to_json(), "projection")
            .expect("the projection parses as JSON");
        assert_eq!(project(&folded_repo(&reparsed, "project")), projected);
    }

    /// A source document whose file order disagrees with every positional
    /// order — the fixture the stickiness test needs.
    const OUT_OF_ORDER: &str = r#"
{
  "version": 2,
  "top": "b0",
  "blocks": [
    {
      "id": "b0",
      "x": 0,
      "y": 0,
      "w": 40,
      "h": 40,
      "title": {
        "name": "sheet"
      },
      "children": [
        "b1",
        "b2"
      ]
    },
    {
      "id": "b1",
      "x": 0,
      "y": 20,
      "w": 8,
      "h": 5,
      "title": {
        "name": "lower"
      }
    },
    {
      "id": "b2",
      "x": 0,
      "y": 5,
      "w": 8,
      "h": 5,
      "title": {
        "name": "upper"
      }
    }
  ]
}
"#;

    /// D11: names come from the log, so moving a block changes that block's
    /// coordinates and nothing else. The precondition is asserted, not
    /// assumed — under the positional order this replaced, `b1` and `b2`
    /// would already have swapped before the move, and would swap again
    /// after it.
    #[test]
    fn a_move_changes_one_blocks_coordinates_and_no_ones_name() {
        let mut repo = folded(OUT_OF_ORDER);
        let named = |doc: &schema::Document, title: &str| -> schema::Block {
            doc.blocks
                .iter()
                .find(|b| b.title.as_ref().is_some_and(|t| t.name == title))
                .unwrap_or_else(|| panic!("no projected block titled {title:?}"))
                .clone()
        };

        let before = project(&repo);
        assert_eq!(
            (named(&before, "lower").id, named(&before, "upper").id),
            ("b1".to_owned(), "b2".to_owned()),
            "names follow the file's order",
        );
        assert!(
            named(&before, "upper").y < named(&before, "lower").y,
            "precondition: the file order already disagrees with the positional \
             one, so `upper` would have been b1 under the numbering this replaced",
        );

        let lower_id = repo
            .document()
            .blocks()
            .find(|(_, live)| live.as_ref().title.name.as_ref() == "lower")
            .map(|(id, _)| id)
            .expect("the lower block is in the document");
        repo.submit(Commit::new(
            "Moved a block".to_owned(),
            vec![OpCodes::Block(
                lower_id,
                Crud::Update(blockworx_doc::block_model::BlockUpdate::Rect(GridRect {
                    top_left: GridPoint { x: 0, y: 1 },
                    size: blockworx_doc::geometry::GridSize { w: 8, h: 5 },
                })),
            )],
        ))
        .expect("the move folds");

        let after = project(&repo);
        assert!(
            named(&after, "lower").y < named(&after, "upper").y,
            "precondition: the move crossed the two blocks, so the positional \
             numbering would have swapped them a second time",
        );
        assert_eq!(
            after.blocks.iter().map(|b| &b.id).collect::<Vec<_>>(),
            before.blocks.iter().map(|b| &b.id).collect::<Vec<_>>(),
            "the numbering must not follow the move",
        );
        let differing: Vec<&str> = before
            .blocks
            .iter()
            .zip(&after.blocks)
            .filter(|(was, is)| was != is)
            .map(|(was, _)| was.id.as_str())
            .collect();
        assert_eq!(differing, vec!["b1"], "only the moved block differs");
        assert_eq!(named(&after, "lower").y, 1);
    }

    /// The degenerate export: nothing to say, but still a well-formed
    /// document shape (an empty block list and an empty top pointer).
    #[test]
    fn an_empty_document_projects_empty() {
        let projected = project(&Repo::default());
        assert_eq!(projected.blocks, vec![]);
        assert_eq!(projected.top, "");
        assert_eq!(projected.name, None);
    }
}