@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/export/custom-nodes.d.ts

@@ -0,0 +1,88 @@
+import type { VNode } from '../types/vnode.types';
+import type { Rectangle } from '../types/geometry.types';
+/**
+ * How faithfully a host's content could be captured.
+ *
+ * - `vector` the host's paint was transcribed to SVG primitives. Exact, and it
+ *   survives every target including PDF.
+ * - `html`   the host holds markup we could not transcribe. The SVG target can carry
+ *   it in a `<foreignObject>` (browsers render it); PDF and most standalone
+ *   rasterizers cannot. Always warned about.
+ * - `empty`  nothing capturable. A marked box plus a warning — never a silent blank.
+ */
+export type CustomNodeFidelity = 'vector' | 'html' | 'empty';
+/** What the DOM boundary hands the pure layer for one custom node. */
+export interface CustomNodeCapture {
+    /** The node id — carried onto the group, and what `includeIds` scoping matches. */
+    id: string;
+    /** The node's WORLD rect (position + size), i.e. where to place the content. */
+    rect: Rectangle;
+    fidelity: CustomNodeFidelity;
+    /**
+     * The transcribed display list, in HOST-RELATIVE coordinates (0,0 = the host's
+     * top-left). Placed by translating to `rect`. Only for `fidelity: 'vector'`.
+     */
+    content?: VNode[];
+    /** Raw XHTML for the `foreignObject` attempt. Only for `fidelity: 'html'`. */
+    html?: string;
+    /**
+     * A caveat the DOM boundary knows and this layer cannot see.
+     *
+     * `fidelity` describes what was READ; this describes what happened while reading it.
+     * They are independent, and the gap between them was a silent blank: an ASYNC painter
+     * that missed the export's deadline can leave a host holding half a widget, which
+     * captures perfectly as `fidelity: 'vector'` and would otherwise be reported as a clean
+     * export of a half-drawn chart. Emitted verbatim, ahead of any fidelity warning, because
+     * it is the CAUSE and the fidelity line is the consequence.
+     */
+    warning?: string;
+}
+/** What to do with a capture we could only get as HTML. */
+export type HtmlFallbackMode = 'foreignObject' | 'placeholder' | 'omit';
+export interface CustomNodeOptions {
+    /**
+     * How to export a `fidelity: 'html'` capture. Default `'foreignObject'` — the
+     * honest best effort: browsers render it, so an SVG opened in a browser or placed
+     * in a web page is correct. It is still reported as a fidelity risk, because a PDF
+     * and most standalone rasterizers will drop it.
+     */
+    htmlFallback?: HtmlFallbackMode;
+}
+/** Deterministic number formatting — no `-0`, no float noise, no locale. */
+export declare function n(value: number): string;
+/**
+ * The transform that maps a `viewBox` onto a rect the way `preserveAspectRatio` says
+ * — the fit an inline `<svg>` gets from the browser for free, resolved into an
+ * ordinary affine transform so every target can honour it.
+ *
+ * Supports the two forms that actually occur: `none` (stretch each axis
+ * independently) and `x??Y?? meet` (uniform scale, then align). `slice` is treated as
+ * `meet`: over-filling the widget box would paint a chart over its neighbours, and a
+ * chart that is slightly small is a far smaller lie than one that overlaps.
+ */
+export declare function viewBoxTransform(viewBox: Rectangle, rect: {
+    width: number;
+    height: number;
+}, preserveAspectRatio?: string): string;
+/**
+ * Turn captures into VNodes ready to append to the exported tree.
+ *
+ * Pure: same captures in, same VNodes and same warnings out. Order follows the input,
+ * which the boundary builds from the model's node order — so an export is byte-stable.
+ */
+export declare function customNodeVNodes(captures: readonly CustomNodeCapture[], options?: CustomNodeOptions): {
+    nodes: VNode[];
+    warnings: string[];
+};
+/**
+ * The union of the captures' world rects.
+ *
+ * Needed because a lifted chart is a `<g transform>` full of nested geometry and a
+ * `foreignObject`'s content is opaque — so `vnodeBounds` alone can under-measure a
+ * board. On an all-custom-node dashboard it would find NOTHING and fit the file to a
+ * 40px square. The node rects are the truth about where the widgets are, so the box
+ * is fitted to those as well.
+ */
+export declare function customNodeBounds(captures: readonly CustomNodeCapture[], includeIds?: ReadonlySet<string>): Rectangle | null;
+/** Keep only the captures whose node id is in `ids` — the `includeIds` scoping rule. */
+export declare function filterCaptures(captures: readonly CustomNodeCapture[], ids: Iterable<string> | undefined): readonly CustomNodeCapture[];

