@grafloria/element 0.3.18 → 0.3.20

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

@@ -0,0 +1,69 @@
+"use strict";
+// Export scope: WHICH parts of the diagram end up in the file.
+//
+// Tightening the viewBox around a selection is not enough on its own. SVG clips to
+// the viewBox, so an un-selected node outside it is invisible — but its markup is
+// still IN THE FILE. That is a bloated artifact and, for a "share just this bit"
+// export, an information leak: the bytes carry every label of every node the user
+// did not choose to share. So a selection export PRUNES the tree as well as the box.
+//
+// The prune keeps:
+//   • every container (layers, <defs>) — a kept node may reference a gradient or a
+//     marker that lives in <defs>, and dropping it would leave a dangling url(#…);
+//   • every identified diagram object (`node-<id>` / `link-<id>`) whose id is in scope,
+//     with its whole subtree intact (a node's label and ports are part of the node).
+//
+// and drops every identified object that is not in scope.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectionKeys = selectionKeys;
+exports.filterTreeByIds = filterTreeByIds;
+/** The VNode `key` prefixes the renderer stamps on identified diagram objects. */
+const IDENTIFIED = /^(node|link)-/;
+/**
+ * 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.
+ */
+function selectionKeys(ids) {
+    const keys = new Set();
+    for (const id of ids) {
+        keys.add(`node-${id}`);
+        keys.add(`node-${id}-html-layer`);
+        keys.add(`link-${id}`);
+    }
+    return keys;
+}
+/**
+ * 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).
+ */
+function filterTreeByIds(root, ids) {
+    const keys = selectionKeys(ids);
+    return prune(root, keys);
+}
+function prune(vnode, keys) {
+    var _a;
+    const children = (_a = vnode.children) !== null && _a !== void 0 ? _a : [];
+    const kept = [];
+    for (const child of children) {
+        if (!child || typeof child !== 'object')
+            continue;
+        const key = child.key;
+        const identified = typeof key === 'string' && IDENTIFIED.test(key);
+        if (identified) {
+            // An identified object is all-or-nothing: in scope → keep the whole subtree.
+            if (keys.has(key))
+                kept.push(child);
+            continue;
+        }
+        // A container: keep it and recurse. (Containers are layers and <defs>; a kept
+        // node may reference a def, so defs are never pruned.)
+        kept.push(prune(child, keys));
+    }
+    return Object.assign(Object.assign({}, vnode), { children: kept });
+}
+//# sourceMappingURL=scope.js.map

package/src/libs/renderer/src/export/style-flattener.d.ts

@@ -0,0 +1,23 @@
+import type { Theme } from '../types/theme.types';
+/**
+ * Replace every `var(--grafloria-*)` in a declaration with its literal theme value.
+ * Returns `undefined` when a referenced variable has no value and no fallback —
+ * the declaration is then DROPPED rather than emitted as an unresolvable
+ * reference, and the caller records a warning.
+ */
+export declare function resolveCssVars(value: string, vars: Record<string, string>): string | undefined;
+/**
+ * Resolves an element's class list to the concrete presentation attributes the
+ * renderer's stylesheet would have painted, for THIS theme.
+ */
+export type ClassStyleResolver = (classList: string[]) => Record<string, string>;
+/**
+ * Build the resolver for a theme. Compiles BASE_STYLE_RULES once (var refs
+ * resolved against the theme's variable values), then matches class lists
+ * against it.
+ *
+ * @param theme the theme whose `--grafloria-*` values get baked in
+ * @param warnings collector — a declaration whose variable cannot be resolved is
+ *        dropped and reported here rather than silently emitting `var(--…)`.
+ */
+export declare function createClassStyleResolver(theme: Theme, warnings?: string[]): ClassStyleResolver;

package/src/libs/renderer/src/export/style-flattener.js

