@grafloria/element 0.3.18 → 0.3.19

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

@@ -0,0 +1,42 @@
+/** What a rasterizer is asked to produce. */
+export interface RasterizeRequest {
+    /** A standalone SVG document (styles inlined, no external references). */
+    svg: string;
+    /** Target pixel width (already scaled). */
+    width: number;
+    /** Target pixel height (already scaled). */
+    height: number;
+    /** `image/png` | `image/jpeg` | `image/webp`. */
+    mimeType: string;
+    /** 0–1, for the lossy formats. */
+    quality?: number;
+}
+/** Pluggable rasterizer. Returns a `data:` URL. */
+export interface RasterBackend {
+    rasterize(request: RasterizeRequest): Promise<string>;
+}
+/** `'png'` → `'image/png'`. Throws for a format that is not a raster format. */
+export declare function mimeTypeForFormat(format: string): string;
+/**
+ * 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.
+ */
+export declare function svgToDataUri(svg: string): string;
+/** Is there a canvas we can draw into? (browser main thread or worker) */
+export declare function canRasterizeInThisEnvironment(): boolean;
+/**
+ * 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>`.
+ */
+export declare function createDomRasterBackend(): RasterBackend;
+/**
+ * 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.
+ */
+export declare function resolveRasterBackend(explicit?: RasterBackend): RasterBackend;

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/raster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raster.js","sourceRoot":"","sources":["../../../../../../renderer/src/export/raster.ts"],"names":[],"mappings":"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"}

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;