package/src/libs/renderer/src/export/custom-nodes.js

@@ -0,0 +1,237 @@
+"use strict";
+// CUSTOM-NODE EXPORT — the widget content that used to export as nothing at all.
+//
+// THE BUG THIS CLOSES
+// -------------------
+// A node with `metadata.useHTMLLayer` is not drawn by the renderer. `renderNode()`
+// returns an EMPTY `<g>` for it (see svg-renderer.ts) because its pixels are painted
+// by the page, into a raw HTML host that lives in `.grafloria-html-layer` — a sibling of
+// the SVG, not part of it. So every export path saw an empty group and faithfully
+// exported an empty group: a dashboard of six widgets exported as SIX EMPTY `<g>`s.
+// Not even a box. And nothing said so.
+//
+// THE SEAM
+// --------
+// The content is in the DOM, and only the DOM knows it. So the capture happens at the
+// boundary that HAS a DOM (`createDiagram` owns the hosts — see `capture-host.ts`) and
+// hands this module a `CustomNodeCapture`: PLAIN DATA, no elements, no live nodes.
+// Everything from here down is pure.
+//
+// WHY VNodes AND NOT MARKUP
+// -------------------------
+// The obvious move is to capture an SVG/HTML *string* and paste it into the output.
+// That would work for the SVG target and for nothing else. The renderer has THREE
+// consumers of a picture and they all read VNodes, not strings:
+//
+//   • `serializeVNode`  → the standalone SVG document
+//   • `paint()`          → the true-vector PDF writer (pdf/pdf-export.ts)
+//   • `vnodeBounds`      → the content-fit box, which decides the viewBox
+//
+// Capturing a display list of VNodes therefore makes ONE representation serve all
+// three: the widget lands in the SVG, in the PDF *as real vector*, and in the box the
+// export fits itself to. A string would have been invisible to the latter two.
+//
+// WHY THE viewBox IS BAKED INTO A TRANSFORM
+// -----------------------------------------
+// A lifted chart is an inline `<svg viewBox="0 0 640 250">` that the browser fits into
+// the host box for us. Emitting it as a NESTED `<svg>` would keep that magic in the SVG
+// target and lose it everywhere else: our PDF painter walks children but implements no
+// viewBox mapping, so every chart would paint at raw viewBox coordinates — wrong scale,
+// wrong place, off the page. So `viewBoxTransform()` resolves the fit ONCE, here, into
+// an ordinary `translate/scale` on a `<g>` — which the serializer, the PDF painter and
+// the bounds walker all already understand, identically.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.n = n;
+exports.viewBoxTransform = viewBoxTransform;
+exports.customNodeVNodes = customNodeVNodes;
+exports.customNodeBounds = customNodeBounds;
+exports.filterCaptures = filterCaptures;
+const XHTML_NS = 'http://www.w3.org/1999/xhtml';
+/** Deterministic number formatting — no `-0`, no float noise, no locale. */
+function n(value) {
+    if (!Number.isFinite(value))
+        return '0';
+    const rounded = Math.round(value * 1e4) / 1e4;
+    return Object.is(rounded, -0) ? '0' : String(rounded);
+}
+/**
+ * The transform that maps a `viewBox` onto a rect the way `preserveAspectRatio` says
+ * — the fit an inline `<svg>` gets from the browser for free, resolved into an
+ * ordinary affine transform so every target can honour it.
+ *
+ * Supports the two forms that actually occur: `none` (stretch each axis
+ * independently) and `x??Y?? meet` (uniform scale, then align). `slice` is treated as
+ * `meet`: over-filling the widget box would paint a chart over its neighbours, and a
+ * chart that is slightly small is a far smaller lie than one that overlaps.
+ */
+function viewBoxTransform(viewBox, rect, preserveAspectRatio = 'xMidYMid meet') {
+    const vw = viewBox.width;
+    const vh = viewBox.height;
+    if (!(vw > 0) || !(vh > 0))
+        return '';
+    const par = preserveAspectRatio.trim().toLowerCase();
+    const parts = [];
+    if (par.startsWith('none')) {
+        const sx = rect.width / vw;
+        const sy = rect.height / vh;
+        if (sx !== 1 || sy !== 1)
+            parts.push(`scale(${n(sx)} ${n(sy)})`);
+    }
+    else {
+        const s = Math.min(rect.width / vw, rect.height / vh);
+        // Alignment of the leftover space. Default (and the kit's own) is Mid/Mid.
+        const free = { x: rect.width - vw * s, y: rect.height - vh * s };
+        const alignX = par.includes('xmin') ? 0 : par.includes('xmax') ? free.x : free.x / 2;
+        const alignY = par.includes('ymin') ? 0 : par.includes('ymax') ? free.y : free.y / 2;
+        if (alignX !== 0 || alignY !== 0)
+            parts.push(`translate(${n(alignX)} ${n(alignY)})`);
+        if (s !== 1)
+            parts.push(`scale(${n(s)})`);
+    }
+    // The viewBox origin, undone last (applied first, innermost).
+    if (viewBox.x !== 0 || viewBox.y !== 0)
+        parts.push(`translate(${n(-viewBox.x)} ${n(-viewBox.y)})`);
+    return parts.join(' ');
+}
+/**
+ * Turn captures into VNodes ready to append to the exported tree.
+ *
+ * Pure: same captures in, same VNodes and same warnings out. Order follows the input,
+ * which the boundary builds from the model's node order — so an export is byte-stable.
+ */
+function customNodeVNodes(captures, options = {}) {
+    var _a;
+    const warnings = [];
+    const nodes = [];
+    const htmlFallback = (_a = options.htmlFallback) !== null && _a !== void 0 ? _a : 'foreignObject';
+    for (const capture of captures) {
+        // The boundary's own caveat FIRST — it is why the fidelity below is what it is.
+        if (capture.warning)
+            warnings.push(capture.warning);
+        const node = customNodeVNode(capture, htmlFallback, warnings);
+        if (node)
+            nodes.push(node);
+    }
+    return { nodes, warnings };
+}
+function customNodeVNode(capture, htmlFallback, warnings) {
+    var _a, _b;
+    const { id, rect } = capture;
+    if (capture.fidelity === 'vector') {
+        const content = (_a = capture.content) !== null && _a !== void 0 ? _a : [];
+        if (content.length === 0) {
+            // Claimed vector, transcribed to nothing — that is the silent blank we exist to
+            // prevent, so it degrades to the empty case rather than emitting a bare group.
+            return emptyCustomNode(capture, warnings, 'its captured content was empty');
+        }
+        return {
+            type: 'g',
+            key: `custom-node-${id}`,
+            props: {
+                className: 'grafloria-custom-node',
+                'data-node-id': id,
+                transform: `translate(${n(rect.x)} ${n(rect.y)})`,
+            },
+            children: content,
+        };
+    }
+    if (capture.fidelity === 'html') {
+        const html = (_b = capture.html) !== null && _b !== void 0 ? _b : '';
+        if (htmlFallback === 'omit') {
+            warnings.push(`custom node "${id}" is HTML and was DROPPED (htmlFallback: "omit") — it is missing from this export.`);
+            return null;
+        }
+        if (htmlFallback === 'placeholder' || html === '') {
+            warnings.push(`custom node "${id}" is HTML and was exported as a PLACEHOLDER BOX, not its content` +
+                (html === '' ? ' (nothing to embed)' : ' (htmlFallback: "placeholder")') +
+                '.');
+            return placeholderRect(capture);
+        }
+        warnings.push(`custom node "${id}" could not be transcribed to vector; embedded as <foreignObject> HTML. ` +
+            'Browsers render this, but PDF and most standalone SVG rasterizers (resvg, librsvg, ' +
+            'Inkscape CLI) IGNORE foreignObject — in those targets this widget will be blank.');
+        return {
+            type: 'foreignObject',
+            key: `custom-node-${id}`,
+            props: {
+                className: 'grafloria-custom-node',
+                'data-node-id': id,
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+            },
+            children: [
+                {
+                    type: 'div',
+                    props: { xmlns: XHTML_NS, innerHTML: html },
+                    children: [],
+                },
+            ],
+        };
+    }
+    return emptyCustomNode(capture, warnings, 'its host was empty or unreadable');
+}
+function emptyCustomNode(capture, warnings, why) {
+    warnings.push(`custom node "${capture.id}" exported as an EMPTY BOX — ${why}. ` +
+        'Its content is not in this file.');
+    return placeholderRect(capture);
+}
+/** The visible "something belongs here" marker. Never nothing. */
+function placeholderRect(capture) {
+    const { id, rect } = capture;
+    return {
+        type: 'rect',
+        key: `custom-node-${id}`,
+        props: {
+            className: 'grafloria-custom-node grafloria-custom-node-placeholder',
+            'data-node-id': id,
+            x: rect.x,
+            y: rect.y,
+            width: rect.width,
+            height: rect.height,
+            fill: 'none',
+            stroke: '#94a3b8',
+            'stroke-width': 1,
+            'stroke-dasharray': '4,4',
+        },
+        children: [],
+    };
+}
+/**
+ * The union of the captures' world rects.
+ *
+ * Needed because a lifted chart is a `<g transform>` full of nested geometry and a
+ * `foreignObject`'s content is opaque — so `vnodeBounds` alone can under-measure a
+ * board. On an all-custom-node dashboard it would find NOTHING and fit the file to a
+ * 40px square. The node rects are the truth about where the widgets are, so the box
+ * is fitted to those as well.
+ */
+function customNodeBounds(captures, includeIds) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const capture of captures) {
+        if (includeIds && !includeIds.has(capture.id))
+            continue;
+        const { x, y, width, height } = capture.rect;
+        if (![x, y, width, height].every(Number.isFinite))
+            continue;
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x + width);
+        maxY = Math.max(maxY, y + height);
+    }
+    if (!Number.isFinite(minX) || !Number.isFinite(minY))
+        return null;
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+/** Keep only the captures whose node id is in `ids` — the `includeIds` scoping rule. */
+function filterCaptures(captures, ids) {
+    if (ids === undefined)
+        return captures;
+    const set = ids instanceof Set ? ids : new Set(ids);
+    return captures.filter(capture => set.has(capture.id));
+}
+//# sourceMappingURL=custom-nodes.js.map

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

