blockworx/document/

schema_convert.rs

//! App-side bridge between the in-memory [`Document`] model and the
//! standalone on-disk [`crate::schema`] representation. Everything that couples
//! the schema crate to `document` lives here: the infallible `from_*`
//! projection, the fallible `into_*` reconstruction, the JSON/KDL wrapper
//! functions, and the hand-written enum bridges (the schema enums carry serde;
//! the `document` enums carry the domain).
//!
//! `SchemaError` carries the source text (for `miette` diagnostics), so it is
//! large by design — the internal `Result`s accept that rather than boxing.
#![allow(clippy::result_large_err)]

use std::str::FromStr;

use base64::Engine as _;

use blockworx_doc::geometry::{
    GridPoint, GridRect as DocGridRect, GridSize as DocGridSize, PinSlot,
};

use crate::document::{
    Asset, AutoRoute, Block, BlockLabel, Comment, Decorations, Document, GridPos, GridRect,
    GridSize, Image, ImageData, LabelSide, LineAnchor, LinearDistance, PinPort, PinSide, PinType,
    TextBox, Waypoint,
};
use crate::edit::lower::pin_side;
use crate::presentation::store::{IdMap, IdMapExt, IdSet};
use crate::schema::SchemaError;
use crate::schema::enums;
use crate::schema::loc::{format_loc, parse_loc};
use crate::schema::model as schema;
use crate::shape::port::PORT_HEIGHT;
use crate::store::{CommentId, ImageId, PinId, RectId, RouteId, TextId, WaypointId, WireLabelId};

/// The legacy grid rect in the document crate's spelling — the two are the
/// same value, and this file is the only place they still meet.
fn as_doc(rect: GridRect) -> DocGridRect {
    DocGridRect {
        top_left: GridPoint {
            x: rect.min.x,
            y: rect.min.y,
        },
        size: DocGridSize {
            w: rect.size.w,
            h: rect.size.h,
        },
    }
}

fn from_doc(rect: DocGridRect) -> GridRect {
    GridRect::new(
        GridPos::new(rect.top_left.x, rect.top_left.y),
        GridSize::new(rect.size.w, rect.size.h),
    )
}

/// Port-body auto-placement, the on-disk round trip's half of it: a pin
/// whose body sits where the auto-placement would put it omits its geometry
/// on disk, and a file that omitted it has the body rebuilt on load. The
/// placement itself is [`crate::edit::create::default_port_rect`] — one
/// formula, so a change to it cannot leave the file format behind.
impl Block {
    fn default_port_rect(&self, name: &str, side: PinSide, offset: u32) -> GridRect {
        // Every stored body, zero-width sentinels included: a zero rect
        // intersects nothing, so an unplaced port never blocks a placement.
        let siblings: Vec<DocGridRect> = self.pins.values().map(|p| as_doc(p.rect)).collect();
        from_doc(crate::edit::create::default_port_rect(
            as_doc(self.inner),
            &siblings,
            name,
            PinSlot {
                side: pin_side(side.into()),
                offset,
            },
        ))
    }

    /// Fill any port whose `rect` is unset (zero width — the sentinel a schema
    /// load leaves when a pin omits its geometry) via [`Self::default_port_rect`],
    /// in stored order so each placement avoids the ports already positioned.
    /// Ports that carry an explicit rect are left untouched.
    fn fill_missing_port_rects(&mut self) {
        let ids: Vec<PinId> = self.pins.keys().copied().collect();
        for id in ids {
            if self.pins[&id].rect.size.w != 0 {
                continue;
            }
            let (name, side, offset) = {
                let p = &self.pins[&id];
                (p.name.clone(), p.side, p.offset)
            };
            let rect = self.default_port_rect(&name, side, offset);
            if let Some(p) = self.pins.get_mut(&id) {
                p.rect = rect;
            }
        }
    }

    /// The port rects this block *would* have if every port were auto-placed. A
    /// port whose stored rect equals its auto rect can omit its geometry on disk
    /// (it is reconstructed by [`Self::fill_missing_port_rects`] on load).
    fn auto_port_rects(&self) -> Vec<(PinId, GridRect)> {
        let mut probe = self.clone();
        for p in probe.pins.values_mut() {
            p.rect = GridRect::default();
        }
        probe.fill_missing_port_rects();
        probe.pins.iter().map(|(&id, p)| (id, p.rect)).collect()
    }
}

// ── Enum bridges ────────────────────────────────────────────────────────────
// The schema enums carry serde; the domain enums carry no serde. These 1:1
// bridges are the only place the two vocabularies meet.

impl From<PinSide> for enums::PinSide {
    fn from(v: PinSide) -> Self {
        match v {
            PinSide::East => enums::PinSide::East,
            PinSide::West => enums::PinSide::West,
        }
    }
}
impl From<enums::PinSide> for PinSide {
    fn from(v: enums::PinSide) -> Self {
        match v {
            enums::PinSide::East => PinSide::East,
            enums::PinSide::West => PinSide::West,
        }
    }
}

impl From<PinType> for enums::PinType {
    fn from(v: PinType) -> Self {
        match v {
            PinType::Input => enums::PinType::Input,
            PinType::Output => enums::PinType::Output,
            PinType::InOut => enums::PinType::InOut,
        }
    }
}
impl From<enums::PinType> for PinType {
    fn from(v: enums::PinType) -> Self {
        match v {
            enums::PinType::Input => PinType::Input,
            enums::PinType::Output => PinType::Output,
            enums::PinType::InOut => PinType::InOut,
        }
    }
}

impl From<LabelSide> for enums::LabelSide {
    fn from(v: LabelSide) -> Self {
        match v {
            LabelSide::Top => enums::LabelSide::Top,
            LabelSide::Center => enums::LabelSide::Center,
            LabelSide::Bottom => enums::LabelSide::Bottom,
        }
    }
}
impl From<enums::LabelSide> for LabelSide {
    fn from(v: enums::LabelSide) -> Self {
        match v {
            enums::LabelSide::Top => LabelSide::Top,
            enums::LabelSide::Center => LabelSide::Center,
            enums::LabelSide::Bottom => LabelSide::Bottom,
        }
    }
}

// ── from_document: infallible projection onto the on-disk schema ─────────────

impl From<&Document> for schema::Document {
    fn from(doc: &Document) -> Self {
        let mut assets = AssetIds::default();
        let blocks = doc
            .blocks
            .iter()
            .map(|(&id, b)| schema::Block::from_block(id, b, &mut assets))
            .collect();
        schema::Document {
            // Always written at the current version: the in-memory document is
            // whatever this build understands, whatever it was loaded from.
            version: schema::CURRENT_VERSION,
            name: doc.name.clone(),
            top: doc.top_id.to_string(),
            blocks,
            assets: assets.into_assets(),
        }
    }
}

