@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/export/raster.js

@@ -0,0 +1,126 @@
+"use strict";
+// PNG / JPEG / WebP: rasterizing the standalone SVG.
+//
+// BE HONEST ABOUT THE BOUNDARY. Turning SVG into pixels requires an SVG ENGINE.
+// A browser has one (that is what `<img src="data:image/svg+xml,…">` + `canvas`
+// borrows); bare Node does not, and shipping one (resvg / skia / a headless
+// Chromium) would be a heavyweight dependency this library does not get to make
+// on its users' behalf.
+//
+// So rasterization is a SEAM, not a hard-coded implementation:
+//
+//   • {@link createDomRasterBackend} — zero-dependency, works wherever there is a
+//     canvas: the browser main thread, and a worker (via OffscreenCanvas). This is
+//     what `renderer.export('png')` uses by default in a browser.
+//   • {@link RasterBackend} — implement it with resvg-js / sharp / puppeteer in a
+//     Node service and pass it as `options.rasterBackend`. ~10 lines, and the SVG
+//     it receives is already standalone (styles inlined, no external refs), which
+//     is precisely what makes those rasterizers work at all.
+//
+// In plain Node with no backend, `export('png')` THROWS with that instruction —
+// it does not silently return a broken or empty image.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mimeTypeForFormat = mimeTypeForFormat;
+exports.svgToDataUri = svgToDataUri;
+exports.canRasterizeInThisEnvironment = canRasterizeInThisEnvironment;
+exports.createDomRasterBackend = createDomRasterBackend;
+exports.resolveRasterBackend = resolveRasterBackend;
+const tslib_1 = require("tslib");
+const MIME_BY_FORMAT = {
+    png: 'image/png',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+};
+/** `'png'` → `'image/png'`. Throws for a format that is not a raster format. */
+function mimeTypeForFormat(format) {
+    const mime = MIME_BY_FORMAT[format];
+    if (!mime)
+        throw new Error(`[grafloria/export] "${format}" is not a raster format`);
+    return mime;
+}
+/**
+ * SVG string → `data:image/svg+xml` URL.
+ *
+ * `encodeURIComponent`, NOT base64: `btoa` throws on any non-Latin-1 character,
+ * so a diagram with a non-ASCII label (or the renderer's own '…' ellipsis, or the
+ * 📌 lock indicator) would blow up the PNG path.
+ */
+function svgToDataUri(svg) {
+    return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+/** Is there a canvas we can draw into? (browser main thread or worker) */
+function canRasterizeInThisEnvironment() {
+    const g = globalThis;
+    return typeof g.Image === 'function' && (typeof g.OffscreenCanvas === 'function' || typeof g.document !== 'undefined');
+}
+/**
+ * The zero-dependency browser backend: draw the SVG into a canvas and read the
+ * pixels back out.
+ *
+ * Prefers `OffscreenCanvas` when present (so it works in a worker, off the main
+ * thread) and falls back to a detached `<canvas>`.
+ */
+function createDomRasterBackend() {
+    return {
+        rasterize(_a) {
+            return tslib_1.__awaiter(this, arguments, void 0, function* ({ svg, width, height, mimeType, quality }) {
+                const g = globalThis;
+                if (!canRasterizeInThisEnvironment()) {
+                    throw new Error('[grafloria/export] no canvas in this environment. Pass options.rasterBackend ' +
+                        '(e.g. resvg-js / sharp / puppeteer) to rasterize outside a browser.');
+                }
+                const image = new g.Image();
+                image.width = width;
+                image.height = height;
+                yield new Promise((resolve, reject) => {
+                    image.onload = () => resolve();
+                    image.onerror = () => reject(new Error('[grafloria/export] the browser failed to decode the exported SVG'));
+                    image.src = svgToDataUri(svg);
+                });
+                const pixelWidth = Math.max(1, Math.round(width));
+                const pixelHeight = Math.max(1, Math.round(height));
+                if (typeof g.OffscreenCanvas === 'function') {
+                    const canvas = new g.OffscreenCanvas(pixelWidth, pixelHeight);
+                    const ctx = canvas.getContext('2d');
+                    if (!ctx)
+                        throw new Error('[grafloria/export] OffscreenCanvas 2d context unavailable');
+                    ctx.drawImage(image, 0, 0, pixelWidth, pixelHeight);
+                    const blob = yield canvas.convertToBlob({ type: mimeType, quality });
+                    return yield blobToDataUrl(blob);
+                }
+                const canvas = g.document.createElement('canvas');
+                canvas.width = pixelWidth;
+                canvas.height = pixelHeight;
+                const ctx = canvas.getContext('2d');
+                if (!ctx)
+                    throw new Error('[grafloria/export] canvas 2d context unavailable');
+                ctx.drawImage(image, 0, 0, pixelWidth, pixelHeight);
+                return canvas.toDataURL(mimeType, quality);
+            });
+        },
+    };
+}
+function blobToDataUrl(blob) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const buffer = yield blob.arrayBuffer();
+        const bytes = new Uint8Array(buffer);
+        let binary = '';
+        for (let i = 0; i < bytes.length; i++)
+            binary += String.fromCharCode(bytes[i]);
+        return `data:${blob.type};base64,${globalThis.btoa(binary)}`;
+    });
+}
+/**
+ * The backend an export will actually use: the caller's, else the browser one,
+ * else a hard failure that tells you exactly what to do.
+ */
+function resolveRasterBackend(explicit) {
+    if (explicit)
+        return explicit;
+    if (canRasterizeInThisEnvironment())
+        return createDomRasterBackend();
+    throw new Error('[grafloria/export] raster export needs an SVG rasterizer. There is none in this environment ' +
+        '(no canvas). Either export("svg") — which is fully headless — or pass options.rasterBackend ' +
+        'backed by resvg-js / sharp / puppeteer.');
+}
+//# sourceMappingURL=raster.js.map