@@ -0,0 +1,144 @@
+"use strict";
+// Standalone-SVG style flattening: RESOLVE the CSS-variable cascade instead of
+// referencing it.
+//
+// THE PROBLEM
+// -----------
+// The live renderer paints the THEME layer from a stylesheet written entirely in
+// custom properties:
+//
+//   [data-grafloria-instance] .diagram-node { fill: var(--grafloria-node-fill); … }
+//   [data-grafloria-instance="grafloria-3"]     { --grafloria-node-fill: #ffffff; … }
+//
+// A node VNode in CSS mode therefore carries NO fill at all — just
+// `class="diagram-node"`. That is exactly right on a live page and useless in a
+// file: an SVG opened in Inkscape, embedded in an email, or handed to a
+// rasterizer (resvg / librsvg / cairosvg — none of which implement CSS custom
+// properties) has neither our stylesheet nor our variables. It would render with
+// UA defaults: black fill, no stroke, 16px serif labels.
+//
+// THE DECISION — flatten, don't ship a <style> block
+// --------------------------------------------------
+// We resolve the cascade to CONCRETE presentation attributes and emit ZERO
+// `var(--…)` and zero `<style>` rules. The alternative (inline the shared rules
+// plus a materialised variable block into a `<style>` inside the SVG) is
+// self-contained in the "no network fetch" sense, but it still requires the
+// consumer to implement CSS selectors AND custom properties. Most non-browser
+// SVG consumers implement neither. Flattening is the only form that renders
+// identically everywhere, so it is what `export` produces — and the export tests
+// assert the output contains no `var(--`.
+//
+// HOW THE CASCADE IS REPRODUCED
+// -----------------------------
+// This is a mini CSS engine over exactly ONE stylesheet — our own
+// {@link BASE_STYLE_RULES} — whose selectors are all simple compound class
+// selectors (`.diagram-node`, `.diagram-node.selected`, `.port-input.port-highlighted`).
+// So the whole cascade is: match by class set, order by (specificity = number of
+// classes, then source order). BASE_STYLE_RULES is authored in ascending
+// precedence, so source order already encodes `selected > highlighted > hovered`
+// at equal specificity — the same tie-break the browser applies.
+//
+// The one subtlety that MATTERS is CSS priority order:
+//
+//     presentation attribute  <  author stylesheet rule  <  inline style
+//
+// A presentation attribute (`fill="#e8f5e9"`) LOSES to any author rule. So the
+// flattened rule values must OVERWRITE prop-derived presentation attributes, and
+// an element's inline `style` string must beat both — which it does for free,
+// because it stays an inline `style` attribute in the output. Reproducing that
+// order here is what keeps the exported picture identical to the live one.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCssVars = resolveCssVars;
+exports.createClassStyleResolver = createClassStyleResolver;
+const theme_css_1 = require("../themes/theme-css");
+const theme_vars_1 = require("../themes/theme-vars");
+/**
+ * CSS properties the flattener is allowed to materialise onto an element.
+ *
+ * Everything in BASE_STYLE_RULES is a paint value except `cursor`, which has no
+ * meaning in a static picture. Anything outside this set is dropped rather than
+ * emitted as a bogus attribute.
+ */
+const PAINTABLE_PROPS = new Set([
+    'fill',
+    'stroke',
+    'stroke-width',
+    'stroke-dasharray',
+    'opacity',
+    'fill-opacity',
+    'stroke-opacity',
+    'font-family',
+    'font-size',
+    'font-weight',
+    'color',
+]);
+/** `.diagram-node.selected` → ['diagram-node', 'selected'] */
+function selectorClasses(selector) {
+    return selector
+        .split('.')
+        .map(part => part.trim())
+        .filter(Boolean);
+}
+const VAR_REF = /var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,\s*([^)]*))?\)/g;
+/**
+ * Replace every `var(--grafloria-*)` in a declaration with its literal theme value.
+ * Returns `undefined` when a referenced variable has no value and no fallback —
+ * the declaration is then DROPPED rather than emitted as an unresolvable
+ * reference, and the caller records a warning.
+ */
+function resolveCssVars(value, vars) {
+    let unresolved = false;
+    const out = value.replace(VAR_REF, (_all, name, fallback) => {
+        const resolved = vars[name];
+        if (resolved !== undefined)
+            return resolved;
+        if (fallback !== undefined && fallback.trim() !== '')
+            return fallback.trim();
+        unresolved = true;
+        return '';
+    });
+    return unresolved ? undefined : out.trim();
+}
+/**
+ * Build the resolver for a theme. Compiles BASE_STYLE_RULES once (var refs
+ * resolved against the theme's variable values), then matches class lists
+ * against it.
+ *
+ * @param theme the theme whose `--grafloria-*` values get baked in
+ * @param warnings collector — a declaration whose variable cannot be resolved is
+ *        dropped and reported here rather than silently emitting `var(--…)`.
+ */
+function createClassStyleResolver(theme, warnings = []) {
+    const vars = (0, theme_vars_1.resolveThemeVars)(theme);
+    const compiled = theme_css_1.BASE_STYLE_RULES.map((rule, order) => {
+        const decls = {};
+        for (const [prop, raw] of Object.entries(rule.decls)) {
+            if (!PAINTABLE_PROPS.has(prop))
+                continue; // cursor & friends: not a picture
+            const resolved = resolveCssVars(raw, vars);
+            if (resolved === undefined) {
+                warnings.push(`unresolved CSS variable in "${rule.selector} { ${prop}: ${raw} }" — declaration dropped`);
+                continue;
+            }
+            decls[prop] = resolved;
+        }
+        const classes = selectorClasses(rule.selector);
+        return { classes, specificity: classes.length, order, decls };
+    });
+    // Stable cascade order: lower specificity first, then source order. Applying in
+    // this order into a map means the LAST write wins — i.e. the browser's winner.
+    compiled.sort((a, b) => a.specificity - b.specificity || a.order - b.order);
+    return (classList) => {
+        if (classList.length === 0)
+            return {};
+        const have = new Set(classList);
+        const out = {};
+        for (const rule of compiled) {
+            if (!rule.classes.every(c => have.has(c)))
+                continue;
+            Object.assign(out, rule.decls);
+        }
+        return out;
+    };
+}
+//# sourceMappingURL=style-flattener.js.map