/// The raw bytes an asset is stored as, and the extension naming its format.
/// This is exactly what a container writes to `assets/<id>`, so the hash below
/// is a hash of the file, not of some other encoding of it.
fn asset_bytes(image: &ImageData) -> (&[u8], &'static str) {
    match image {
        ImageData::Svg(src) => (src.as_bytes(), "svg"),
        ImageData::Png(bytes) => (bytes, "png"),
    }
}

/// The content-derived id for `image`: `<hash>.<ext>`, which is also the name it
/// takes inside a container.
///
/// Truncated to 16 hex characters — 64 bits. Eight would collide at around 77k
/// assets, and a collision here does not fail loudly, it silently swaps one
/// image for another.
pub fn asset_id(image: &ImageData) -> String {
    let (bytes, ext) = asset_bytes(image);
    let hash = blake3::hash(bytes).to_hex();
    format!("{}.{ext}", &hash[..16])
}

/// The bytes a container writes to `assets/<id>` for `asset`. These are the
/// bytes the id hashes, so the file's name really does describe its content.
pub fn asset_to_bytes(asset: &schema::Asset) -> Result<Vec<u8>, SchemaError> {
    match &asset.image {
        schema::ImageData::Svg(src) => Ok(src.clone().into_bytes()),
        schema::ImageData::Png(b64) => base64::engine::general_purpose::STANDARD
            .decode(b64.as_bytes())
            .map_err(|e| SchemaError::AssetPng {
                asset: asset.id.clone(),
                reason: e.to_string(),
            }),
    }
}

/// The inverse: an asset read back out of `assets/<id>`. The format comes from
/// the id's extension, which inside a container is the only thing that carries
/// it — there is no `svg`/`png` child node to read.
pub fn asset_from_bytes(id: &str, bytes: Vec<u8>) -> Result<schema::Asset, SchemaError> {
    let ext = id.rsplit_once('.').map(|(_, ext)| ext).unwrap_or_default();
    let image = match ext {
        "svg" => {
            schema::ImageData::Svg(String::from_utf8(bytes).map_err(|e| SchemaError::AssetPng {
                asset: id.to_string(),
                reason: format!("not valid UTF-8: {e}"),
            })?)
        }
        "png" => schema::ImageData::Png(base64::engine::general_purpose::STANDARD.encode(&bytes)),
        other => {
            return Err(SchemaError::AssetPng {
                asset: id.to_string(),
                reason: format!("{other:?} is not an image format this build stores"),
            });
        }
    };
    Ok(schema::Asset {
        id: id.to_string(),
        image,
    })
}

/// Names each distinct image once, so an image placed many times is written once
/// and referenced by id. The id is derived from the content, so equal images get
/// equal ids in every document, and an unrelated edit never renumbers anything.
/// Interned content hashes and compares by pointer, so the lookup never touches
/// the bytes.
#[derive(Default)]
pub struct AssetIds {
    ids: std::collections::HashMap<Asset, String>,
    assets: Vec<schema::Asset>,
}

impl AssetIds {
    /// The id naming `asset`, minting (and recording) one on first sight.
    fn id_for(&mut self, asset: &Asset) -> String {
        if let Some(id) = self.ids.get(asset) {
            return id.clone();
        }
        let id = asset_id(asset);
        self.assets.push(schema::Asset {
            id: id.clone(),
            image: match &**asset {
                ImageData::Svg(src) => schema::ImageData::Svg(src.clone()),
                ImageData::Png(bytes) => {
                    schema::ImageData::Png(base64::engine::general_purpose::STANDARD.encode(bytes))
                }
            },
        });
        self.ids.insert(asset.clone(), id.clone());
        id
    }

    pub fn into_assets(self) -> Vec<schema::Asset> {
        self.assets
    }
}

/// The image content of a parsed document, keyed by the id its placements
/// reference. Interning happens here, so equal content loaded from anywhere —
/// this document, a paste, another file — ends up sharing one allocation.
pub struct Assets(std::collections::HashMap<String, Asset>);

impl Assets {
    /// Decode and intern every asset, rejecting duplicate ids (KDL catches these
    /// with a span; JSON has no span to point at).
    pub fn decode(assets: Vec<schema::Asset>) -> Result<Self, SchemaError> {
        let mut map = std::collections::HashMap::new();
        for a in assets {
            let image = match a.image {
                schema::ImageData::Svg(svg) => ImageData::Svg(svg),
                schema::ImageData::Png(png) => ImageData::Png(
                    base64::engine::general_purpose::STANDARD
                        .decode(png.as_bytes())
                        .map_err(|e| SchemaError::AssetPng {
                            asset: a.id.clone(),
                            reason: e.to_string(),
                        })?,
                ),
            };
            if map.insert(a.id.clone(), Asset::from(image)).is_some() {
                return Err(SchemaError::DuplicateAsset { asset: a.id });
            }
        }
        Ok(Self(map))
    }

    fn get(&self, id: &str, block: &str) -> Result<Asset, SchemaError> {
        self.0
            .get(id)
            .cloned()
            .ok_or_else(|| SchemaError::UnknownAsset {
                block: block.to_string(),
                asset: id.to_string(),
            })
    }
}

/// Round a continuous quantity (label/route positions, sizes) to 1 decimal, so
/// the on-disk form stays clean and greppable.
fn round1(v: f32) -> f32 {
    (v * 10.0).round() / 10.0
}

/// Emit a block label only when it differs from its per-kind `default`; `side` is
/// dropped when it matches the default placement.
fn from_label(label: &BlockLabel, default: &BlockLabel) -> Option<schema::Label> {
    if label == default {
        return None;
    }
    Some(schema::Label {
        name: label.name.clone(),
        side: (label.side != default.side).then(|| enums::LabelSide::from(label.side)),
        offset: round1(label.offset),
        hidden: label.hidden,
    })
}

impl schema::Block {
    pub fn from_block(id: RectId, b: &Block, assets: &mut AssetIds) -> Self {
        // A port whose rect equals the auto-placement default omits its geometry
        // (reconstructed on load); others carry it verbatim.
        let auto: std::collections::HashMap<PinId, GridRect> =
            b.auto_port_rects().into_iter().collect();
        schema::Block {
            id: id.to_string(),
            x: b.inner.min.x,
            y: b.inner.min.y,
            w: b.inner.size.w,
            h: b.inner.size.h,
            role: b.role,
            locked: b.locked,
            title: from_label(&b.decorations.title, &BlockLabel::default()),
            type_label: from_label(&b.decorations.type_label, &BlockLabel::upper_left()),
            pins: b
                .pins
                .iter()
                .map(|(&id, p)| schema::Pin::from_pin(id, p, auto.get(&id).copied()))
                .collect(),
            routes: b.routes.values().map(schema::Route::from_route).collect(),
            texts: b.texts.values().map(schema::Text::from_text).collect(),
            comments: b
                .comments
                .values()
                .map(schema::Comment::from_comment)
                .collect(),
            images: b
                .images
                .values()
                .map(|s| schema::Image::from_symbol(s, assets))
                .collect(),
            icon: b
                .icon
                .as_ref()
                .map(|s| schema::Image::from_symbol(s, assets)),
            children: b.children.iter().map(|&cid| cid.to_string()).collect(),
        }
    }
}