package/src/libs/renderer/src/export/round-trip.d.ts

@@ -0,0 +1,83 @@
+import type { DiagramDocumentEnvelope, DiagramModel, DiagramLoadOptions } from '@grafloria/engine';
+/** The XML namespace the embedded model lives in. */
+export declare const GRAFLORIA_NS = "https://grafloria.dev/ns/diagram";
+/**
+ * The PNG text-chunk keyword, and the SVG element name.
+ *
+ * NOT `grafloria-diagram`: that is already the CSS class on the exported root
+ * (`class="grafloria-diagram"`), so "does this file carry a model?" would answer YES for
+ * every export we have ever produced.
+ */
+export declare const GRAFLORIA_MODEL_KEY = "grafloria-model";
+/**
+ * Insert the model into an SVG document, right after the root `<svg …>` tag.
+ *
+ * The JSON is XML-escaped text, not base64 — it stays greppable and diffable, and the
+ * envelope's checksum catches any tool that mangles it on the way through.
+ */
+export declare function embedModelInSvg(svg: string, envelope: DiagramDocumentEnvelope): string;
+/**
+ * Pull the model back out of an SVG. `null` when there is none — a plain SVG is not
+ * an error, it is just not editable.
+ *
+ * THROWS if a model IS present but does not parse: a corrupted payload must not
+ * silently degrade into "no model", which would look to the user like a successful
+ * import of an empty diagram.
+ */
+export declare function extractModelFromSvg(svg: string): DiagramDocumentEnvelope | null;
+export declare function crc32(bytes: Uint8Array): number;
+/**
+ * UTF-8, implemented rather than borrowed.
+ *
+ * `TextEncoder`/`TextDecoder` are NOT reliably global: they are absent in jsdom (which
+ * is what the renderer's own tests run in) and were late to Node. Sniffing for them and
+ * falling back would give two code paths that can disagree about a surrogate pair — in a
+ * module whose entire job is lossless bytes. So: one path, always, everywhere.
+ */
+export declare const utf8: {
+    encode(text: string): Uint8Array;
+    decode(bytes: Uint8Array): string;
+};
+/**
+ * Insert the model into a PNG as an `iTXt` chunk, immediately before `IEND`.
+ *
+ * The pixels are untouched: the result is the same image, and any decoder that does
+ * not know the chunk simply skips it (text chunks are ancillary by definition).
+ */
+export declare function embedModelInPng(png: Uint8Array, envelope: DiagramDocumentEnvelope): Uint8Array;
+/**
+ * Pull the model back out of a PNG. `null` when the image carries none.
+ *
+ * Reads BOTH `iTXt` (what we write) and `tEXt` (so a file produced by another tool, or
+ * an older writer, still opens).
+ */
+export declare function extractModelFromPng(png: Uint8Array): DiagramDocumentEnvelope | null;
+/** Pure base64 → bytes. (No `atob`: it does not exist in Node, and this must stay DOM-free.) */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/** Pure bytes → base64. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** `data:image/png;base64,…` → the bytes. Throws on a URL that is not base64 data. */
+export declare function dataUrlToBytes(dataUrl: string): Uint8Array;
+/** bytes → `data:<mime>;base64,…` */
+export declare function bytesToDataUrl(bytes: Uint8Array, mimeType: string): string;
+/** Anything a user might drop on the canvas: an SVG string, a data: URL, or raw bytes. */
+export type Artifact = string | Uint8Array;
+/**
+ * Find the embedded model in ANY exported artifact — SVG text, a `data:` URL of
+ * either kind, or PNG bytes. `null` when the artifact carries no model (a plain image
+ * is not an error; it is simply not editable).
+ */
+export declare function extractModel(artifact: Artifact): DiagramDocumentEnvelope | null;
+/** Does this artifact carry a model we could re-open? */
+export declare function isEditableArtifact(artifact: Artifact): boolean;
+/**
+ * Re-open an exported artifact as a live diagram.
+ *
+ * The rehydration runs through the ENGINE's own `DiagramSerializer.deserialize`, which
+ * unwraps the envelope, VERIFIES the checksum (throwing on a mismatch), and runs the
+ * schema migrations. So an artifact exported by an older build opens in a newer one,
+ * and a corrupted one refuses to open rather than opening subtly wrong.
+ *
+ * Returns `null` for an artifact with no embedded model.
+ */
+export declare function importDiagram(artifact: Artifact, options?: DiagramLoadOptions): DiagramModel | null;

