blockworx/

embed.rs

//! Embedding (and recovering) a diagram inside an exported PNG or SVG.
//!
//! An SVG/PNG export is a picture, but we also stash the source diagram as JSON
//! inside it so the file round-trips: re-importing the picture rebuilds the
//! editable diagram instead of dropping a flat image. The JSON is base64-encoded
//! (ASCII, so it survives both containers untouched) and carried in a place every
//! renderer ignores:
//!
//! - **SVG**: a `<metadata id="blockworx-diagram">…</metadata>` child of the root.
//! - **PNG**: a `tEXt` chunk keyed `blockworx-diagram`, spliced in after `IHDR`.
//!
//! Extraction is the inverse: find the marker, base64-decode, and hand back the
//! JSON. A picture without our marker yields `None`, and the importer treats it as
//! a plain image.
//!
//! Only the READING half ships. The export that wrote these payloads died with
//! the legacy serializer at the flag day (12·5) — a picture the editor exports
//! now carries no diagram — while the importer still recovers one from a
//! picture written before it, which is F5's courtesy read. The writing half
//! survives in this module's `fixtures` (test-only) as the inverse the reader
//! is tested against; phase 7 decides what, if anything, an export embeds
//! again.

use base64::Engine;

/// Marker naming our payload in both containers (the SVG element id and the PNG
/// text keyword).
const MARKER: &str = "blockworx-diagram";

const PNG_SIGNATURE: [u8; 8] = [0x89, b'P', b'N', b'G', b'\r', b'\n', 0x1a, b'\n'];

fn b64_decode(s: &str) -> Option<String> {
    let bytes = base64::engine::general_purpose::STANDARD
        .decode(s.trim())
        .ok()?;
    String::from_utf8(bytes).ok()
}

// ── SVG ─────────────────────────────────────────────────────────────────────

/// Recover the diagram JSON from an SVG's `blockworx-diagram` metadata element, or
/// `None` if the SVG carries no such element (a plain image).
pub fn extract_from_svg(svg: &str) -> Option<String> {
    let opener = format!("id=\"{MARKER}\">");
    let start = svg.find(&opener)? + opener.len();
    let end = svg[start..].find("</metadata>")? + start;
    b64_decode(&svg[start..end])
}

// ── PNG ─────────────────────────────────────────────────────────────────────

/// Recover the diagram JSON from a PNG's `blockworx-diagram` `tEXt` chunk, or
/// `None` if there is none (a plain image).
pub fn extract_from_png(png: &[u8]) -> Option<String> {
    if png.len() < 8 || png[..8] != PNG_SIGNATURE {
        return None;
    }
    let mut pos = 8;
    while pos + 8 <= png.len() {
        let len = u32::from_be_bytes(png[pos..pos + 4].try_into().ok()?) as usize;
        let kind = &png[pos + 4..pos + 8];
        let data_start = pos + 8;
        let data_end = data_start.checked_add(len)?;
        if data_end + 4 > png.len() {
            break;
        }
        if kind == b"tEXt" {
            let data = &png[data_start..data_end];
            if let Some(sep) = data.iter().position(|&b| b == 0)
                && &data[..sep] == MARKER.as_bytes()
            {
                return b64_decode(std::str::from_utf8(&data[sep + 1..]).ok()?);
            }
        }
        pos = data_end + 4; // skip the 4-byte CRC
    }
    None
}

/// How a picture carrying a diagram is built: the inverse of the readers
/// above, kept so the tests that recover a payload can write a real one, and
/// so `import`'s can too. Nothing ships this — an export writes a picture and
/// nothing else since 12·5.
#[cfg(test)]
pub(crate) mod fixtures {
    use super::{MARKER, PNG_SIGNATURE};
    use base64::Engine;

    fn b64_encode(s: &str) -> String {
        base64::engine::general_purpose::STANDARD.encode(s.as_bytes())
    }

    /// Insert `<metadata id="blockworx-diagram">base64(diagram)</metadata>` as
    /// the first child of the root `<svg>` element. Renderers ignore
    /// `<metadata>`, so the picture is unchanged.
    pub(crate) fn embed_in_svg(svg: &str, diagram_json: &str) -> String {
        let Some(insert_at) = svg_open_tag_end(svg) else {
            return svg.to_string();
        };
        let metadata = format!(
            "<metadata id=\"{MARKER}\">{}</metadata>",
            b64_encode(diagram_json)
        );
        let (head, tail) = svg.split_at(insert_at);
        format!("{head}{metadata}{tail}")
    }

    /// The byte offset just past the root `<svg …>` opening tag (where a first
    /// child is inserted). `None` if there is no `<svg` tag.
    fn svg_open_tag_end(svg: &str) -> Option<usize> {
        let tag = svg.find("<svg")?;
        let close = svg[tag..].find('>')? + tag;
        Some(close + 1)
    }