package/src/libs/renderer/src/export/svg-export.d.ts

@@ -0,0 +1,123 @@
+import type { VNode } from '../types/vnode.types';
+import type { Theme } from '../types/theme.types';
+import type { Rectangle } from '../types/geometry.types';
+import { type ForeignObjectMode } from './vnode-serializer';
+import { type CustomNodeCapture, type HtmlFallbackMode } from './custom-nodes';
+import { type FontSource } from './assets';
+import type { DiagramDocumentEnvelope } from '@grafloria/engine';
+export declare const SVG_XMLNS = "http://www.w3.org/2000/svg";
+/** The XML prolog. Required by strict XML parsers and by most SVG→PDF toolchains. */
+export declare const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>";
+export interface SvgExportOptions {
+    /**
+     * The theme whose values get baked into the output. MUST be the theme the tree
+     * was rendered with — it is the source of every `--grafloria-*` value the live
+     * stylesheet would have supplied. Defaults to LIGHT_THEME.
+     */
+    theme?: Theme;
+    /**
+     * Multiplies the SVG's `width`/`height` (its intrinsic size) while the
+     * `viewBox` stays put — so the picture is unchanged, just rendered larger. This
+     * is what makes a 2x PNG a 2x PNG.
+     */
+    scale?: number;
+    /** Painted as a full-viewBox rect behind everything. Default: transparent. */
+    backgroundColor?: string;
+    /** What to do with `<foreignObject>` subtrees. Default `'serialize'`. */
+    foreignObject?: ForeignObjectMode;
+    /** Supply the live HTML inside a foreignObject (browser-side callers). */
+    captureForeignObject?: (vnode: VNode) => string | undefined;
+    /**
+     * CUSTOM-NODE CONTENT — the widgets an HTML-layer node paints, which the VNode tree
+     * does not contain and cannot contain (the renderer emits an empty `<g>` for those
+     * nodes; the page paints a raw HTML host that is a SIBLING of the SVG).
+     *
+     * Plain data, captured by whoever has the DOM — `createDiagram` does it for you.
+     * Passing it keeps this function pure: no element ever reaches here.
+     * See `capture-host.ts` for the capture and `custom-nodes.ts` for the placement.
+     */
+    customNodes?: readonly CustomNodeCapture[];
+    /**
+     * What to do with a custom node that could only be captured as HTML. Default
+     * `'foreignObject'`. Whatever you choose, it is REPORTED in `warnings` — a widget
+     * that cannot make it into the file faithfully never does so quietly.
+     */
+    htmlFallback?: HtmlFallbackMode;
+    /**
+     * CSS emitted verbatim into a `<style>` inside `<defs>`. THE font seam: pass an
+     * `@font-face` whose `src` is a `data:` URI and the exported file carries its
+     * own glyphs. We do not fetch, subset or embed fonts for you — that is a
+     * deliberate boundary, not an oversight.
+     */
+    embedFontCss?: string;
+    /**
+     * Fonts to EMBED as base64 `@font-face` rules — the built form of the `embedFontCss` seam.
+     * Both are honoured; `embedFontCss` is appended after these.
+     */
+    embedFonts?: FontSource[];
+    /**
+     * Fit the viewBox to the CONTENT — the union box of everything the tree actually
+     * draws (labels, ports and arrowheads included), not the root's own viewBox.
+     *
+     * The root `<svg>`'s viewBox is the live VIEWPORT: it is scoped to what the user
+     * is looking at, and at any zoom but 1 it is not even the same rectangle. A file
+     * wants the diagram, so this defaults to ON. Turn it off to keep the tree's own
+     * viewBox verbatim (that is what a pagination tile does — it has already chosen
+     * its rectangle).
+     */
+    fitToContent?: boolean;
+    /** Margin around the fitted content box, in world units. Default 20. */
+    padding?: number;
+    /**
+     * Export ONLY these node/link ids. The tree is pruned to them (not merely cropped
+     * — an un-selected node outside the viewBox is invisible but its markup, and its
+     * labels, would still be in the bytes) and the box is fitted around them.
+     */
+    includeIds?: Iterable<string>;
+    /** Use this exact viewBox and fit nothing. Wins over `fitToContent`. */
+    viewBox?: Rectangle;
+    /**
+     * Cap on the output's intrinsic size, per side, in px. Default 4000. The scale is
+     * REDUCED to fit rather than the picture being cropped — see `clampOutputSize`.
+     */
+    maxSize?: number;
+    /** Floor on the output's intrinsic size, per side, in px. Default 1. */
+    minSize?: number;
+    /** Prepend the `<?xml …?>` prolog. Default false (an inline `<svg>` must not have one). */
+    xmlDeclaration?: boolean;
+    /**
+     * Embed this document envelope in the SVG's `<metadata>`, making the exported file
+     * an EDITABLE artifact: re-import it and get the diagram back, losslessly.
+     *
+     * Takes the envelope rather than building one, because an envelope carries a
+     * `createdAt` — and minting a timestamp in here would make the export
+     * non-deterministic, which is a guarantee this module does not get to break.
+     * `SVGRenderer.export` builds it for you (see `ExportOptions.embedModel`).
+     */
+    embedModel?: DiagramDocumentEnvelope;
+}
+export interface SvgExportResult {
+    /** The standalone SVG document. */
+    svg: string;
+    /** Intrinsic width in px (viewBox width × the CLAMPED scale). */
+    width: number;
+    /** Intrinsic height in px. */
+    height: number;
+    /** The world rectangle the document actually covers — what pagination and PDF page off. */
+    viewBox: ViewBox;
+    /** Fidelity caveats hit during this export (foreignObject, unresolved vars, size clamp, …). */
+    warnings: string[];
+}
+interface ViewBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Serialize a rendered VNode tree to a standalone SVG string.
+ *
+ * @param root the root `<svg>` VNode from `SVGRenderer.render(viewport, zoom)`
+ */
+export declare function exportSvg(root: VNode, options?: SvgExportOptions): SvgExportResult;
+export {};