impl schema::Pin {
    pub fn from_pin(id: PinId, p: &PinPort, auto: Option<GridRect>) -> Self {
        // Omit geometry when it matches the auto-placed default (height is always
        // `PORT_HEIGHT`, never stored).
        let is_auto = auto == Some(p.rect);
        schema::Pin {
            id: id.to_string(),
            name: p.name.clone(),
            type_label: p.type_label.clone(),
            tag: p.tag.clone(),
            tag_hidden: p.tag_hidden,
            loc: Some(format_loc(p.side.into(), p.offset)),
            x: (!is_auto).then_some(p.rect.min.x),
            y: (!is_auto).then_some(p.rect.min.y),
            w: (!is_auto).then_some(p.rect.size.w),
            dir: (p.kind != PinType::InOut).then(|| p.kind.into()),
            // The stub accents are derived from route roles now, never
            // stored — the keys stay in the schema so old files decode,
            // but nothing writes them anymore.
            pin_accent: None,
            port_accent: p.port_accent,
            port_pin_accent: None,
            // A port faces `side.flip()` (natural) or `side` (flipped); the
            // boolean records the flipped case.
            fliplr: p.port_orientation == Some(p.side),
        }
    }
}

impl schema::Route {
    pub fn from_route(r: &AutoRoute) -> Self {
        schema::Route {
            name: r.route_name().to_string(),
            from: LineAnchor::to_string(&r.start()),
            to: LineAnchor::to_string(&r.finish()),
            role: r.role(),
            waypoints: r
                .iter_waypoints()
                .map(|(_, w)| schema::Waypoint {
                    x: w.pos.x,
                    y: w.pos.y,
                    locked: w.locked,
                })
                .collect(),
            labels: r
                .iter_labels()
                .map(|(_, &d)| round1(f32::from(d)))
                .collect(),
        }
    }
}

impl schema::Text {
    pub fn from_text(t: &TextBox) -> Self {
        schema::Text {
            text: t.text.clone(),
            x: t.anchor.x,
            y: t.anchor.y,
            role: t.role,
        }
    }
}

impl schema::Comment {
    pub fn from_comment(c: &Comment) -> Self {
        schema::Comment {
            x: c.inner.min.x,
            y: c.inner.min.y,
            w: c.inner.size.w,
            h: c.inner.size.h,
            role: c.role,
            title: from_label(&c.title, &BlockLabel::default()),
        }
    }
}

impl schema::Image {
    pub fn from_symbol(s: &Image, assets: &mut AssetIds) -> Self {
        schema::Image {
            asset: assets.id_for(&s.image),
            x: round1(s.inner.min.x),
            y: round1(s.inner.min.y),
            w: round1(s.inner.width()),
            h: round1(s.inner.height()),
        }
    }
}

// ── into_document: fallible reconstruction from the on-disk schema ───────────

fn parse_id<T: FromStr<Err = String>>(kind: &'static str, s: &str) -> Result<T, SchemaError> {
    s.parse().map_err(|reason| SchemaError::Id {
        kind,
        value: s.to_string(),
        reason,
    })
}

fn parse_anchor(block: &str, s: &str) -> Result<LineAnchor, SchemaError> {
    let anchor_err = |reason: String| SchemaError::Anchor {
        block: block.to_string(),
        value: s.to_string(),
        reason,
    };
    if let Some((b, p)) = s.split_once(':') {
        Ok(LineAnchor::Pin {
            block: b.parse().map_err(anchor_err)?,
            pin: p.parse().map_err(anchor_err)?,
        })
    } else {
        Ok(LineAnchor::Port(s.parse().map_err(anchor_err)?))
    }
}

impl schema::Label {
    fn into_label(self, default: &BlockLabel) -> BlockLabel {
        BlockLabel {
            name: self.name,
            hidden: self.hidden,
            side: self.side.map_or(default.side, Into::into),
            offset: self.offset,
        }
    }
}

fn label_or(dto: Option<schema::Label>, default: BlockLabel) -> BlockLabel {
    match dto {
        Some(l) => l.into_label(&default),
        None => default,
    }
}

impl schema::Document {
    pub fn into_document(self) -> Result<Document, SchemaError> {
        let top_id: RectId = self.top.parse().map_err(|reason| SchemaError::BadTop {
            value: self.top.clone(),
            reason,
        })?;
        let assets = Assets::decode(self.assets)?;
        let mut blocks: IdMap<RectId, Block> = IdMap::default();
        for sb in self.blocks {
            let (id, block) = sb.into_block(&assets)?;
            blocks.insert(id, block);
        }
        if !blocks.contains_key(&top_id) {
            return Err(SchemaError::BadTop {
                value: self.top,
                reason: "no block with that id".into(),
            });
        }
        validate_children(&blocks)?;
        Ok(Document {
            name: self.name,
            top_id,
            blocks: blocks.into(),
        })
    }
}

/// Strict on load (unlike the lenient runtime `child_blocks`): a child id that
/// isn't in the document is a hand-edit error worth surfacing.
fn validate_children(blocks: &IdMap<RectId, Block>) -> Result<(), SchemaError> {
    for (bid, block) in blocks {
        for cid in &block.children {
            if !blocks.contains_key(cid) {
                return Err(SchemaError::DanglingChild {
                    block: bid.to_string(),
                    child: cid.to_string(),
                });
            }
        }
    }
    Ok(())
}

impl schema::Block {
    pub fn into_block(self, assets: &Assets) -> Result<(RectId, Block), SchemaError> {
        let id: RectId = parse_id("block", &self.id)?;
        let block_ctx = self.id;

        let decorations = Decorations {
            title: label_or(self.title, BlockLabel::default()),
            type_label: label_or(self.type_label, BlockLabel::upper_left()),
        };

        let mut pins: IdMap<PinId, PinPort> = IdMap::default();
        for p in self.pins {
            let (pid, pin) = p.into_pin(&block_ctx)?;
            pins.insert(pid, pin);
        }

        // Routes/texts/comments/images carry no id on disk; mint fresh ones in
        // stored order.
        let mut routes: IdMap<RouteId, AutoRoute> = IdMap::default();
        for r in self.routes {
            routes.insert_value(r.into_route(&block_ctx)?);
        }

        let mut texts: IdMap<TextId, TextBox> = IdMap::default();
        for t in self.texts {
            texts.insert_value(t.into_text());
        }

        let mut comments: IdMap<CommentId, Comment> = IdMap::default();
        for c in self.comments {
            comments.insert_value(c.into_comment());
        }

        let mut images: IdMap<ImageId, Image> = IdMap::default();
        for s in self.images {
            images.insert_value(s.into_symbol(&block_ctx, assets)?);
        }
        let icon = match self.icon {
            Some(s) => Some(s.into_symbol(&block_ctx, assets)?),
            None => None,
        };

        let mut children: IdSet<RectId> = IdSet::default();
        for cid in self.children {
            children.insert(parse_id("block", &cid)?);
        }

        let block = Block {
            inner: GridRect::new(GridPos::new(self.x, self.y), GridSize::new(self.w, self.h)),
            decorations,
            pins,
            children,
            routes,
            texts,
            comments,
            images,
            icon,
            role: self.role,
            locked: self.locked,
        };
        // Reconstruct any port geometry omitted on disk (matched the auto default).
        let mut block = block;
        block.fill_missing_port_rects();
        Ok((id, block))
    }
}

