scrybe-mermaid

Standalone PNG iTXt codec: embeds and extracts Mermaid diagram source as invisible metadata inside a PNG file. Python on the outside, Rust on the inside.

What it does

Uses the PNG iTXt (international text) metadata chunk mechanism to store Mermaid diagram source alongside the rendered image. The PNG is fully valid and renders normally in any image viewer. The source text travels with the image and can be round-tripped without loss.

Python quick start

pip install scrybe-mermaid

from pathlib import Path
from scrybe_mermaid import embed, extract

source = """
graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
"""

# diagram.png: any PNG — render one with mmdc, Kroki, or the Mermaid live editor
png_in = Path("diagram.png").read_bytes()
png_out = embed(png_in, source)
Path("diagram-with-source.png").write_bytes(png_out)

payload = extract(png_out)  # verifies the embedded sha256 — raises ValueError if tampered
if payload.source != source:  # optional
    raise ValueError("Round-trip mismatch")
print(f"Round-tripped {len(payload.source)} chars; sha256={payload.sha256[:12]}…")

The resulting PNG renders normally in any image viewer and carries its own Mermaid source for round-tripping. See the API reference below.

Codec format

• Chunk key: scrybe-mermaid
• Value: JSON { "source": "<mermaid source>", "sha256": "<hex>", "uuid": "<v4>" }

The sha256 field is a SHA-256 digest of the source bytes, and extract enforces it by default: the digest is recomputed from the extracted source and compared against the stored value. Three outcomes are distinguished:

A payload with no digest is never reported as verified. For forensics on tampered or foreign payloads, extract_unverified returns the raw stored fields without any check.

Role in the architecture

scrybe-mermaid is a self-contained utility crate with no dependency on scrybe-core. It is used by scrybe-mcp-server (the embed/extract tools), scrybe-cli (scrybe mermaid embed/extract/verify), and the Tauri backend.

Key public types and entry points

Build and test

cargo build -p scrybe-mermaid
cargo test -p scrybe-mermaid

The codec parses PNG chunks from first principles — no external binaries required.