package/src/libs/renderer/src/export/svg-export.js

@@ -0,0 +1,178 @@
+"use strict";
+// The standalone SVG document: a pure function from the renderer's VNode tree to
+// a self-contained, styles-inlined SVG string.
+//
+// GUARANTEES (each one is pinned by a test in svg-export.spec.ts):
+//   • no `var(--…)`            — the theme cascade is RESOLVED, not referenced
+//   • no external references   — no http(s), no `<image href>`, no @import, no
+//                                webfont URL: every `url(#…)` points inside the
+//                                document's own `<defs>`
+//   • deterministic            — same tree + same options ⇒ byte-identical string,
+//                                every time, in any process
+//   • zero DOM                 — plain Node, a worker, an SSR pass; no `document`
+//
+// WHAT IS NOT GUARANTEED (be blunt — see README of the card):
+//   • FONTS are declared (`font-family: …`), not embedded. Glyphs still come from
+//     the machine that renders the file. Pass `embedFontCss` with a @font-face
+//     whose src is a data: URI to make the file truly self-contained; we do NOT
+//     subset or convert text to paths.
+//   • CSS ANIMATIONS are not exported. A static picture has no time axis, so an
+//     animated link exports as its base (un-dashed) stroke.
+//   • foreignObject content is host-mounted DOM, not VNode — see the serializer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XML_DECLARATION = exports.SVG_XMLNS = void 0;
+exports.exportSvg = exportSvg;
+const default_light_theme_1 = require("../themes/default-light-theme");
+const style_flattener_1 = require("./style-flattener");
+const vnode_serializer_1 = require("./vnode-serializer");
+const bounds_1 = require("./bounds");
+const scope_1 = require("./scope");
+const custom_nodes_1 = require("./custom-nodes");
+const round_trip_1 = require("./round-trip");
+const assets_1 = require("./assets");
+exports.SVG_XMLNS = 'http://www.w3.org/2000/svg';
+/** The XML prolog. Required by strict XML parsers and by most SVG→PDF toolchains. */
+exports.XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>';
+/** Read the root `<svg>` VNode's viewBox — or synthesize one from width/height. */
+function readViewBox(root) {
+    var _a, _b, _c, _d, _e;
+    const raw = (_a = root.props) === null || _a === void 0 ? void 0 : _a['viewBox'];
+    if (typeof raw === 'string') {
+        const parts = raw.trim().split(/[\s,]+/).map(Number);
+        if (parts.length === 4 && parts.every(n => Number.isFinite(n))) {
+            return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+        }
+    }
+    // The empty-diagram root carries width/height instead of a viewBox.
+    const width = Number((_c = (_b = root.props) === null || _b === void 0 ? void 0 : _b['width']) !== null && _c !== void 0 ? _c : 0);
+    const height = Number((_e = (_d = root.props) === null || _d === void 0 ? void 0 : _d['height']) !== null && _e !== void 0 ? _e : 0);
+    return { x: 0, y: 0, width: Number.isFinite(width) ? width : 0, height: Number.isFinite(height) ? height : 0 };
+}
+/**
+ * Serialize a rendered VNode tree to a standalone SVG string.
+ *
+ * @param root the root `<svg>` VNode from `SVGRenderer.render(viewport, zoom)`
+ */
+function exportSvg(root, options = {}) {
+    var _a, _b, _c, _d, _e, _f;
+    const theme = (_a = options.theme) !== null && _a !== void 0 ? _a : default_light_theme_1.LIGHT_THEME;
+    const requestedScale = options.scale && options.scale > 0 ? options.scale : 1;
+    const warnings = [];
+    // (1) SCOPE — prune before anything else, so the box is fitted to what survives.
+    const tree = options.includeIds !== undefined ? (0, scope_1.filterTreeByIds)(root, options.includeIds) : root;
+    // Custom-node content is scoped by the SAME ids. A capture is keyed by node id, so
+    // `includeIds` prunes widgets exactly as it prunes nodes.
+    const captures = (0, custom_nodes_1.filterCaptures)((_b = options.customNodes) !== null && _b !== void 0 ? _b : [], options.includeIds);
+    const custom = (0, custom_nodes_1.customNodeVNodes)(captures, { htmlFallback: options.htmlFallback });
+    warnings.push(...custom.warnings);
+    // (2) THE BOX. Priority: an explicit viewBox, else the content fit (the default —
+    // the root's own viewBox is the live viewport, which is not what a file wants),
+    // else the tree's viewBox verbatim.
+    const viewBox = resolveViewBox(tree, options, warnings, captures);
+    // (3) SIZE, capped.
+    //
+    // NO CAP BY DEFAULT HERE. The cap exists to stop a canvas request the browser will
+    // silently refuse — and an SVG allocates no canvas. It is a VECTOR document: a
+    // 9000px-wide intrinsic size costs nothing and still renders sharp at any size, so
+    // clamping it would shrink a perfectly good file for no reason.
+    //
+    // The raster path (`SVGRenderer.export('png'|…)`) therefore passes the real cap in
+    // explicitly. A caller who wants an SVG capped too can pass `maxSize`.
+    const clamped = (0, bounds_1.clampOutputSize)(viewBox.width, viewBox.height, requestedScale, (_c = options.maxSize) !== null && _c !== void 0 ? _c : Infinity, (_d = options.minSize) !== null && _d !== void 0 ? _d : 1);
+    if (clamped.warning)
+        warnings.push(clamped.warning);
+    const width = clamped.width;
+    const height = clamped.height;
+    const classStyles = (0, style_flattener_1.createClassStyleResolver)(theme, warnings);
+    // Defs the serializer had to synthesize (blur filters). Filled during the walk,
+    // emitted after it — hence children are serialized BEFORE the document is composed.
+    const extraDefs = new Map();
+    const serialize = (child) => (0, vnode_serializer_1.serializeVNode)(child, {
+        classStyles,
+        foreignObject: options.foreignObject,
+        captureForeignObject: options.captureForeignObject,
+        warnings,
+        extraDefs,
+    });
+    // Custom nodes are serialized LAST, so they paint above the diagram — the same
+    // stacking the live page has, where `.grafloria-html-layer` sits on top of the SVG layer.
+    const children = ((_e = tree.children) !== null && _e !== void 0 ? _e : [])
+        .filter(child => child !== null && child !== undefined)
+        .map(serialize)
+        .join('') + custom.nodes.map(serialize).join('');
+    const background = options.backgroundColor !== undefined
+        ? `<rect x="${viewBox.x}" y="${viewBox.y}" width="${viewBox.width}" height="${viewBox.height}" ` +
+            `fill="${(0, vnode_serializer_1.escapeAttr)(options.backgroundColor)}"/>`
+        : '';
+    // The font seam. CDATA-wrapped so a `>` or `&` in the caller's CSS cannot
+    // break the document.
+    const embedded = ((_f = options.embedFonts) === null || _f === void 0 ? void 0 : _f.length) ? (0, assets_1.fontFaceCss)(options.embedFonts) : '';
+    const fontCss = [embedded, options.embedFontCss].filter(Boolean).join('\n');
+    const fontDefs = fontCss ? `<style type="text/css"><![CDATA[\n${fontCss}\n]]></style>` : '';
+    const synthesized = Array.from(extraDefs.values()).join('');
+    const defs = fontDefs || synthesized ? `<defs>${fontDefs}${synthesized}</defs>` : '';
+    const prolog = options.xmlDeclaration ? exports.XML_DECLARATION : '';
+    let svg = prolog +
+        `<svg xmlns="${exports.SVG_XMLNS}" ` +
+        `viewBox="${viewBox.x} ${viewBox.y} ${viewBox.width} ${viewBox.height}" ` +
+        `width="${width}" height="${height}" class="grafloria-diagram">` +
+        defs +
+        background +
+        children +
+        `</svg>`;
+    // The source model, carried inside the picture (Card 7). Injected AFTER composition
+    // so it cannot disturb the serializer's byte layout when it is absent.
+    if (options.embedModel) {
+        svg = (0, round_trip_1.embedModelInSvg)(svg, options.embedModel);
+    }
+    return { svg, width, height, viewBox, warnings };
+}
+/**
+ * The rectangle the file covers.
+ *
+ * DEFAULT: fit the content. The root `<svg>`'s own viewBox is the LIVE VIEWPORT —
+ * scoped to what the user happens to be looking at, and at any zoom ≠ 1 not even the
+ * same rectangle. Exporting it is how a "download PNG" button produces a picture of
+ * the user's scroll position instead of a picture of the diagram.
+ */
+function resolveViewBox(tree, options, warnings, captures = []) {
+    var _a, _b;
+    if (options.viewBox)
+        return options.viewBox;
+    if (options.fitToContent !== false) {
+        const drawn = (0, bounds_1.vnodeBounds)(tree, {
+            includeIds: options.includeIds ? new Set(options.includeIds) : undefined,
+        });
+        // The custom nodes' own rects join the fit. Two reasons this is not optional:
+        // a lifted chart hides its geometry behind a `<g transform>` and a foreignObject's
+        // content is opaque, so `vnodeBounds` under-measures a board — and on an ALL-custom
+        // dashboard it measures nothing at all and the file comes out a 40px square.
+        const content = unionRects(drawn, (0, custom_nodes_1.customNodeBounds)(captures));
+        if (content)
+            return (0, bounds_1.padRect)(content, (_a = options.padding) !== null && _a !== void 0 ? _a : 20);
+        // Nothing is drawn. A zero-area document is rejected by rasterizers, so emit a
+        // small valid square instead of a degenerate one.
+        if (options.includeIds !== undefined) {
+            warnings.push('nothing to export: no element matched the requested ids');
+        }
+        const side = Math.max(1, ((_b = options.padding) !== null && _b !== void 0 ? _b : 20) * 2);
+        return { x: 0, y: 0, width: side, height: side };
+    }
+    return readViewBox(tree);
+}
+/** Union of two optional rectangles — either, both, or neither. */
+function unionRects(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const x = Math.min(a.x, b.x);
+    const y = Math.min(a.y, b.y);
+    return {
+        x,
+        y,
+        width: Math.max(a.x + a.width, b.x + b.width) - x,
+        height: Math.max(a.y + a.height, b.y + b.height) - y,
+    };
+}
+//# sourceMappingURL=svg-export.js.map