impl schema::Pin {
    pub fn into_pin(self, block: &str) -> Result<(PinId, PinPort), SchemaError> {
        let id: PinId = parse_id("pin", &self.id)?;
        let loc = self.loc.ok_or_else(|| SchemaError::MissingPinSide {
            block: block.to_string(),
            pin: self.id.clone(),
        })?;
        let (side, offset) = parse_loc(&loc).map_err(|reason| SchemaError::BadLoc {
            block: block.to_string(),
            pin: self.id.clone(),
            value: loc.clone(),
            reason,
        })?;
        let side: PinSide = side.into();
        let pin = PinPort {
            name: self.name,
            type_label: self.type_label,
            tag: self.tag,
            tag_hidden: self.tag_hidden,
            side,
            offset,
            // Omitted geometry leaves a zero-width sentinel; `fill_missing_port_rects`
            // (called by `into_block`) reconstructs it. Height is always PORT_HEIGHT.
            rect: match (self.x, self.y, self.w) {
                (Some(x), Some(y), Some(w)) => {
                    GridRect::new(GridPos::new(x, y), GridSize::new(w, PORT_HEIGHT))
                }
                _ => GridRect::default(),
            },
            kind: self.dir.map(Into::into).unwrap_or_default(),
            port_accent: self.port_accent,
            // Flipped ⇒ facing == side; natural ⇒ None (facing derives side.flip()).
            port_orientation: self.fliplr.then_some(side),
        };
        Ok((id, pin))
    }
}

impl schema::Route {
    pub fn into_route(self, block: &str) -> Result<AutoRoute, SchemaError> {
        let from = parse_anchor(block, &self.from)?;
        let to = parse_anchor(block, &self.to)?;

        let mut waypoints: IdMap<WaypointId, Waypoint> = IdMap::default();
        for w in self.waypoints {
            waypoints.insert_value(Waypoint {
                pos: GridPos::new(w.x, w.y),
                locked: w.locked,
            });
        }
        let mut labels: IdMap<WireLabelId, LinearDistance> = IdMap::default();
        for at in self.labels {
            labels.insert_value(LinearDistance::from(at));
        }

        let mut route = AutoRoute::new(from, to, waypoints, labels);
        route.set_route_name(self.name);
        route.set_role(self.role);
        Ok(route)
    }
}

impl schema::Text {
    pub fn into_text(self) -> TextBox {
        TextBox {
            text: self.text,
            anchor: GridPos::new(self.x, self.y),
            role: self.role,
        }
    }
}

impl schema::Comment {
    pub fn into_comment(self) -> Comment {
        Comment {
            inner: GridRect::new(GridPos::new(self.x, self.y), GridSize::new(self.w, self.h)),
            title: label_or(self.title, BlockLabel::default()),
            role: self.role,
        }
    }
}

impl schema::Image {
    pub fn into_symbol(self, block: &str, assets: &Assets) -> Result<Image, SchemaError> {
        Ok(Image {
            image: assets.get(&self.asset, block)?,
            inner: egui::Rect::from_min_size(
                egui::pos2(self.x, self.y),
                egui::vec2(self.w, self.h),
            ),
        })
    }
}

// ── JSON / KDL wrappers ──────────────────────────────────────────────────────

/// Serialize the document as pretty JSON.
pub fn to_json(doc: &Document) -> String {
    schema::Document::from(doc).to_json()
}

/// Serialize the document as KDL.
pub fn to_kdl(doc: &Document) -> String {
    schema::Document::from(doc).to_kdl()
}

/// Parse a KDL document. Routes come back with empty geometry; the caller must
/// rebuild it before display (see `crate::presentation::Presentation::refresh_routes`).
pub fn from_kdl(src: &str, src_name: &str) -> miette::Result<Document> {
    Ok(schema::Document::parse_kdl(src, src_name)?.into_document()?)
}

/// Parse a document and rebuild its wire geometry, choosing the format by
/// `src_name`'s extension (`.kdl` for KDL, otherwise JSON).
///
/// This — not [`from_kdl`] — is what a caller loading a document to
/// display wants: those two stop at the parse, leaving every route with empty
/// geometry.
pub fn load(src: &str, src_name: &str) -> miette::Result<Document> {
    let is_kdl = std::path::Path::new(src_name)
        .extension()
        .is_some_and(|e| e.eq_ignore_ascii_case("kdl"));
    if is_kdl {
        finish_load(schema::Document::parse_kdl(src, src_name)?)
    } else {
        finish_load(schema::Document::parse_json(src, src_name)?)
    }
}

/// Reconstruct a document from a parsed model. Geometry is left empty —
/// the caller that owns the document's [`Presentation`](crate::presentation::Presentation)
/// runs [`refresh_routes`](crate::presentation::Presentation::refresh_routes), so wire
/// geometry lands beside the document rather than being built into a store
/// this layer cannot see. (Split out of [`load`] for the container, which
/// injects its file-kept assets before the model can be reconstructed.)
pub fn finish_load(model: schema::Document) -> miette::Result<Document> {
    Ok(model.into_document()?)
}

/// Serialize a document in the format `dst_name`'s extension names, so a `.kdl`
/// round-trips through KDL and a `.json` through JSON. The counterpart of
/// [`load`].
pub fn save(doc: &Document, dst_name: &str) -> String {
    let is_kdl = std::path::Path::new(dst_name)
        .extension()
        .is_some_and(|e| e.eq_ignore_ascii_case("kdl"));
    if is_kdl { to_kdl(doc) } else { to_json(doc) }
}

#[cfg(test)]
mod tests {
    use super::{from_kdl, to_json, to_kdl};

