blockworx/document_ng/

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_ng` 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_ng` 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 crate::document_ng::{
    Accents, AutoRoute, Block, BlockLabel, Comment, Decorations, Document, GridPos, GridRect,
    GridSize, Image, ImageData, LabelSide, LineAnchor, LinearDistance, PinPort, PinSide, PinType,
    TextBox, Waypoint,
};
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, IdMap, IdMapExt, IdSet, ImageId, PinId, RectId, RouteId, TextId, WaypointId,
    WireLabelId,
};
use crate::widget::auto_route::AutoRouteExt;

// ── 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 {
        schema::Document {
            top: doc.top_id.to_string(),
            blocks: doc
                .blocks
                .iter()
                .map(|(&id, b)| schema::Block::from_block(id, b))
                .collect(),
        }
    }
}

/// Format a route anchor as `"p2"` (port) or `"b3:p2"` (child-block pin).
fn format_anchor(anchor: LineAnchor) -> String {
    match anchor {
        LineAnchor::Port(p) => p.to_string(),
        LineAnchor::Pin { block, pin } => format!("{block}:{pin}"),
    }
}

/// 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) -> 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(schema::Image::from_symbol).collect(),
            icon: b.icon.as_ref().map(schema::Image::from_symbol),
            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()),
            pin_accent: p.accents.pin_accent,
            port_accent: p.accents.port_accent,
            port_pin_accent: p.accents.port_pin_accent,
            // 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: format_anchor(r.start()),
            to: format_anchor(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) -> Self {
        let image = match &s.image {
            ImageData::Svg(src) => schema::ImageData::Svg(src.clone()),
            ImageData::Png(bytes) => {
                schema::ImageData::Png(base64::engine::general_purpose::STANDARD.encode(bytes))
            }
        };
        schema::Image {
            x: round1(s.inner.min.x),
            y: round1(s.inner.min.y),
            w: round1(s.inner.width()),
            h: round1(s.inner.height()),
            image,
        }
    }
}

// ── 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 mut blocks: IdMap<RectId, Block> = IdMap::default();
        for sb in self.blocks {
            let (id, block) = sb.into_block()?;
            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 {
            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) -> 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 (index, s) in self.images.into_iter().enumerate() {
            images.insert_value(s.into_symbol(&block_ctx, index)?);
        }
        let icon = match self.icon {
            Some(s) => Some(s.into_symbol(&block_ctx, 0)?),
            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(),
            accents: Accents {
                pin_accent: self.pin_accent,
                port_accent: self.port_accent,
                port_pin_accent: self.port_pin_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));
        }

        // Empty geometry; the router rebuilds it after load.
        let mut route = AutoRoute::build(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),
            size: None,
            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, index: usize) -> Result<Image, SchemaError> {
        let image = match self.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::SymbolPng {
                        block: block.to_string(),
                        index,
                        reason: e.to_string(),
                    })?,
            ),
        };
        Ok(Image {
            image,
            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()
}

/// Parse a JSON document. Routes come back with empty geometry; the caller must
/// rebuild it before display (see `crate::widget::drawing::finalize_load`).
pub fn from_json(src: &str, src_name: &str) -> miette::Result<Document> {
    Ok(schema::Document::parse_json(src, src_name)?.into_document()?)
}

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

/// Parse a KDL document. Like [`from_json`], routes need rebuilding before display.
pub fn from_kdl(src: &str, src_name: &str) -> miette::Result<Document> {
    Ok(schema::Document::parse_kdl(src, src_name)?.into_document()?)
}

#[cfg(test)]
mod tests {
    use super::{from_json, from_kdl, to_json, to_kdl};
    use crate::document_ng::{
        Accents, AutoRoute, Block, BlockLabel, Comment, Decorations, Document, GridPos, GridRect,
        GridSize, Image, ImageData, LabelSide, LineAnchor, LinearDistance, PinPort, PinSide,
        PinType, TextBox, Waypoint,
    };
    use crate::schema::SchemaError;
    use crate::schema::model;
    use crate::store::{
        CommentId, IdMap, IdMapExt, IdSet, ImageId, PinId, RectId, RouteId, TextId, WaypointId,
        WireLabelId,
    };
    use crate::widget::auto_route::AutoRouteExt;

    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,
            accents: Accents::default(),
            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::build(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),
                size: None,
                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(),
                ),
                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(),
            ),
            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.accents = Accents {
            pin_accent: Some(1),
            port_accent: Some(2),
            port_pin_accent: None,
        };
        // 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 {
            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()),
                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");
        }
    }

    #[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"),
        }
    }
}