package/src/libs/renderer/src/export/vnode-serializer.d.ts

@@ -0,0 +1,75 @@
+import type { VNode } from '../types/vnode.types';
+import type { ClassStyleResolver } from './style-flattener';
+/** What the serializer does with a `<foreignObject>` (HTML-in-SVG) subtree. */
+export type ForeignObjectMode = 'serialize' | 'placeholder' | 'omit';
+/**
+ * WHO is going to read this string — the only axis on which the two callers differ.
+ *
+ *   'file' (default)  A standalone `.svg` a rasterizer / Inkscape / an email client
+ *                     will read. It has no stylesheet, so the cascade is FLATTENED
+ *                     into presentation attributes; live-pipeline attributes minted
+ *                     from process-global counters are DROPPED (they mean nothing in
+ *                     a file and would destroy determinism); CSS `filter: blur()` is
+ *                     translated into a real `<filter>` def.
+ *
+ *   'dom'             An SSR snapshot the client's VNodePatcher will ADOPT. Here the
+ *                     string must describe exactly the DOM the patcher would have
+ *                     built from the same tree — otherwise hydration sees a different
+ *                     attribute set, tears the node down and rebuilds it, and the
+ *                     diagram flashes. So: `style` is kept verbatim, nothing is
+ *                     dropped, no cascade flattening, and the patcher's `data-vnode-key`
+ *                     mirror is reproduced.
+ *
+ * ONE traversal serves both. Keeping two would have meant two copies of the
+ * prop→attribute rules, and the moment one learned a new verbatim attribute and the
+ * other did not, exported files and hydrated pages would quietly disagree about what
+ * the diagram looks like.
+ */
+export type SerializeFidelity = 'file' | 'dom';
+export interface SerializeOptions {
+    /** Who reads the output. Default `'file'`. See {@link SerializeFidelity}. */
+    fidelity?: SerializeFidelity;
+    /** Stamp `xmlns` on the root element (needed for a standalone `.svg` file). */
+    standalone?: boolean;
+    /**
+     * Resolves an element's classes to the presentation attributes the renderer's
+     * stylesheet would have painted. Omit for a tree rendered in programmatic mode
+     * (there is no stylesheet there — every value is already on the element).
+     * Ignored under `fidelity: 'dom'` — the client has the real stylesheet.
+     */
+    classStyles?: ClassStyleResolver;
+    /** How to handle `<foreignObject>` subtrees. Default `'serialize'`. */
+    foreignObject?: ForeignObjectMode;
+    /**
+     * Faithful foreignObject export. The VNode tree does NOT contain the HTML a
+     * framework mounted into a foreignObject (the patcher treats those subtrees as
+     * opaque and never touches their children) — so a headless serializer CANNOT
+     * know what is in there. A browser-side caller that has the live DOM can hand
+     * the markup back through this hook (e.g. `el.outerHTML` of the mounted
+     * content); it is emitted verbatim inside the `<foreignObject>`.
+     */
+    captureForeignObject?: (vnode: VNode) => string | undefined;
+    /** Collector for fidelity caveats hit while serializing. */
+    warnings?: string[];
+    /** Collector for `<defs>` elements the serializer had to synthesize (blur filters). */
+    extraDefs?: Map<string, string>;
+    /**
+     * This subtree is XHTML, not SVG (i.e. it is inside a `<foreignObject>`). Set
+     * automatically when recursing into one — HTML has no presentation attributes,
+     * so there the `style` attribute is kept verbatim and no class flattening is
+     * attempted (the host's own CSS, which we do not own, styles that content).
+     */
+    html?: boolean;
+}
+/** XML-escape an attribute value. */
+export declare function escapeAttr(value: string): string;
+/** XML-escape text content. */
+export declare function escapeText(value: string): string;
+/**
+ * Serialize ONE VNode (and its subtree) to an XML string.
+ *
+ * Pure: same VNode in, same string out — no ambient state, no DOM, no clock, no
+ * randomness. Attribute order follows prop insertion order, which the renderer
+ * builds deterministically, so two calls on the same tree are byte-identical.
+ */
+export declare function serializeVNode(vnode: VNode, options?: SerializeOptions): string;