    /// Splice a `tEXt` chunk carrying base64(diagram) into `png` right after
    /// its `IHDR` chunk.
    pub(crate) fn embed_in_png(png: &[u8], diagram_json: &str) -> Vec<u8> {
        let Some(after_ihdr) = ihdr_end(png) else {
            return png.to_vec();
        };
        let mut data = Vec::new();
        data.extend_from_slice(MARKER.as_bytes());
        data.push(0); // keyword/text separator
        data.extend_from_slice(b64_encode(diagram_json).as_bytes());
        let chunk = png_chunk(*b"tEXt", &data);

        let mut out = Vec::with_capacity(png.len() + chunk.len());
        out.extend_from_slice(&png[..after_ihdr]);
        out.extend_from_slice(&chunk);
        out.extend_from_slice(&png[after_ihdr..]);
        out
    }

    /// The byte offset just past the `IHDR` chunk. `None` if the signature is
    /// wrong or the header is truncated.
    fn ihdr_end(png: &[u8]) -> Option<usize> {
        if png.len() < 8 || png[..8] != PNG_SIGNATURE {
            return None;
        }
        let ihdr_len = u32::from_be_bytes(png[8..12].try_into().ok()?) as usize;
        let end = 8 + 4 + 4 + ihdr_len + 4; // length + type + data + CRC
        (end <= png.len()).then_some(end)
    }

    /// Assemble a PNG chunk: big-endian length, 4-byte type, data, CRC-32 over
    /// type+data.
    pub(crate) fn png_chunk(kind: [u8; 4], data: &[u8]) -> Vec<u8> {
        let mut out = Vec::with_capacity(12 + data.len());
        out.extend_from_slice(&(data.len() as u32).to_be_bytes());
        out.extend_from_slice(&kind);
        out.extend_from_slice(data);
        let mut crc_input = Vec::with_capacity(4 + data.len());
        crc_input.extend_from_slice(&kind);
        crc_input.extend_from_slice(data);
        out.extend_from_slice(&crc32(&crc_input).to_be_bytes());
        out
    }

    /// PNG's CRC-32 (reflected, polynomial `0xEDB88320`) over a chunk's
    /// type+data.
    fn crc32(data: &[u8]) -> u32 {
        let mut crc: u32 = 0xFFFF_FFFF;
        for &byte in data {
            crc ^= byte as u32;
            for _ in 0..8 {
                let mask = (crc & 1).wrapping_neg();
                crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
            }
        }
        !crc
    }

    /// A minimal but structurally valid PNG: signature + IHDR + IEND. Enough
    /// for the chunk splicer/scanner to walk.
    pub(crate) fn tiny_png() -> Vec<u8> {
        let mut png = PNG_SIGNATURE.to_vec();
        let mut ihdr = Vec::new();
        ihdr.extend_from_slice(&1u32.to_be_bytes()); // width
        ihdr.extend_from_slice(&1u32.to_be_bytes()); // height
        ihdr.extend_from_slice(&[8, 6, 0, 0, 0]); // bit depth, color type, etc.
        png.extend_from_slice(&png_chunk(*b"IHDR", &ihdr));
        png.extend_from_slice(&png_chunk(*b"IEND", &[]));
        png
    }

    #[test]
    fn crc32_matches_known_value() {
        // The IEND chunk's CRC is a well-known constant (0xAE426082).
        assert_eq!(crc32(b"IEND"), 0xAE42_6082);
    }
}

#[cfg(test)]
mod tests {
    use super::fixtures::{embed_in_png, embed_in_svg, tiny_png};
    use super::*;

    const DIAGRAM: &str = r#"{"top":"b0","blocks":[{"id":"b0","x":0,"y":0,"w":10,"h":10}]}"#;

    #[test]
    fn svg_round_trips_the_diagram() {
        let svg = r#"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect/></svg>"#;
        let embedded = embed_in_svg(svg, DIAGRAM);
        assert!(embedded.contains("<rect/>"), "the picture is preserved");
        assert_eq!(extract_from_svg(&embedded).as_deref(), Some(DIAGRAM));
    }

    #[test]
    fn svg_without_metadata_extracts_none() {
        let svg = r#"<svg viewBox="0 0 1 1"><rect/></svg>"#;
        assert_eq!(extract_from_svg(svg), None);
    }

    #[test]
    fn png_round_trips_the_diagram() {
        let png = tiny_png();
        let embedded = embed_in_png(&png, DIAGRAM);
        assert!(embedded.len() > png.len(), "a chunk was added");
        // The original IHDR and IEND still bracket the file.
        assert_eq!(&embedded[..8], &PNG_SIGNATURE);
        assert_eq!(extract_from_png(&embedded).as_deref(), Some(DIAGRAM));
    }

    #[test]
    fn png_without_text_chunk_extracts_none() {
        assert_eq!(extract_from_png(&tiny_png()), None);
        assert_eq!(extract_from_png(b"not a png"), None);
    }
}