    /// Parse JSON *without* rebuilding wire geometry. The round-trip tests below
    /// compare documents by value, so they need the parse alone —
    /// `super::load` finalizes, which is a different document.
    fn from_json(src: &str, src_name: &str) -> miette::Result<Document> {
        Ok(super::schema::Document::parse_json(src, src_name)?.into_document()?)
    }
    use crate::document::{
        AutoRoute, Block, BlockLabel, Comment, Decorations, Document, GridPos, GridRect, GridSize,
        Image, ImageData, LabelSide, LineAnchor, LinearDistance, PinPort, PinSide, PinType,
        TextBox, Waypoint,
    };
    use crate::presentation::store::{IdMap, IdMapExt, IdSet};
    use crate::schema::SchemaError;
    use crate::schema::model;
    use crate::store::{
        CommentId, ImageId, PinId, RectId, RouteId, TextId, WaypointId, WireLabelId,
    };

    fn pin(name: &str, side: PinSide, offset: u32, kind: PinType, rect: GridRect) -> PinPort {
        PinPort {
            name: name.to_string(),
            type_label: String::new(),
            tag: String::new(),
            tag_hidden: false,
            side,
            offset,
            rect,
            kind,
            port_accent: None,
            port_orientation: None,
        }
    }

    fn rect(x: i32, y: i32, w: u32, h: u32) -> GridRect {
        GridRect::new(GridPos::new(x, y), GridSize::new(w, h))
    }

    fn block(name: &str) -> Block {
        Block {
            decorations: Decorations {
                title: BlockLabel {
                    name: name.to_string(),
                    ..BlockLabel::default()
                },
                ..Decorations::default()
            },
            ..Block::default()
        }
    }

    fn route(
        from: LineAnchor,
        to: LineAnchor,
        name: &str,
        wps: &[(i32, i32)],
        labels: &[f32],
    ) -> AutoRoute {
        let mut waypoints: IdMap<WaypointId, Waypoint> = IdMap::default();
        for &(x, y) in wps {
            waypoints.insert_value(Waypoint {
                pos: GridPos::new(x, y),
                locked: false,
            });
        }
        let mut ld: IdMap<WireLabelId, LinearDistance> = IdMap::default();
        for &l in labels {
            ld.insert_value(LinearDistance::from(l));
        }
        let mut r = AutoRoute::new(from, to, waypoints, ld);
        r.set_route_name(name.to_string());
        r
    }

    /// A representative document exercising every field the schema carries: pin
    /// rects, type labels, accents, facing, routes with waypoints + labels, text,
    /// comment, SVG image, role, locked, nested children.
    fn demo() -> Document {
        let top = RectId::nth_default(1);
        let c1 = RectId::nth_default(2);
        let c2 = RectId::nth_default(3);
        let buffer = RectId::nth_default(4);

        let mut t = block("block_1");
        t.decorations.type_label.name = "Counter".to_string();
        t.pins.insert(
            PinId::nth_default(1),
            pin("clk", PinSide::West, 1, PinType::Input, rect(-11, 28, 4, 2)),
        );
        t.pins.insert(
            PinId::nth_default(2),
            pin("rst", PinSide::West, 2, PinType::InOut, rect(-11, 32, 4, 2)),
        );
        t.children = IdSet::from_iter([c1, c2]);
        t.role = Some(3);
        t.locked = true;
        t.texts.insert(
            TextId::nth_default(1),
            TextBox {
                text: "line one\nline two".to_string(),
                anchor: GridPos::new(5, 8),
                role: Some(2),
            },
        );
        t.comments.insert(
            CommentId::nth_default(1),
            Comment {
                inner: rect(2, 2, 10, 8),
                title: BlockLabel {
                    name: "Region".to_string(),
                    side: LabelSide::Top,
                    ..BlockLabel::default()
                },
                role: None,
            },
        );
        t.images.insert(
            ImageId::nth_default(1),
            Image {
                image: ImageData::Svg(
                    "<svg viewBox=\"0 0 10 10\">\n  <path d=\"M0 0 L10 10\"/>\n</svg>".to_string(),
                )
                .into(),
                inner: egui::Rect::from_min_size(egui::pos2(20.0, 15.0), egui::vec2(8.0, 8.0)),
            },
        );
        t.icon = Some(Image {
            image: ImageData::Svg(
                "<svg viewBox=\"0 0 4 4\"><rect width=\"4\" height=\"4\"/></svg>".to_string(),
            )
            .into(),
            inner: egui::Rect::from_min_size(egui::pos2(4.0, 4.0), egui::vec2(3.0, 3.0)),
        });
        let mut r1 = route(
            LineAnchor::Pin {
                block: c1,
                pin: PinId::nth_default(1),
            },
            LineAnchor::Pin {
                block: c2,
                pin: PinId::nth_default(1),
            },
            "route_1",
            &[(12, 21), (-16, 19)],
            &[76.6],
        );
        r1.set_role(Some(5));
        t.routes.insert(RouteId::nth_default(1), r1);
        t.routes.insert(
            RouteId::nth_default(2),
            route(
                LineAnchor::Pin {
                    block: c2,
                    pin: PinId::nth_default(1),
                },
                LineAnchor::Port(PinId::nth_default(1)),
                "",
                &[],
                &[],
            ),
        );

        let mut b1 = block("block_1");
        b1.pins.insert(
            PinId::nth_default(1),
            pin(
                "i.1.write_logic",
                PinSide::West,
                1,
                PinType::InOut,
                rect(0, 0, 8, 2),
            ),
        );
        // A pin exercising every optional field.
        let mut fancy = pin(
            "typed",
            PinSide::East,
            3,
            PinType::Output,
            rect(20, 6, 5, 2),
        );
        fancy.type_label = "Counter".to_string();
        fancy.tag = "U3".to_string();
        fancy.tag_hidden = true;
        fancy.port_accent = Some(2);
        // side == East, so Some(East) is the flipped state (fliplr=true) that the
        // boolean encoding round-trips (Some(side.flip()) would collapse to None).
        fancy.port_orientation = Some(PinSide::East);
        b1.pins.insert(PinId::nth_default(2), fancy);

        let mut b2 = block("block_2b");
        b2.pins.insert(
            PinId::nth_default(1),
            pin(
                "o.0.read_logic",
                PinSide::East,
                1,
                PinType::InOut,
                rect(30, 0, 8, 2),
            ),
        );
        b2.children = IdSet::from_iter([buffer]);

        let mut buf = block("Internal Buffer");
        buf.pins.insert(
            PinId::nth_default(1),
            pin("Port", PinSide::West, 1, PinType::InOut, rect(22, 5, 4, 2)),
        );

        let mut blocks: IdMap<RectId, Block> = IdMap::default();
        blocks.insert(top, t);
        blocks.insert(c1, b1);
        blocks.insert(c2, b2);
        blocks.insert(buffer, buf);
        Document {
            name: None,
            top_id: top,
            blocks: blocks.into(),
        }
    }

    #[test]
    fn json_round_trip_is_idempotent() {
        let doc = demo();
        let s1 = to_json(&doc);
        let back = from_json(&s1, "demo.json").unwrap_or_else(|e| panic!("re-parse:\n{e:?}\n{s1}"));
        let s2 = to_json(&back);
        assert_eq!(s1, s2, "JSON must be idempotent\n{s1}");
    }