package/src/libs/renderer/src/export/round-trip.js

@@ -0,0 +1,432 @@
+"use strict";
+// EDITABLE ROUND-TRIP: the exported picture IS the document.
+//
+// An exported PNG or SVG is normally a dead end — the model that produced it is gone,
+// so "open this diagram someone sent me" means "redraw it by hand". This carries the
+// source model INSIDE the artifact, so an export can be re-imported and edited with
+// no loss.
+//
+// WE DO NOT INVENT A FORMAT. The engine already has:
+//   • a suite-enforced lossless round-trip invariant — serialize(fromJSON(serialize(d)))
+//     is byte-identical to serialize(d);
+//   • a portable document envelope with a generator identity and an FNV-1a checksum
+//     over the canonical (key-sorted) JSON, which `unwrapDiagramDocument` VERIFIES on
+//     load and throws on mismatch.
+// So the payload embedded here is exactly that envelope. The checksum is the thing
+// that makes this safe: an SVG that some other tool has re-indented, or a PNG that a
+// pipeline has re-encoded, does not load as a subtly-wrong diagram — it fails loudly.
+//
+// WHERE IT GOES
+//   SVG   a namespaced <grafloria:model> inside <metadata>. `<metadata>` is the element
+//         SVG defines for exactly this, every renderer ignores its content, and a
+//         foreign namespace keeps us out of everyone else's way.
+//   PNG   an `iTXt` chunk. PNG's text chunks are ancillary, so a decoder that does not
+//         know them skips them and the image still displays anywhere.
+//
+// WHY iTXt AND NOT tEXt: `tEXt` is Latin-1 ONLY. A diagram with a non-Latin-1 label —
+// any Arabic, CJK, or even a curly quote — would be silently mangled on the way into a
+// tEXt chunk. `iTXt` is UTF-8 by definition, which is what JSON needs.
+//
+// Everything here is pure: no DOM, no deps, no clock. (The envelope's `createdAt` is
+// the one non-deterministic field, so `embedModel` takes it from the caller — see
+// `SvgExportOptions.embedModel`.)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utf8 = exports.GRAFLORIA_MODEL_KEY = exports.GRAFLORIA_NS = void 0;
+exports.embedModelInSvg = embedModelInSvg;
+exports.extractModelFromSvg = extractModelFromSvg;
+exports.crc32 = crc32;
+exports.embedModelInPng = embedModelInPng;
+exports.extractModelFromPng = extractModelFromPng;
+exports.base64ToBytes = base64ToBytes;
+exports.bytesToBase64 = bytesToBase64;
+exports.dataUrlToBytes = dataUrlToBytes;
+exports.bytesToDataUrl = bytesToDataUrl;
+exports.extractModel = extractModel;
+exports.isEditableArtifact = isEditableArtifact;
+exports.importDiagram = importDiagram;
+const engine_1 = require("@grafloria/engine");
+/** The XML namespace the embedded model lives in. */
+exports.GRAFLORIA_NS = 'https://grafloria.dev/ns/diagram';
+/**
+ * The PNG text-chunk keyword, and the SVG element name.
+ *
+ * NOT `grafloria-diagram`: that is already the CSS class on the exported root
+ * (`class="grafloria-diagram"`), so "does this file carry a model?" would answer YES for
+ * every export we have ever produced.
+ */
+exports.GRAFLORIA_MODEL_KEY = 'grafloria-model';
+// ---------------------------------------------------------------------------
+// SVG
+// ---------------------------------------------------------------------------
+function escapeXmlText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function unescapeXmlText(value) {
+    // &amp; LAST: doing it first would turn `&amp;lt;` into `<` instead of `&lt;`.
+    return value
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+/**
+ * Insert the model into an SVG document, right after the root `<svg …>` tag.
+ *
+ * The JSON is XML-escaped text, not base64 — it stays greppable and diffable, and the
+ * envelope's checksum catches any tool that mangles it on the way through.
+ */
+function embedModelInSvg(svg, envelope) {
+    const json = JSON.stringify(envelope);
+    const block = `<metadata>` +
+        `<${exports.GRAFLORIA_MODEL_KEY} xmlns="${exports.GRAFLORIA_NS}">${escapeXmlText(json)}</${exports.GRAFLORIA_MODEL_KEY}>` +
+        `</metadata>`;
+    const rootEnd = svg.indexOf('>', svg.indexOf('<svg'));
+    if (rootEnd < 0)
+        return svg; // not an SVG we recognise — leave it alone
+    return svg.slice(0, rootEnd + 1) + block + svg.slice(rootEnd + 1);
+}
+const MODEL_BLOCK = new RegExp(`<${exports.GRAFLORIA_MODEL_KEY}[^>]*>([\\s\\S]*?)</${exports.GRAFLORIA_MODEL_KEY}>`);
+/**
+ * Pull the model back out of an SVG. `null` when there is none — a plain SVG is not
+ * an error, it is just not editable.
+ *
+ * THROWS if a model IS present but does not parse: a corrupted payload must not
+ * silently degrade into "no model", which would look to the user like a successful
+ * import of an empty diagram.
+ */
+function extractModelFromSvg(svg) {
+    const match = MODEL_BLOCK.exec(svg);
+    if (!match)
+        return null;
+    const json = unescapeXmlText(match[1]);
+    try {
+        return JSON.parse(json);
+    }
+    catch (cause) {
+        throw new Error(`[grafloria/export] this SVG carries an embedded Grafloria model, but it is not valid JSON — ` +
+            `the file was modified or truncated after it was written. (${cause.message})`);
+    }
+}
+// ---------------------------------------------------------------------------
+// PNG
+// ---------------------------------------------------------------------------
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** The standard CRC-32 (IEEE) PNG requires on every chunk. */
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function isPng(bytes) {
+    if (bytes.length < 8)
+        return false;
+    return PNG_SIGNATURE.every((b, i) => bytes[i] === b);
+}
+function readUint32(bytes, offset) {
+    return (((bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]) >>> 0);
+}
+function writeUint32(value) {
+    return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff];
+}
+/**
+ * UTF-8, implemented rather than borrowed.
+ *
+ * `TextEncoder`/`TextDecoder` are NOT reliably global: they are absent in jsdom (which
+ * is what the renderer's own tests run in) and were late to Node. Sniffing for them and
+ * falling back would give two code paths that can disagree about a surrogate pair — in a
+ * module whose entire job is lossless bytes. So: one path, always, everywhere.
+ */
+exports.utf8 = {
+    encode(text) {
+        const out = [];
+        for (let i = 0; i < text.length; i++) {
+            let code = text.charCodeAt(i);
+            // A surrogate PAIR is one code point; combine it before encoding.
+            if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+                const low = text.charCodeAt(i + 1);
+                if (low >= 0xdc00 && low <= 0xdfff) {
+                    code = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+                    i++;
+                }
+            }
+            if (code < 0x80) {
+                out.push(code);
+            }
+            else if (code < 0x800) {
+                out.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+            }
+            else if (code < 0x10000) {
+                out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+            }
+            else {
+                out.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 0x3f), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+            }
+        }
+        return new Uint8Array(out);
+    },
+    decode(bytes) {
+        let out = '';
+        for (let i = 0; i < bytes.length;) {
+            const byte = bytes[i];
+            let code;
+            if (byte < 0x80) {
+                code = byte;
+                i += 1;
+            }
+            else if ((byte & 0xe0) === 0xc0) {
+                code = ((byte & 0x1f) << 6) | (bytes[i + 1] & 0x3f);
+                i += 2;
+            }
+            else if ((byte & 0xf0) === 0xe0) {
+                code = ((byte & 0x0f) << 12) | ((bytes[i + 1] & 0x3f) << 6) | (bytes[i + 2] & 0x3f);
+                i += 3;
+            }
+            else {
+                code =
+                    ((byte & 0x07) << 18) |
+                        ((bytes[i + 1] & 0x3f) << 12) |
+                        ((bytes[i + 2] & 0x3f) << 6) |
+                        (bytes[i + 3] & 0x3f);
+                i += 4;
+            }
+            // Anything past the BMP goes back out as a surrogate pair.
+            if (code > 0xffff) {
+                code -= 0x10000;
+                out += String.fromCharCode(0xd800 + (code >> 10), 0xdc00 + (code & 0x3ff));
+            }
+            else {
+                out += String.fromCharCode(code);
+            }
+        }
+        return out;
+    },
+};
+/**
+ * Build an uncompressed `iTXt` chunk.
+ *
+ * Layout (PNG spec 11.3.4.5):
+ *   keyword \0 compressionFlag compressionMethod languageTag \0 translatedKeyword \0 text
+ * with the text in UTF-8. We do not compress (flag 0), so `compressionMethod` is 0 and
+ * ignored, and the payload stays readable to `strings`.
+ */
+function buildITxtChunk(keyword, text) {
+    const data = [
+        ...exports.utf8.encode(keyword),
+        0, // keyword terminator
+        0, // compression flag: uncompressed
+        0, // compression method
+        0, // language tag: empty, terminated
+        0, // translated keyword: empty, terminated
+        ...exports.utf8.encode(text),
+    ];
+    const type = exports.utf8.encode('iTXt');
+    const typeAndData = new Uint8Array([...type, ...data]);
+    return new Uint8Array([
+        ...writeUint32(data.length), // length counts the DATA only, not the type
+        ...typeAndData,
+        ...writeUint32(crc32(typeAndData)), // CRC covers type + data
+    ]);
+}
+/**
+ * Insert the model into a PNG as an `iTXt` chunk, immediately before `IEND`.
+ *
+ * The pixels are untouched: the result is the same image, and any decoder that does
+ * not know the chunk simply skips it (text chunks are ancillary by definition).
+ */
+function embedModelInPng(png, envelope) {
+    if (!isPng(png)) {
+        throw new Error('[grafloria/export] not a PNG (bad signature) — cannot embed the model');
+    }
+    const chunk = buildITxtChunk(exports.GRAFLORIA_MODEL_KEY, JSON.stringify(envelope));
+    const iend = findChunk(png, 'IEND');
+    if (iend === null) {
+        throw new Error('[grafloria/export] malformed PNG: no IEND chunk');
+    }
+    // …[chunks]… | OUR CHUNK | IEND
+    const out = new Uint8Array(png.length + chunk.length);
+    out.set(png.subarray(0, iend.start), 0);
+    out.set(chunk, iend.start);
+    out.set(png.subarray(iend.start), iend.start + chunk.length);
+    return out;
+}
+/** Walk the chunk list. Returns the FIRST chunk of the given type. */
+function findChunk(png, type, keyword) {
+    let offset = 8; // past the signature
+    while (offset + 8 <= png.length) {
+        const length = readUint32(png, offset);
+        const chunkType = String.fromCharCode(png[offset + 4], png[offset + 5], png[offset + 6], png[offset + 7]);
+        const dataStart = offset + 8;
+        if (chunkType === type) {
+            if (keyword === undefined) {
+                return { start: offset, dataStart, length };
+            }
+            // Match on the chunk's keyword (the bytes up to the first NUL).
+            const nul = png.indexOf(0, dataStart);
+            if (nul > 0 && nul < dataStart + length) {
+                const found = exports.utf8.decode(png.subarray(dataStart, nul));
+                if (found === keyword)
+                    return { start: offset, dataStart, length };
+            }
+        }
+        // length + type(4) + data + crc(4)
+        offset = dataStart + length + 4;
+    }
+    return null;
+}
+/**
+ * Pull the model back out of a PNG. `null` when the image carries none.
+ *
+ * Reads BOTH `iTXt` (what we write) and `tEXt` (so a file produced by another tool, or
+ * an older writer, still opens).
+ */
+function extractModelFromPng(png) {
+    var _a;
+    if (!isPng(png))
+        return null;
+    const json = (_a = readITxt(png)) !== null && _a !== void 0 ? _a : readTExt(png);
+    if (json === null)
+        return null;
+    try {
+        return JSON.parse(json);
+    }
+    catch (cause) {
+        throw new Error(`[grafloria/export] this PNG carries an embedded Grafloria model, but it is not valid JSON — ` +
+            `the file was re-encoded or truncated after it was written. (${cause.message})`);
+    }
+}
+function readITxt(png) {
+    const chunk = findChunk(png, 'iTXt', exports.GRAFLORIA_MODEL_KEY);
+    if (!chunk)
+        return null;
+    const end = chunk.dataStart + chunk.length;
+    // keyword \0 flag method lang \0 translated \0 text
+    let cursor = png.indexOf(0, chunk.dataStart) + 1; // past keyword
+    const compressed = png[cursor];
+    cursor += 2; // compression flag + method
+    if (compressed === 1) {
+        throw new Error('[grafloria/export] the embedded model is a COMPRESSED iTXt chunk. This reader does not inflate ' +
+            '(zlib is not a dependency of the renderer) — re-export with the Grafloria writer, which never compresses.');
+    }
+    cursor = png.indexOf(0, cursor) + 1; // past language tag
+    cursor = png.indexOf(0, cursor) + 1; // past translated keyword
+    return exports.utf8.decode(png.subarray(cursor, end));
+}
+function readTExt(png) {
+    const chunk = findChunk(png, 'tEXt', exports.GRAFLORIA_MODEL_KEY);
+    if (!chunk)
+        return null;
+    const end = chunk.dataStart + chunk.length;
+    const cursor = png.indexOf(0, chunk.dataStart) + 1; // past keyword
+    return exports.utf8.decode(png.subarray(cursor, end));
+}
+// ---------------------------------------------------------------------------
+// data: URLs — the raster backends hand back a URL, not bytes
+// ---------------------------------------------------------------------------
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** Pure base64 → bytes. (No `atob`: it does not exist in Node, and this must stay DOM-free.) */
+function base64ToBytes(base64) {
+    const clean = base64.replace(/[^A-Za-z0-9+/]/g, '');
+    const out = new Uint8Array((clean.length * 3) >> 2);
+    let outIndex = 0;
+    let buffer = 0;
+    let bits = 0;
+    for (let i = 0; i < clean.length; i++) {
+        buffer = (buffer << 6) | B64.indexOf(clean[i]);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[outIndex++] = (buffer >> bits) & 0xff;
+        }
+    }
+    return out.subarray(0, outIndex);
+}
+/** Pure bytes → base64. */
+function bytesToBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i];
+        const b = i + 1 < bytes.length ? bytes[i + 1] : undefined;
+        const c = i + 2 < bytes.length ? bytes[i + 2] : undefined;
+        out += B64[a >> 2];
+        out += B64[((a & 0x03) << 4) | ((b !== null && b !== void 0 ? b : 0) >> 4)];
+        out += b === undefined ? '=' : B64[((b & 0x0f) << 2) | ((c !== null && c !== void 0 ? c : 0) >> 6)];
+        out += c === undefined ? '=' : B64[c & 0x3f];
+    }
+    return out;
+}
+/** `data:image/png;base64,…` → the bytes. Throws on a URL that is not base64 data. */
+function dataUrlToBytes(dataUrl) {
+    const comma = dataUrl.indexOf(',');
+    if (!dataUrl.startsWith('data:') || comma < 0) {
+        throw new Error('[grafloria/export] not a data: URL');
+    }
+    const header = dataUrl.slice(5, comma);
+    const payload = dataUrl.slice(comma + 1);
+    if (!header.includes('base64')) {
+        // The SVG data URL path is percent-encoded, not base64 (btoa cannot take non-Latin-1).
+        return exports.utf8.encode(decodeURIComponent(payload));
+    }
+    return base64ToBytes(payload);
+}
+/** bytes → `data:<mime>;base64,…` */
+function bytesToDataUrl(bytes, mimeType) {
+    return `data:${mimeType};base64,${bytesToBase64(bytes)}`;
+}
+/**
+ * Find the embedded model in ANY exported artifact — SVG text, a `data:` URL of
+ * either kind, or PNG bytes. `null` when the artifact carries no model (a plain image
+ * is not an error; it is simply not editable).
+ */
+function extractModel(artifact) {
+    if (typeof artifact !== 'string') {
+        // Bytes: a PNG, or an SVG someone read as a buffer.
+        return isPng(artifact) ? extractModelFromPng(artifact) : extractModelFromSvg(exports.utf8.decode(artifact));
+    }
+    if (artifact.startsWith('data:')) {
+        const bytes = dataUrlToBytes(artifact);
+        return isPng(bytes) ? extractModelFromPng(bytes) : extractModelFromSvg(exports.utf8.decode(bytes));
+    }
+    return extractModelFromSvg(artifact);
+}
+/** Does this artifact carry a model we could re-open? */
+function isEditableArtifact(artifact) {
+    try {
+        return extractModel(artifact) !== null;
+    }
+    catch (_a) {
+        // A present-but-broken payload is not an editable artifact — but it IS a thing the
+        // caller may want to report, so `extractModel` still throws for anyone who asks.
+        return false;
+    }
+}
+/**
+ * Re-open an exported artifact as a live diagram.
+ *
+ * The rehydration runs through the ENGINE's own `DiagramSerializer.deserialize`, which
+ * unwraps the envelope, VERIFIES the checksum (throwing on a mismatch), and runs the
+ * schema migrations. So an artifact exported by an older build opens in a newer one,
+ * and a corrupted one refuses to open rather than opening subtly wrong.
+ *
+ * Returns `null` for an artifact with no embedded model.
+ */
+function importDiagram(artifact, options) {
+    const envelope = extractModel(artifact);
+    if (!envelope)
+        return null;
+    return new engine_1.DiagramSerializer().deserialize(envelope, options);
+}
+//# sourceMappingURL=round-trip.js.map

package/src/libs/renderer/src/export/scope.d.ts

@@ -0,0 +1,16 @@
+import type { VNode } from '../types/vnode.types';
+/**
+ * Every key shape the renderer can mint for a given diagram id.
+ *
+ * `renderNode` has a second early-return path for HTML-layer nodes that keys them
+ * `node-<id>-html-layer`, so an exact-match set built only from `node-<id>` would
+ * silently drop those from a selection export.
+ */
+export declare function selectionKeys(ids: Iterable<string>): Set<string>;
+/**
+ * Prune a rendered tree down to the given node/link ids.
+ *
+ * Returns a new tree; the input is not mutated (the caller's tree is the live
+ * render, and mutating it would corrupt the next frame).
+ */
+export declare function filterTreeByIds(root: VNode, ids: Iterable<string>): VNode;