@@ -0,0 +1,14 @@
+export * from './style-flattener';
+export * from './vnode-serializer';
+export * from './bounds';
+export * from './scope';
+export * from './round-trip';
+export * from './assets';
+export * from './svg-export';
+export * from './custom-nodes';
+export * from './capture-host';
+export * from './raster';
+export * from './node-raster';
+export * from './pagination';
+export * from './pdf';
+export * from './batch';

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

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// Deterministic headless export: VNode → standalone SVG (→ PNG / JPEG / WebP).
+//
+// The renderer is already a pure VNode producer, so ONE serializer yields both the
+// live client picture (via vnode/patch.ts) and a server-side thumbnail from the
+// very same tree — no second rendering path, no drift.
+//
+// Entry points:
+//   exportSvg(vnode, opts)      pure, zero-DOM, deterministic → standalone SVG
+//   serializeVNode(vnode, opts) the VNode → XML primitive underneath it
+//   resolveRasterBackend(…)     the PNG/JPEG/WebP seam (browser canvas by default)
+//   SVGRenderer.export(fmt)     the wired IRenderer.export contract
+//   vnodeBounds(root)           the content-tight bbox of what is actually DRAWN
+tslib_1.__exportStar(require("./style-flattener"), exports);
+tslib_1.__exportStar(require("./vnode-serializer"), exports);
+tslib_1.__exportStar(require("./bounds"), exports);
+tslib_1.__exportStar(require("./scope"), exports);
+tslib_1.__exportStar(require("./round-trip"), exports);
+tslib_1.__exportStar(require("./assets"), exports);
+tslib_1.__exportStar(require("./svg-export"), exports);
+tslib_1.__exportStar(require("./custom-nodes"), exports);
+tslib_1.__exportStar(require("./capture-host"), exports);
+tslib_1.__exportStar(require("./raster"), exports);
+tslib_1.__exportStar(require("./node-raster"), exports);
+tslib_1.__exportStar(require("./pagination"), exports);
+tslib_1.__exportStar(require("./pdf"), exports);
+tslib_1.__exportStar(require("./batch"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,60 @@
+import type { RasterBackend } from './raster';
+/** The slice of `@resvg/resvg-js` we use. */
+export interface ResvgModule {
+    Resvg: new (svg: string | Uint8Array, options?: {
+        fitTo?: {
+            mode: 'width' | 'height';
+            value: number;
+        };
+    }) => {
+        render(): {
+            asPng(): Uint8Array;
+        };
+    };
+}
+/** The slice of `sharp` we use. */
+export type SharpModule = (input: Uint8Array, options?: {
+    density?: number;
+}) => {
+    resize(width: number, height: number): ReturnType<SharpModule>;
+    png(): ReturnType<SharpModule>;
+    jpeg(options?: {
+        quality?: number;
+    }): ReturnType<SharpModule>;
+    webp(options?: {
+        quality?: number;
+    }): ReturnType<SharpModule>;
+    flatten(options?: {
+        background?: string;
+    }): ReturnType<SharpModule>;
+    toBuffer(): Promise<Uint8Array>;
+};
+/**
+ * A PNG rasterizer backed by resvg. PNG only — resvg has no JPEG or WebP encoder, and
+ * pretending otherwise would mean handing a caller PNG bytes under a `image/jpeg` mime
+ * type, which is the kind of quiet lie this seam exists to prevent.
+ *
+ * `fitTo: width` is what applies the export's scale: the SVG carries the picture, and
+ * resvg renders it at the pixel width we ask for.
+ */
+export declare function createResvgBackend(resvg: ResvgModule): RasterBackend;
+/**
+ * A rasterizer backed by sharp (libvips + librsvg). Produces all three raster formats.
+ *
+ * The SVG goes in as BYTES, not as a path: sharp reads an SVG buffer through librsvg.
+ * `density` is how sharp scales vector input — 72 is the 1:1 baseline, so we scale the
+ * DPI by the ratio of the target pixel width to the SVG's intrinsic width and let
+ * librsvg rasterize at that resolution rather than upscaling a small bitmap.
+ */
+export declare function createSharpBackend(sharp: SharpModule): RasterBackend;
+/**
+ * Find a rasterizer in this Node process.
+ *
+ * The imports are DYNAMIC and the specifiers are built at runtime, so a bundler cannot
+ * statically resolve them and will not try to pull a native module into a browser bundle
+ * (which is how an optional native dep usually breaks a web build).
+ *
+ * @param format the format you intend to produce — only sharp can do the lossy ones, so
+ *        asking for jpeg/webp will not hand you a resvg backend that would then throw.
+ */
+export declare function loadNodeRasterBackend(format?: 'png' | 'jpeg' | 'webp'): Promise<RasterBackend>;

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

@@ -0,0 +1,161 @@
+"use strict";
+// The no-Chromium Node rasterizer (Card 6).
+//
+// Wave 4 built the `RasterBackend` seam and deliberately made bare Node THROW with
+// instructions rather than fake an image. This finishes the job: real backends, and a
+// loader that finds whichever one is installed.
+//
+// WHY NO DEPENDENCY IS ADDED
+// --------------------------
+// `libs/renderer` runs in the BROWSER. Taking a hard dependency on resvg-js or sharp
+// would force a native, platform-specific binary (~10-40MB, prebuilt per arch) into the
+// install of every app that only ever draws to a screen — to support a code path those
+// apps never call. So both stay OPTIONAL:
+//
+//   • `createResvgBackend(resvg)` / `createSharpBackend(sharp)` take the module as an
+//     ARGUMENT. The caller owns the dependency; we own the adapter. This is also what
+//     makes them trivially testable — the tests inject a fake and assert the wiring,
+//     with no native binary in CI.
+//   • `loadNodeRasterBackend()` dynamically imports whichever is present, and if neither
+//     is, throws an error that names the two packages and the one-line install.
+//
+// The SVG we hand these tools is already standalone — the cascade is flattened into
+// presentation attributes and there are no external references — which is precisely what
+// makes them work at all: resvg and librsvg implement neither CSS custom properties nor
+// selectors, so an un-flattened export would rasterize as black boxes in 16px serif.
+//
+// WHICH TOOL DOES WHAT
+//   resvg   Rust, self-contained, no system libraries, excellent SVG coverage. PNG ONLY.
+//   sharp   libvips + librsvg. PNG, JPEG and WebP. Needs librsvg present in the image.
+// So `loadNodeRasterBackend` prefers sharp when a lossy format is wanted and resvg
+// otherwise — and each backend REFUSES a format it cannot actually produce instead of
+// quietly handing back the wrong bytes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createResvgBackend = createResvgBackend;
+exports.createSharpBackend = createSharpBackend;
+exports.loadNodeRasterBackend = loadNodeRasterBackend;
+const tslib_1 = require("tslib");
+const round_trip_1 = require("./round-trip");
+// ---------------------------------------------------------------------------
+// resvg
+// ---------------------------------------------------------------------------
+/**
+ * A PNG rasterizer backed by resvg. PNG only — resvg has no JPEG or WebP encoder, and
+ * pretending otherwise would mean handing a caller PNG bytes under a `image/jpeg` mime
+ * type, which is the kind of quiet lie this seam exists to prevent.
+ *
+ * `fitTo: width` is what applies the export's scale: the SVG carries the picture, and
+ * resvg renders it at the pixel width we ask for.
+ */
+function createResvgBackend(resvg) {
+    return {
+        rasterize(_a) {
+            return tslib_1.__awaiter(this, arguments, void 0, function* ({ svg, width, mimeType }) {
+                if (mimeType !== 'image/png') {
+                    throw new Error(`[grafloria/export] the resvg backend cannot produce ${mimeType} — resvg only encodes PNG. ` +
+                        `Use the sharp backend (createSharpBackend) for JPEG/WebP, or export PNG.`);
+                }
+                const image = new resvg.Resvg(svg, {
+                    fitTo: { mode: 'width', value: Math.max(1, Math.round(width)) },
+                });
+                return (0, round_trip_1.bytesToDataUrl)(image.render().asPng(), 'image/png');
+            });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// sharp
+// ---------------------------------------------------------------------------
+/**
+ * A rasterizer backed by sharp (libvips + librsvg). Produces all three raster formats.
+ *
+ * The SVG goes in as BYTES, not as a path: sharp reads an SVG buffer through librsvg.
+ * `density` is how sharp scales vector input — 72 is the 1:1 baseline, so we scale the
+ * DPI by the ratio of the target pixel width to the SVG's intrinsic width and let
+ * librsvg rasterize at that resolution rather than upscaling a small bitmap.
+ */
+function createSharpBackend(sharp) {
+    return {
+        rasterize(_a) {
+            return tslib_1.__awaiter(this, arguments, void 0, function* ({ svg, width, height, mimeType, quality }) {
+                const targetWidth = Math.max(1, Math.round(width));
+                const targetHeight = Math.max(1, Math.round(height));
+                let pipeline = sharp(round_trip_1.utf8.encode(svg), { density: 72 }).resize(targetWidth, targetHeight);
+                // 0–1 (the canvas convention) → 1–100 (the encoder convention).
+                const q = quality === undefined ? undefined : Math.round(quality * 100);
+                switch (mimeType) {
+                    case 'image/png':
+                        pipeline = pipeline.png();
+                        break;
+                    case 'image/jpeg':
+                        // JPEG has no alpha: flatten, or transparent pixels come out BLACK.
+                        pipeline = pipeline.flatten({ background: '#ffffff' }).jpeg({ quality: q });
+                        break;
+                    case 'image/webp':
+                        pipeline = pipeline.webp({ quality: q });
+                        break;
+                    default:
+                        throw new Error(`[grafloria/export] the sharp backend cannot produce ${mimeType}`);
+                }
+                return (0, round_trip_1.bytesToDataUrl)(yield pipeline.toBuffer(), mimeType);
+            });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// The loader
+// ---------------------------------------------------------------------------
+const INSTALL_HINT = '[grafloria/export] headless raster export needs an SVG rasterizer, and neither is installed.\n' +
+    '  npm i @resvg/resvg-js   — PNG only; pure Rust, no system libraries (recommended)\n' +
+    '  npm i sharp             — PNG/JPEG/WebP; needs librsvg in the image\n' +
+    'Both are OPTIONAL: the renderer does not depend on either, so a browser build never ' +
+    'pays for them. SVG export needs no rasterizer at all.';
+/**
+ * Find a rasterizer in this Node process.
+ *
+ * The imports are DYNAMIC and the specifiers are built at runtime, so a bundler cannot
+ * statically resolve them and will not try to pull a native module into a browser bundle
+ * (which is how an optional native dep usually breaks a web build).
+ *
+ * @param format the format you intend to produce — only sharp can do the lossy ones, so
+ *        asking for jpeg/webp will not hand you a resvg backend that would then throw.
+ */
+function loadNodeRasterBackend() {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (format = 'png') {
+        const needsLossy = format === 'jpeg' || format === 'webp';
+        const sharp = yield tryImport('sharp');
+        if (sharp)
+            return createSharpBackend(sharp);
+        if (!needsLossy) {
+            const resvg = yield tryImport('@resvg/resvg-js');
+            if (resvg)
+                return createResvgBackend(resvg);
+        }
+        if (needsLossy) {
+            const resvg = yield tryImport('@resvg/resvg-js');
+            if (resvg) {
+                throw new Error(`[grafloria/export] only @resvg/resvg-js is installed, and it cannot encode ${format} (PNG only). ` +
+                    `Install sharp for JPEG/WebP, or export PNG.`);
+            }
+        }
+        throw new Error(INSTALL_HINT);
+    });
+}
+/** Import a module that may not be installed. `null` rather than a throw when it is not. */
+function tryImport(specifier) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a;
+        try {
+            // Assembled at runtime so bundlers leave it alone.
+            const dynamic = new Function('s', 'return import(s)');
+            const module = yield dynamic(specifier);
+            // resvg exports { Resvg }; sharp is a default-exported function.
+            const candidate = ((_a = module['default']) !== null && _a !== void 0 ? _a : module);
+            return candidate !== null && candidate !== void 0 ? candidate : null;
+        }
+        catch (_b) {
+            return null;
+        }
+    });
+}
+//# sourceMappingURL=node-raster.js.map