    #[test]
    fn kdl_round_trip_is_idempotent() {
        let doc = demo();
        let s1 = to_kdl(&doc);
        let back = from_kdl(&s1, "demo.kdl").unwrap_or_else(|e| panic!("re-parse:\n{e:?}\n{s1}"));
        let s2 = to_kdl(&back);
        assert_eq!(s1, s2, "KDL must be idempotent\n{s1}");
    }

    #[test]
    fn json_and_kdl_agree() {
        // Both formats are serializations of the same schema, so a doc routed through
        // KDL and back must produce the same JSON as the original.
        let doc = demo();
        let via_kdl = from_kdl(&to_kdl(&doc), "demo.kdl").unwrap();
        assert_eq!(to_json(&doc), to_json(&via_kdl));
    }

    #[test]
    fn schema_projection_round_trips_by_value() {
        // The schema itself (not the string) round-trips exactly through both formats.
        let doc = demo();
        let s = model::Document::from(&doc);
        let via_json = from_json(&to_json(&doc), "d.json").unwrap();
        let via_kdl = from_kdl(&to_kdl(&doc), "d.kdl").unwrap();
        assert_eq!(s, model::Document::from(&via_json), "json");
        assert_eq!(s, model::Document::from(&via_kdl), "kdl");
    }

    #[test]
    fn image_fractional_size_round_trips() {
        // Images are free-sized (not grid-quantized), so a fractional rect must
        // survive both formats verbatim.
        let mut doc = Document::default();
        let top = doc.top_id;
        let inner = egui::Rect::from_min_size(egui::pos2(3.5, 2.5), egui::vec2(37.5, 12.5));
        doc.block_mut(top).unwrap().images.insert(
            ImageId::nth_default(1),
            Image {
                image: ImageData::Svg("<svg/>".into()).into(),
                inner,
            },
        );
        for back in [
            from_json(&to_json(&doc), "d.json").unwrap(),
            from_kdl(&to_kdl(&doc), "d.kdl").unwrap(),
        ] {
            let img = back.block(top).unwrap().images.values().next().unwrap();
            assert_eq!(img.inner, inner, "fractional image rect preserved");
        }
    }

    /// A document placing one image twice as a background and once as a block's
    /// icon — the shape that used to write the same bytes three times.
    fn thrice_placed(marker: &str) -> (Document, RectId) {
        let content = ImageData::Svg(format!("<svg viewBox=\"0 0 2 2\"><!--{marker}--></svg>"));
        let mut doc = Document::default();
        let top = doc.top_id;
        let child = doc.add_child(top, block("child"));
        for (n, at) in [(1, 0.0), (2, 10.0)] {
            doc.block_mut(top).unwrap().images.insert(
                ImageId::nth_default(n),
                Image::new(
                    content.clone(),
                    egui::Rect::from_min_size(egui::pos2(at, at), egui::vec2(4.0, 4.0)),
                ),
            );
        }
        doc.block_mut(child).unwrap().icon = Some(Image::new(
            content.clone(),
            egui::Rect::from_min_size(egui::pos2(1.0, 1.0), egui::vec2(2.0, 2.0)),
        ));
        (doc, child)
    }

    #[test]
    fn a_repeated_image_is_written_once_and_shared_on_from_json() {
        let (doc, child) = thrice_placed("written-once");
        let kdl = to_kdl(&doc);
        assert_eq!(kdl.matches("<svg viewBox").count(), 1, "one copy:\n{kdl}");
        assert_eq!(kdl.matches("asset \"").count(), 1, "one asset:\n{kdl}");

        let original = doc.block(child).unwrap().icon.clone().unwrap().image;
        let id = super::asset_id(&original);
        assert_eq!(
            kdl.matches(&format!("\"{id}\"")).count(),
            4,
            "one definition, three placements:\n{kdl}"
        );
        for (name, back) in [
            ("kdl", from_kdl(&kdl, "d.kdl").unwrap()),
            ("json", from_json(&to_json(&doc), "d.json").unwrap()),
        ] {
            let top = back.block(back.top_id).unwrap();
            let mut placed: Vec<_> = top.images.values().map(|s| s.image.clone()).collect();
            placed.push(back.block(child).unwrap().icon.clone().unwrap().image);
            assert_eq!(placed.len(), 3, "{name}");
            // Equality here *is* pointer identity, so this says the three
            // placements share one allocation — and share it with the document
            // that was already in memory, since interning is global.
            assert!(
                placed.iter().all(|a| *a == original),
                "{name}: every placement resolves to the one interned copy"
            );
        }
    }

    #[test]
    fn an_unknown_asset_reference_is_rejected() {
        let (doc, child) = thrice_placed("unknown-ref");
        let real = super::asset_id(&doc.block(child).unwrap().icon.clone().unwrap().image);
        // A well-formed id that nothing defines — the reference is what is being
        // rejected here, not the spelling.
        let kdl = to_kdl(&doc).replace(
            &format!("image \"{real}\""),
            "image \"0000000000000000.svg\"",
        );
        let err = from_kdl(&kdl, "d.kdl")
            .unwrap_err()
            .downcast::<SchemaError>()
            .unwrap();
        assert!(
            matches!(err, SchemaError::UnknownAsset { .. }),
            "a placement naming an undefined asset must not load: {err}"
        );
    }

    #[test]
    fn ids_preserved_and_child_order_kept() {
        let back = from_kdl(&to_kdl(&demo()), "d.kdl").unwrap();
        assert_eq!(back.top_id, RectId::nth_default(1));
        assert!(back.block(RectId::nth_default(4)).is_some());
        let top = back.block(back.top_id).unwrap();
        assert_eq!(
            top.children.iter().copied().collect::<Vec<_>>(),
            vec![RectId::nth_default(2), RectId::nth_default(3)]
        );
    }

    #[test]
    fn pin_rect_is_captured_not_recomputed() {
        // The dragged/authored port rect survives a round-trip verbatim.
        let back = from_json(&to_json(&demo()), "d.json").unwrap();
        let clk = back
            .block(RectId::nth_default(1))
            .unwrap()
            .pins
            .get(&PinId::nth_default(1))
            .unwrap();
        assert_eq!(clk.rect, rect(-11, 28, 4, 2));
    }

    #[test]
    fn fliplr_round_trips() {
        let kdl = to_kdl(&demo());
        assert!(kdl.contains("fliplr=true"), "{kdl}");
        assert!(
            !kdl.contains("facing") && !kdl.contains("port-orientation"),
            "{kdl}"
        );
        let back = from_kdl(&kdl, "d.kdl").unwrap();
        let fancy = back
            .block(RectId::nth_default(2))
            .unwrap()
            .pins
            .get(&PinId::nth_default(2))
            .unwrap();
        // fliplr=true reloads as port_orientation == side (East here).
        assert_eq!(fancy.port_orientation, Some(PinSide::East));
        // A natural-facing pin has no fliplr and reloads as None.
        let clk = back
            .block(RectId::nth_default(1))
            .unwrap()
            .pins
            .get(&PinId::nth_default(1))
            .unwrap();
        assert_eq!(clk.port_orientation, None);
    }

    #[test]
    fn route_anchors_are_positional_and_id_less() {
        let kdl = to_kdl(&demo());
        // Anchors are the two positional args; no `from=`/`to=` props and no id.
        assert!(
            kdl.contains(r#"route "b2:p1" "b3:p1" name="route_1""#),
            "{kdl}"
        );
        assert!(!kdl.contains("from=") && !kdl.contains("to="), "{kdl}");
    }

    #[test]
    fn label_position_round_trips_exactly() {
        // The ×10 integer encoding makes the label position exact through a round-trip.
        let doc = demo();
        let orig = doc
            .block(RectId::nth_default(1))
            .unwrap()
            .routes
            .get(&RouteId::nth_default(1))
            .unwrap()
            .iter_labels()
            .next()
            .map(|(_, &d)| d)
            .unwrap();
        let back = from_kdl(&to_kdl(&doc), "d.kdl").unwrap();
        let got = back
            .block(RectId::nth_default(1))
            .unwrap()
            .routes
            .values()
            .find(|r| r.route_name() == "route_1")
            .unwrap()
            .iter_labels()
            .next()
            .map(|(_, &d)| d)
            .unwrap();
        assert_eq!(orig, got, "label LinearDistance preserved exactly");
    }

    #[test]
    fn enums_are_kebab_case_in_json() {
        let json = to_json(&demo());
        assert!(json.contains(r#""dir": "output""#), "{json}");
        assert!(
            !json.contains("\"East\"") && !json.contains("\"InOut\""),
            "{json}"
        );
    }

    #[test]
    fn loc_combines_side_and_offset() {
        let kdl = to_kdl(&demo());
        let json = to_json(&demo());
        // "clk" is West, offset 1 → loc "w1"; no separate side/offset fields.
        assert!(kdl.contains(r#"loc="w1""#), "{kdl}");
        assert!(json.contains(r#""loc": "w1""#), "{json}");
        // Pins no longer carry separate side/offset props (labels still use `side=`).
        assert!(!kdl.contains(r#""clk" side="#), "{kdl}");
        let back = from_kdl(&kdl, "d.kdl").unwrap();
        let clk = back
            .block(RectId::nth_default(1))
            .unwrap()
            .pins
            .get(&PinId::nth_default(1))
            .unwrap();
        assert_eq!((clk.side, clk.offset), (PinSide::West, 1));
    }

    #[test]
    fn pin_geometry_omitted_when_auto() {
        let p = pin("clk", PinSide::West, 1, PinType::InOut, rect(5, 5, 4, 2));
        // rect == auto-placed default → geometry omitted.
        let auto = model::Pin::from_pin(PinId::nth_default(1), &p, Some(rect(5, 5, 4, 2)));
        assert_eq!((auto.x, auto.y, auto.w), (None, None, None));
        // rect != default (dragged) → geometry kept.
        let kept = model::Pin::from_pin(PinId::nth_default(1), &p, Some(rect(9, 9, 4, 2)));
        assert_eq!((kept.x, kept.y, kept.w), (Some(5), Some(5), Some(4)));
    }

    #[test]
    fn hand_authored_pin_without_geometry_gets_auto_placed() {
        // A pin declared with only `loc` (no x/y/w) parses and is auto-placed on load.
        let src =
            "top \"b1\"\nblock \"b1\" x=0 y=0 w=20 h=8 {\n    pin \"p1\" \"clk\" loc=\"w1\"\n}";
        let back = from_kdl(src, "d.kdl").unwrap();
        let p = back
            .block(RectId::nth_default(1))
            .unwrap()
            .pins
            .get(&PinId::nth_default(1))
            .unwrap();
        // Height is PORT_HEIGHT and width/position were filled in (non-zero width).
        assert!(p.rect.size.w > 0, "port width was auto-filled");
        assert_eq!(p.rect.size.h, crate::shape::port::PORT_HEIGHT);
    }

    #[test]
    fn children_are_one_node() {
        let kdl = to_kdl(&demo());
        // The top block's children on a single node, in order.
        assert!(kdl.contains(r#"children "b2" "b3""#), "{kdl}");
        assert!(
            !kdl.contains("child \"b2\""),
            "no per-line child nodes:\n{kdl}"
        );
        let back = from_kdl(&kdl, "d.kdl").unwrap();
        assert_eq!(
            back.block(RectId::nth_default(1))
                .unwrap()
                .children
                .iter()
                .copied()
                .collect::<Vec<_>>(),
            vec![RectId::nth_default(2), RectId::nth_default(3)]
        );
    }

    #[test]
    fn bad_and_missing_loc_errors() {
        // In KDL both surface with a span (via the walker).
        let missing = "top \"b1\"\nblock \"b1\" x=0 y=0 w=40 h=30 {\n    pin \"p1\" \"clk\" x=0 y=0 w=4 h=2\n}";
        assert!(matches!(kdl_err(missing), SchemaError::Kdl { .. }));
        let bad = "top \"b1\"\nblock \"b1\" x=0 y=0 w=40 h=30 {\n    pin \"p1\" \"clk\" loc=\"z9\" x=0 y=0 w=4 h=2\n}";
        let err = kdl_err(bad);
        assert!(matches!(err, SchemaError::Kdl { .. }));
        let (off, len) = kdl_span(&err);
        assert_eq!(&bad[off..off + len], "\"z9\"", "span points at the bad loc");
    }

    #[test]
    fn missing_loc_in_json_is_missing_pin_side() {
        // The JSON path (no walker) surfaces the friendly conversion error.
        let json = r#"{"top":"b1","blocks":[{"id":"b1","x":0,"y":0,"w":40,"h":30,
            "pins":[{"id":"p1","name":"clk","x":0,"y":0,"w":4,"h":2}]}]}"#;
        let err = from_json(json, "e.json")
            .unwrap_err()
            .downcast::<SchemaError>()
            .unwrap();
        assert!(matches!(err, SchemaError::MissingPinSide { .. }));
    }

    #[test]
    fn defaults_omitted() {
        let kdl = to_kdl(&demo());
        assert!(!kdl.contains("in-out"), "default kind omitted:\n{kdl}");
    }

    // ── Error cases ─────────────────────────────────────────────────────────────

    fn json_err(src: &str) -> SchemaError {
        from_json(src, "e.json")
            .unwrap_err()
            .downcast::<SchemaError>()
            .expect("SchemaError")
    }
    fn kdl_err(src: &str) -> SchemaError {
        from_kdl(src, "e.kdl")
            .unwrap_err()
            .downcast::<SchemaError>()
            .expect("SchemaError")
    }

    /// The span of a `Kdl` error, for asserting it points at the right token.
    fn kdl_span(err: &SchemaError) -> (usize, usize) {
        match err {
            SchemaError::Kdl { span, .. } => (span.offset(), span.len()),
            other => panic!("expected a Kdl error, got {other:?}"),
        }
    }

    #[test]
    fn malformed_is_an_error() {
        assert!(matches!(kdl_err("top \"b1\" {"), SchemaError::Kdl { .. }));
        assert!(matches!(json_err("not json"), SchemaError::Json { .. }));
    }

    #[test]
    fn bad_id_error_points_at_the_id() {
        let src = "top \"b1\"\nblock \"xyz\" x=0 y=0 w=4 h=4";
        let err = kdl_err(src);
        assert!(matches!(err, SchemaError::Kdl { .. }));
        // The span covers the `"xyz"` token.
        let (off, len) = kdl_span(&err);
        assert_eq!(&src[off..off + len], "\"xyz\"");
    }

    #[test]
    fn bad_anchor_error() {
        // Anchors are positional; `"zzz"` is neither `p<N>` nor `b<N>:p<M>`.
        let src = "top \"b1\"\nblock \"b1\" x=0 y=0 w=40 h=30 {\n    route \"zzz\" \"p1\"\n}";
        assert!(matches!(kdl_err(src), SchemaError::Kdl { .. }));
    }

    #[test]
    fn dangling_child_error() {
        let src = "top \"b1\"\nblock \"b1\" x=0 y=0 w=40 h=30 {\n    children \"b9\"\n}";
        assert!(matches!(kdl_err(src), SchemaError::DanglingChild { .. }));
    }

    /// A `top` naming no block used to load "fine" and then take the editor down
    /// on the first frame: every draw resolves the current block through `top_id`.
    #[test]
    fn top_naming_a_missing_block_is_an_error() {
        let src = "top \"b9\"\nblock \"b1\" x=0 y=0 w=40 h=30";
        assert!(matches!(kdl_err(src), SchemaError::BadTop { .. }));
    }

    #[test]
    fn image_without_data_error() {
        let src = "top \"b1\"\nblock \"b1\" x=0 y=0 w=40 h=30 {\n    image x=1 y=1 size=10.0\n}";
        assert!(matches!(kdl_err(src), SchemaError::Kdl { .. }));
    }

    #[test]
    fn unknown_node_error() {
        let src = "top \"b1\"\nblock \"b1\" x=0 y=0 w=40 h=30 {\n    widget x=1\n}";
        assert!(matches!(kdl_err(src), SchemaError::Kdl { .. }));
    }

    #[test]
    fn svg_with_quotes_round_trips() {
        let kdl = to_kdl(&demo());
        assert!(kdl.contains("svg r#\""), "{kdl}");
        let back = from_kdl(&kdl, "d.kdl").unwrap();
        let sym = back
            .block(RectId::nth_default(1))
            .unwrap()
            .images
            .get(&ImageId::nth_default(1))
            .unwrap();
        match &*sym.image {
            ImageData::Svg(s) => assert!(s.contains("M0 0 L10 10") && s.contains('\n')),
            ImageData::Png(_) => panic!("expected svg"),
        }
    }

    fn png(marker: &str) -> ImageData {
        ImageData::Png(format!("fake-png-{marker}").into_bytes())
    }

    /// A document holding `images` as background images on its top block.
    fn doc_with_images(images: Vec<ImageData>) -> Document {
        let mut doc = Document::default();
        let top = doc.top_id;
        let block = doc.blocks.get_mut(&top).expect("the top block");
        for image in images {
            block
                .images
                .insert_value(Image::new(image, egui::Rect::ZERO));
        }
        doc
    }

    fn asset_ids(doc: &Document) -> Vec<String> {
        model::Document::from(doc)
            .assets
            .into_iter()
            .map(|a| a.id)
            .collect()
    }

    #[test]
    fn an_asset_id_is_its_content_hash_and_extension() {
        let ids = asset_ids(&doc_with_images(vec![
            png("one"),
            ImageData::Svg("<svg/>".to_string()),
        ]));
        assert_eq!(ids.len(), 2);
        let split = |id: &str| {
            let (stem, ext) = id.rsplit_once('.').expect("an extension");
            (stem.to_string(), ext.to_string())
        };
        for (id, expected_ext) in ids.iter().zip(["png", "svg"]) {
            let (stem, ext) = split(id);
            assert_eq!(ext, expected_ext, "{id}");
            assert_eq!(stem.len(), 16, "{id}");
            assert!(stem.chars().all(|c| c.is_ascii_hexdigit()), "{id}");
        }
        // Equal content, equal id — in this document and in any other.
        assert_eq!(
            asset_ids(&doc_with_images(vec![png("one")]))[0],
            ids[0],
            "the same image got different ids in different documents"
        );
    }

    /// The property the content-derived ids exist for: with positional ids,
    /// dropping the first image renumbered every later reference, so an
    /// unrelated edit rewrote the whole file. Now nothing moves.
    #[test]
    fn removing_one_asset_does_not_rename_the_others() {
        let before = doc_with_images(vec![png("first"), png("second"), png("third")]);
        let ids_before = asset_ids(&before);
        assert_eq!(ids_before.len(), 3, "three distinct images");

        let mut after = before.clone();
        let top = after.top_id;
        let first = *after.blocks[&top].images.keys().next().expect("an image");
        after
            .blocks
            .get_mut(&top)
            .expect("the top block")
            .images
            .shift_remove(&first);

        assert_eq!(
            asset_ids(&after),
            ids_before[1..],
            "dropping the first image renamed the survivors"
        );
    }

    /// A version-1 document's `i<N>` ids load, and are rewritten as content
    /// hashes on the next save — reader permissive, writer canonical.
    #[test]
    fn legacy_ids_are_recanonicalized_on_save() {
        let legacy = "top \"b1\"\n\
                      block \"b1\" x=0 y=0 w=40 h=30 {\n\
                      \x20   image \"i1\" x=0 y=0 w=4 h=4\n\
                      }\n\
                      asset \"i1\" {\n    svg r#\"<svg/>\"#\n}";
        let doc = from_kdl(legacy, "legacy.kdl").expect("a version-1 document loads");

        let saved = to_kdl(&doc);
        assert!(
            !saved.contains("\"i1\""),
            "the legacy id survived:\n{saved}"
        );
        assert!(
            saved.contains(&format!("version {}", model::CURRENT_VERSION)),
            "{saved}"
        );
        let id = &asset_ids(&doc)[0];
        assert!(saved.contains(&format!("asset \"{id}\"")), "{saved}");
        assert!(saved.contains(&format!("image \"{id}\"")), "{saved}");
    }
}