@grafloria/element 0.3.17 → 0.3.19

package/src/libs/renderer/src/export/vnode-serializer.js

@@ -0,0 +1,344 @@
+"use strict";
+// VNode → XML string. The headless sibling of `vnode/patch.ts`.
+//
+// The patcher turns a VNode tree into live DOM; this turns the SAME tree into a
+// string, with ZERO DOM: no `document`, no `XMLSerializer`, no `innerHTML`. It
+// runs in plain Node, in a worker, in an SSR pass. That is the whole point of the
+// card: one VNode contract, two consumers, identical picture.
+//
+// It shares THE prop → attribute mapping with the patcher (`attrNameForProp`,
+// `serializeStyle`) so the two cannot drift.
+//
+// Three things this does that the patcher does not:
+//
+//   1. FLATTENS the stylesheet. The patcher can rely on the injected
+//      `var(--grafloria-*)` stylesheet being in the document; a file cannot. A
+//      {@link ClassStyleResolver} turns each element's class list into concrete
+//      presentation attributes, inserted at the correct point of the CSS priority
+//      order (see below).
+//
+//   2. DROPS live-pipeline-only attributes. `data-grafloria-instance` (the CSS scope)
+//      and `container-id` (the foreignObject component-injection handle) are both
+//      derived from PROCESS-GLOBAL COUNTERS. They mean nothing in a file, and
+//      keeping them would make the output depend on how many renderers/nodes the
+//      process happened to create first — i.e. it would destroy determinism.
+//
+//   3. TRANSLATES `filter: blur(Npx)` into a real `<filter>` def. The renderer's
+//      node shadow uses the CSS filter shorthand, which browsers accept on SVG
+//      but standalone rasterizers (resvg / librsvg / Inkscape) do not. Emitting an
+//      feGaussianBlur def keeps shadows in the exported picture.
+//
+// CSS PRIORITY ORDER — reproduced exactly, then COLLAPSED:
+//     presentation attribute  <  author stylesheet rule  <  inline style
+// The winner of that order is emitted as a presentation attribute and the `style`
+// attribute is dropped, so every property appears exactly once, in the form the
+// widest range of SVG consumers understands. (HTML inside a foreignObject is the
+// exception — HTML has no presentation attributes, so there the `style` attribute
+// is kept verbatim.)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeAttr = escapeAttr;
+exports.escapeText = escapeText;
+exports.serializeVNode = serializeVNode;
+const patch_1 = require("../vnode/patch");
+/**
+ * Props that address the LIVE pipeline, not the picture. Both are minted from
+ * process-global counters, so serializing them would make byte-identical output
+ * impossible across processes.
+ */
+const DROPPED_PROPS = new Set(['containerId', 'data-grafloria-instance']);
+/** `blur(4px)` / `blur(4)` → the radius in px. */
+const CSS_BLUR = /^blur\(\s*([\d.]+)(?:px)?\s*\)$/;
+/** XML-escape an attribute value. */
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/** XML-escape text content. */
+function escapeText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** Split a `class` string into its tokens. */
+function classList(className) {
+    if (typeof className !== 'string' || className.trim() === '')
+        return [];
+    return className.trim().split(/\s+/);
+}
+/**
+ * Turn `filter: blur(4px)` into a real SVG filter def and return the `url(#…)`
+ * reference. CSS `blur(r)` is a Gaussian blur of std-deviation r/2.
+ *
+ * The def id is derived from the radius alone → the same radius always yields the
+ * same id (determinism), and N shadows share ONE def.
+ */
+function translateBlurFilter(value, extraDefs) {
+    const match = CSS_BLUR.exec(value.trim());
+    if (!match)
+        return value; // not a blur shorthand — pass through untouched
+    const radius = Number(match[1]);
+    const id = `grafloria-blur-${String(radius).replace('.', '_')}`;
+    if (!extraDefs.has(id)) {
+        extraDefs.set(id, `<filter id="${id}" x="-50%" y="-50%" width="200%" height="200%">` +
+            `<feGaussianBlur stdDeviation="${radius / 2}"/>` +
+            `</filter>`);
+    }
+    return `url(#${id})`;
+}
+/**
+ * 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.
+ */
+function serializeVNode(vnode, options = {}) {
+    var _a, _b, _c, _d;
+    const warnings = (_a = options.warnings) !== null && _a !== void 0 ? _a : [];
+    const extraDefs = (_b = options.extraDefs) !== null && _b !== void 0 ? _b : new Map();
+    const foMode = (_c = options.foreignObject) !== null && _c !== void 0 ? _c : 'serialize';
+    const dom = options.fidelity === 'dom';
+    if (vnode.type === 'foreignObject') {
+        return serializeForeignObject(vnode, Object.assign(Object.assign({}, options), { warnings, extraDefs }), foMode);
+    }
+    const { attrs, text, raw } = elementAttrs(vnode, options, extraDefs, options.html === true);
+    const children = ((_d = vnode.children) !== null && _d !== void 0 ? _d : []).filter(isRenderable);
+    // A standalone file needs the namespace declared; an SSR snapshot needs it too,
+    // because the client parses the markup before the patcher adopts it.
+    if (options.standalone && !attrs.has('xmlns') && !options.html) {
+        attrs.set('xmlns', patch_1.SVG_NS);
+    }
+    // Children are serialized as SVG unless we have crossed into a foreignObject.
+    // `standalone` is a ROOT-only concern — never inherit it.
+    const childOpts = Object.assign(Object.assign({}, options), { warnings, extraDefs, standalone: false });
+    const open = `<${vnode.type}${renderAttrs(attrs)}`;
+    // `textContent` OWNS the element's content (the patcher has the same rule):
+    // elements that render through the prop never also declare children.
+    if (text !== undefined) {
+        return `${open}>${escapeText(text)}</${vnode.type}>`;
+    }
+    // Markup, emitted verbatim (see `innerHTML` above). Escaping it would print the
+    // tags instead of rendering them.
+    if (raw !== undefined) {
+        return `${open}>${raw}</${vnode.type}>`;
+    }
+    if (children.length === 0) {
+        // Under 'dom' fidelity always write the long form: the patcher builds
+        // `<g></g>`, and the snapshot the client parses should read the same.
+        return dom ? `${open}></${vnode.type}>` : `${open}/>`;
+    }
+    const inner = children
+        .map(child => isVNodeChild(child)
+        ? serializeVNode(child, childOpts)
+        : escapeText(String(child)))
+        .join('');
+    return `${open}>${inner}</${vnode.type}>`;
+}
+/**
+ * foreignObject: the honest story.
+ *
+ * The VNode tree carries only what the RENDERER declared — for component nodes
+ * that is an empty XHTML `<div>` shell whose real content is mounted into the
+ * live DOM by the host framework, and which the patcher deliberately never
+ * touches again. Headless, that content simply does not exist.
+ *
+ *   'serialize'   (default) emit the `<foreignObject>` and whatever children the
+ *                 VNode declares. Faithful to the contract, and lossless for
+ *                 trees that DO declare HTML children. Warns, because (a) the
+ *                 host-mounted content is not in the tree and (b) essentially no
+ *                 non-browser SVG rasterizer implements foreignObject at all.
+ *   'placeholder' replace it with a dashed rect of the same geometry, so a server
+ *                 thumbnail shows a box where the component is instead of a hole.
+ *   'omit'        drop it.
+ *
+ * `captureForeignObject` is the escape hatch: a caller WITH a live DOM can hand
+ * back the mounted markup and get a faithful export.
+ */
+function serializeForeignObject(vnode, options, mode) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const { warnings } = options;
+    const props = (_a = vnode.props) !== null && _a !== void 0 ? _a : {};
+    if (mode === 'omit') {
+        warnings.push('foreignObject dropped (foreignObject: "omit")');
+        return '';
+    }
+    if (mode === 'placeholder') {
+        warnings.push('foreignObject replaced by a placeholder rect (foreignObject: "placeholder")');
+        return (`<rect x="${(_b = props.x) !== null && _b !== void 0 ? _b : 0}" y="${(_c = props.y) !== null && _c !== void 0 ? _c : 0}" ` +
+            `width="${(_d = props.width) !== null && _d !== void 0 ? _d : 0}" height="${(_e = props.height) !== null && _e !== void 0 ? _e : 0}" ` +
+            `fill="none" stroke="#94a3b8" stroke-width="1" stroke-dasharray="4,4" ` +
+            `class="grafloria-foreign-placeholder"/>`);
+    }
+    // The <foreignObject> element itself is SVG; its CHILDREN are HTML.
+    const { attrs } = elementAttrs(vnode, options, options.extraDefs, false);
+    const open = `<foreignObject${renderAttrs(attrs)}`;
+    const captured = (_f = options.captureForeignObject) === null || _f === void 0 ? void 0 : _f.call(options, vnode);
+    if (captured !== undefined) {
+        return `${open}>${captured}</foreignObject>`;
+    }
+    warnings.push('foreignObject serialized from the VNode tree only — host-mounted HTML/components are NOT in the tree ' +
+        '(pass captureForeignObject to supply it). Note that most non-browser SVG rasterizers ignore foreignObject entirely.');
+    const children = ((_g = vnode.children) !== null && _g !== void 0 ? _g : []).filter(isRenderable);
+    if (children.length === 0)
+        return `${open}/>`;
+    // Children are XHTML from here down.
+    const htmlOptions = Object.assign(Object.assign({}, options), { html: true });
+    const inner = children
+        .map(child => isVNodeChild(child) ? serializeVNode(child, htmlOptions) : escapeText(String(child)))
+        .join('');
+    return `${open}>${inner}</foreignObject>`;
+}
+/**
+ * Declarations that only exist in CSS. They have no presentation-attribute
+ * equivalent, and none of them means anything in a still picture.
+ */
+const CSS_ONLY_DECLS = new Set([
+    'transition',
+    'cursor',
+    'will-change',
+    'animation',
+    'animation-name',
+    'animation-duration',
+    'animation-direction',
+    'animation-iteration-count',
+    'animation-timing-function',
+    'user-select',
+    'transform-origin',
+]);
+/** `'fill: red; stroke-width: 2'` (or the object form) → `{ fill: 'red', 'stroke-width': '2' }`. */
+function parseStyleDecls(style) {
+    const out = {};
+    const serialized = (0, patch_1.serializeStyle)(style); // handles BOTH forms the renderer emits
+    if (!serialized)
+        return out;
+    for (const part of serialized.split(';')) {
+        const colon = part.indexOf(':');
+        if (colon < 0)
+            continue;
+        const prop = part.slice(0, colon).trim();
+        const value = part.slice(colon + 1).trim();
+        if (prop && value)
+            out[prop] = value;
+    }
+    return out;
+}
+/**
+ * Build an element's FULLY RESOLVED attribute map.
+ *
+ * The cascade is applied in CSS priority order …
+ *
+ *   1. props            → presentation attributes (lowest)
+ *   2. class rules      → OVERWRITE them (an author rule beats a presentation attr)
+ *   3. inline `style`   → OVERWRITES both (highest)
+ *
+ * … and then every winner is emitted as a PRESENTATION ATTRIBUTE, with no `style`
+ * attribute left behind.
+ *
+ * WHY collapse to attributes rather than keep the winning value in a `style=`:
+ * a standalone file is read by things that are not browsers, and presentation
+ * attributes are the most universally understood form there is. Leaving
+ * `fill="#ffffff" style="fill: #123456"` on an element would render correctly in
+ * a browser and WRONG (theme white instead of the node's own red) in any consumer
+ * that skips inline CSS — which is the exact class of bug this card exists to
+ * kill. One property, one value, one place.
+ */
+function elementAttrs(vnode, options, extraDefs, html) {
+    var _a;
+    const props = (_a = vnode.props) !== null && _a !== void 0 ? _a : {};
+    const attrs = new Map();
+    let text;
+    let raw;
+    let inline = {};
+    // 'dom': describe the DOM the patcher would build, verbatim. No dropping, no
+    // flattening, no filter translation — the client HAS the stylesheet, and any
+    // difference here is a hydration mismatch (torn-down + rebuilt nodes = a flash).
+    const dom = options.fidelity === 'dom';
+    for (const key of Object.keys(props)) {
+        const value = props[key];
+        if (value === null || value === undefined)
+            continue;
+        // Event handlers are not attributes. Stringifying a function into the output
+        // would emit a JS source dump as an attribute value.
+        if (typeof value === 'function')
+            continue;
+        // Live-pipeline attributes: meaningless in a file, and minted from process-global
+        // counters, so keeping them would make the bytes depend on how many renderers the
+        // process happened to build first. In a DOM snapshot they must SURVIVE — the CSS
+        // scope (`data-grafloria-instance`) and the component-mount handle both depend on them.
+        if (!dom && DROPPED_PROPS.has(key))
+            continue;
+        if (key === 'textContent') {
+            text = String(value);
+            continue;
+        }
+        // `innerHTML` OWNS the element's content — the patcher assigns it to
+        // `el.innerHTML`, so it is MARKUP, not an attribute value (HTML edge labels,
+        // Card 5). Kebab-casing it like any other prop would emit
+        // `inner-h-t-m-l="&lt;b&gt;…"`: an escaped attribute nobody reads, and an empty
+        // label in every exported file and every server render.
+        if (key === 'innerHTML') {
+            raw = String(value);
+            continue;
+        }
+        if (key === 'style') {
+            // HTML has no presentation attributes: keep the style attribute verbatim.
+            // Same for a DOM snapshot — the patcher writes `style`, so we must too.
+            if (html || dom) {
+                const serialized = (0, patch_1.serializeStyle)(value);
+                if (serialized)
+                    attrs.set('style', serialized);
+            }
+            else {
+                inline = parseStyleDecls(value);
+            }
+            continue;
+        }
+        if (key === 'filter' && !dom) {
+            attrs.set('filter', translateBlurFilter(String(value), extraDefs));
+            continue;
+        }
+        attrs.set((0, patch_1.attrNameForProp)(key), String(value));
+    }
+    if (dom) {
+        // The patcher mirrors the VNode key into the DOM as `data-vnode-key`; a snapshot
+        // that omitted it would present a different attribute set on every keyed element.
+        if (vnode.key !== undefined && vnode.key !== null) {
+            attrs.set('data-vnode-key', String(vnode.key));
+        }
+        return { attrs, text, raw };
+    }
+    // Inside a foreignObject the host's CSS owns the content — we neither know nor
+    // flatten it.
+    if (html)
+        return { attrs, text, raw };
+    // (2) the stylesheet layer, flattened
+    const resolver = options.classStyles;
+    if (resolver) {
+        for (const [prop, value] of Object.entries(resolver(classList(props['className'])))) {
+            attrs.set(prop, value);
+        }
+    }
+    // (3) the element's own inline style — the cascade's winner
+    for (const [prop, value] of Object.entries(inline)) {
+        if (CSS_ONLY_DECLS.has(prop))
+            continue;
+        attrs.set(prop, prop === 'filter' ? translateBlurFilter(value, extraDefs) : value);
+    }
+    return { attrs, text, raw };
+}
+function renderAttrs(attrs) {
+    let out = '';
+    for (const [name, value] of attrs) {
+        out += ` ${name}="${escapeAttr(value)}"`;
+    }
+    return out;
+}
+/** Empty child slots (the fallout of conditional children) — same rule as the patcher. */
+function isRenderable(child) {
+    return child !== null && child !== undefined && child !== false;
+}
+function isVNodeChild(child) {
+    return !!child && typeof child === 'object' && typeof child.type === 'string';
+}
+//# sourceMappingURL=vnode-serializer.js.map

package/src/libs/renderer/src/export/vnode-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vnode-serializer.js","sourceRoot":"","sources":["../../../../../../renderer/src/export/vnode-serializer.ts"],"names":[],"mappings":";AAAA,gEAAgE;AAChE,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,kFAAkF;AAClF,8DAA8D;AAC9D,EAAE;AACF,8EAA8E;AAC9E,6CAA6C;AAC7C,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,qEAAqE;AACrE,+EAA+E;AAC/E,gFAAgF;AAChF,kFAAkF;AAClF,0BAA0B;AAC1B,EAAE;AACF,sFAAsF;AACtF,kFAAkF;AAClF,8EAA8E;AAC9E,iFAAiF;AACjF,6EAA6E;AAC7E,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,mFAAmF;AACnF,iEAAiE;AACjE,EAAE;AACF,2DAA2D;AAC3D,yEAAyE;AACzE,kFAAkF;AAClF,gFAAgF;AAChF,iFAAiF;AACjF,kFAAkF;AAClF,qBAAqB;;AAwFrB,gCAMC;AAGD,gCAEC;AAuCD,wCAoDC;AA3LD,0CAAyE;AA+BzE;;;;GAIG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,yBAAyB,CAAC,CAAC,CAAC;AAE1E,kDAAkD;AAClD,MAAM,QAAQ,GAAG,iCAAiC,CAAC;AA6CnD,qCAAqC;AACrC,SAAgB,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,+BAA+B;AAC/B,SAAgB,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAClF,CAAC;AAED,8CAA8C;AAC9C,SAAS,SAAS,CAAC,SAAkB;IACnC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IACxE,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,KAAa,EAAE,SAA8B;IACxE,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC,CAAC,gDAAgD;IAE1E,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,kBAAkB,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAChE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,SAAS,CAAC,GAAG,CACX,EAAE,EACF,eAAe,EAAE,iDAAiD;YAChE,iCAAiC,MAAM,GAAG,CAAC,KAAK;YAChD,WAAW,CACd,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,EAAE,GAAG,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,KAAY,EAAE,UAA4B,EAAE;;IACzE,MAAM,QAAQ,GAAG,MAAA,OAAO,CAAC,QAAQ,mCAAI,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,MAAA,OAAO,CAAC,SAAS,mCAAI,IAAI,GAAG,EAAkB,CAAC;IACjE,MAAM,MAAM,GAAG,MAAA,OAAO,CAAC,aAAa,mCAAI,WAAW,CAAC;IACpD,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,KAAK,CAAC;IAEvC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACnC,OAAO,sBAAsB,CAAC,KAAK,kCAAO,OAAO,KAAE,QAAQ,EAAE,SAAS,KAAI,MAAM,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,CAAC,MAAA,KAAK,CAAC,QAAQ,mCAAI,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAE7D,gFAAgF;IAChF,qEAAqE;IACrE,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAC/D,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,cAAM,CAAC,CAAC;IAC7B,CAAC;IAED,8EAA8E;IAC9E,0DAA0D;IAC1D,MAAM,SAAS,mCAA0B,OAAO,KAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,GAAE,CAAC;IAE3F,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAEnD,4EAA4E;IAC5E,qEAAqE;IACrE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,GAAG,IAAI,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC;IACvD,CAAC;IAED,gFAAgF;IAChF,kCAAkC;IAClC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,GAAG,IAAI,IAAI,GAAG,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC;IAC1C,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,sEAAsE;QACtE,sEAAsE;QACtE,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;IACxD,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ;SACnB,GAAG,CAAC,KAAK,CAAC,EAAE,CACX,YAAY,CAAC,KAAK,CAAC;QACjB,CAAC,CAAC,cAAc,CAAC,KAAc,EAAE,SAAS,CAAC;QAC3C,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC9B;SACA,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO,GAAG,IAAI,IAAI,KAAK,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,sBAAsB,CAC7B,KAAY,EACZ,OAAkF,EAClF,IAAuB;;IAEvB,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,KAAK,GAAG,MAAA,KAAK,CAAC,KAAK,mCAAI,EAAE,CAAC;IAEhC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;QAC/D,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,6EAA6E,CAAC,CAAC;QAC7F,OAAO,CACL,YAAY,MAAA,KAAK,CAAC,CAAC,mCAAI,CAAC,QAAQ,MAAA,KAAK,CAAC,CAAC,mCAAI,CAAC,IAAI;YAChD,UAAU,MAAA,KAAK,CAAC,KAAK,mCAAI,CAAC,aAAa,MAAA,KAAK,CAAC,MAAM,mCAAI,CAAC,IAAI;YAC5D,uEAAuE;YACvE,yCAAyC,CAC1C,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,MAAM,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,iBAAiB,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAEnD,MAAM,QAAQ,GAAG,MAAA,OAAO,CAAC,oBAAoB,wDAAG,KAAK,CAAC,CAAC;IACvD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,GAAG,IAAI,IAAI,QAAQ,kBAAkB,CAAC;IAC/C,CAAC;IAED,QAAQ,CAAC,IAAI,CACX,uGAAuG;QACrG,qHAAqH,CACxH,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,MAAA,KAAK,CAAC,QAAQ,mCAAI,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC7D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,IAAI,IAAI,CAAC;IAE9C,qCAAqC;IACrC,MAAM,WAAW,mCAA0B,OAAO,KAAE,IAAI,EAAE,IAAI,GAAE,CAAC;IACjE,MAAM,KAAK,GAAG,QAAQ;SACnB,GAAG,CAAC,KAAK,CAAC,EAAE,CACX,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAc,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC9F;SACA,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,GAAG,IAAI,IAAI,KAAK,kBAAkB,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,YAAY;IACZ,QAAQ;IACR,aAAa;IACb,WAAW;IACX,gBAAgB;IAChB,oBAAoB;IACpB,qBAAqB;IACrB,2BAA2B;IAC3B,2BAA2B;IAC3B,aAAa;IACb,kBAAkB;CACnB,CAAC,CAAC;AAEH,oGAAoG;AACpG,SAAS,eAAe,CAAC,KAAc;IACrC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,MAAM,UAAU,GAAG,IAAA,sBAAc,EAAC,KAAK,CAAC,CAAC,CAAC,wCAAwC;IAClF,IAAI,CAAC,UAAU;QAAE,OAAO,GAAG,CAAC;IAE5B,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK,GAAG,CAAC;YAAE,SAAS;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3C,IAAI,IAAI,IAAI,KAAK;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,YAAY,CACnB,KAAY,EACZ,OAAyB,EACzB,SAA8B,EAC9B,IAAa;;IAEb,MAAM,KAAK,GAAG,MAAA,KAAK,CAAC,KAAK,mCAAI,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,IAAI,IAAwB,CAAC;IAC7B,IAAI,GAAuB,CAAC;IAC5B,IAAI,MAAM,GAA2B,EAAE,CAAC;IAExC,6EAA6E;IAC7E,6EAA6E;IAC7E,iFAAiF;IACjF,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,KAAK,CAAC;IAEvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAEzB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QACpD,6EAA6E;QAC7E,qDAAqD;QACrD,IAAI,OAAO,KAAK,KAAK,UAAU;YAAE,SAAS;QAC1C,kFAAkF;QAClF,kFAAkF;QAClF,iFAAiF;QACjF,wFAAwF;QACxF,IAAI,CAAC,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAE7C,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YAC1B,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QAED,qEAAqE;QACrE,6EAA6E;QAC7E,0DAA0D;QAC1D,gFAAgF;QAChF,wDAAwD;QACxD,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YACxB,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QAED,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YACpB,0EAA0E;YAC1E,wEAAwE;YACxE,IAAI,IAAI,IAAI,GAAG,EAAE,CAAC;gBAChB,MAAM,UAAU,GAAG,IAAA,sBAAc,EAAC,KAAK,CAAC,CAAC;gBACzC,IAAI,UAAU;oBAAE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACjD,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7B,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;YACnE,SAAS;QACX,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,IAAA,uBAAe,EAAC,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,GAAG,EAAE,CAAC;QACR,iFAAiF;QACjF,kFAAkF;QAClF,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;YAClD,KAAK,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED,+EAA+E;IAC/E,cAAc;IACd,IAAI,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAEtC,sCAAsC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC;IACrC,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACpF,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACvC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACrF,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,WAAW,CAAC,KAA0B;IAC7C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QAClC,GAAG,IAAI,IAAI,IAAI,KAAK,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0FAA0F;AAC1F,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAK,KAAiB,KAAK,KAAK,CAAC;AAC/E,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAAe,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC3F,CAAC"}

package/src/libs/renderer/src/ext/capabilities.d.ts

@@ -0,0 +1,178 @@
+/**
+ * ============================================================================
+ * Card 0 — the typed CAPABILITY accessors
+ * ============================================================================
+ *
+ * An extension never receives the engine, the renderer, or a raw registry. It
+ * receives a set of narrow, typed capability objects — and ONLY the ones its
+ * manifest declared (Card 7). That is the least-privilege rule, and it is what
+ * makes an extension's blast radius readable from its manifest alone.
+ *
+ * Every `register*` here returns a {@link Disposer}, and every disposer RESTORES
+ * the previous registration rather than merely deleting the key — so an
+ * extension that overrode a built-in gives it back on unload.
+ *
+ * These are FACADES. Not one of them reimplements a registry: they delegate to
+ * the real ones (shape-registry, edge-templates, RoutingEngine, TemplateRegistry,
+ * CustomAnimationRegistry, and Wave 6's link-pipeline), adding only the disposer
+ * + restore semantics the underlying registries never had.
+ */
+import type { DiagramEngine, NodeTemplate, TemplateRegistry } from '@grafloria/engine';
+import type { IRouter } from '@grafloria/engine';
+import type { ShapeDefinition } from '../svg/shape-registry';
+import type { PathGeometry, PathShapeOptions } from '../svg/shape-registry';
+import type { LinkTemplate, LabelTemplate, MarkerDefinition } from '../svg/edge-templates';
+import type { CustomAnimationDefinition } from '../services/custom-animation-registry';
+import type { AnchorFn, ConnectionPointFn, ConnectorFn } from './link-pipeline';
+import type { Disposer } from './disposable';
+import type { Portal, PortalOptions, ViewportPortal } from './portal';
+import type { CanvasTool, ConnectionValidator } from './tools';
+/** The names an extension may request. Mirrors the keys of {@link ExtensionCapabilities}. */
+export type CapabilityName = 'shapes' | 'links' | 'routers' | 'templates' | 'animations' | 'tools' | 'panels';
+/** Contribute node geometry. Wraps the (already unified) shape registry. */
+export interface ShapeCapability {
+    /** Register a full shape definition. */
+    register(type: string, definition: Omit<ShapeDefinition, 'type'> & {
+        type?: string;
+    }): Disposer;
+    /** Register a shape from an SVG path (boundary + port anchors auto-derived). */
+    registerPath(type: string, geometry: PathGeometry, options?: PathShapeOptions): Disposer;
+    has(type: string): boolean;
+    list(): string[];
+}
+/** Contribute link visuals + the four link-pipeline stages. */
+export interface LinkCapability {
+    /** Whole-link VNode template (`link.style.template`). */
+    registerTemplate(name: string, template: LinkTemplate): Disposer;
+    /** Label VNode template (`label.template`). */
+    registerLabelTemplate(name: string, template: LabelTemplate): Disposer;
+    /** Arrowhead / marker (`arrowHead.type`). */
+    registerMarker(name: string, definition: MarkerDefinition): Disposer;
+    /** Polyline → SVG path `d` (`link.connector`). */
+    registerConnector(name: string, connector: ConnectorFn): Disposer;
+    /** Per-end attachment point (`link.metadata.sourceAnchor` / `targetAnchor`). */
+    registerAnchor(name: string, anchor: AnchorFn): Disposer;
+    /** Whole-link, two-ended attachment strategy (`link.metadata.connectionPoint`). */
+    registerConnectionPoint(name: string, strategy: ConnectionPointFn): Disposer;
+    listConnectors(): string[];
+    listAnchors(): string[];
+    listConnectionPoints(): string[];
+}
+/** Contribute routing algorithms. Wraps `RoutingEngine.registerRouter`. */
+export interface RouterCapability {
+    register(name: string, router: IRouter): Disposer;
+    list(): string[];
+    has(name: string): boolean;
+}
+/** Contribute reusable node templates. Wraps the engine's TemplateRegistry. */
+export interface TemplateCapability {
+    register(template: NodeTemplate): Disposer;
+    list(): NodeTemplate[];
+    has(id: string): boolean;
+}
+/** Contribute named animations. Wraps CustomAnimationRegistry. */
+export interface AnimationCapability {
+    register(definition: CustomAnimationDefinition): Disposer;
+    has(name: string): boolean;
+    list(): CustomAnimationDefinition[];
+}
+/** Contribute interaction tools + connection validation (Card 5). */
+export interface ToolCapability {
+    /**
+     * Register (or REPLACE, by name) a canvas tool. Replacing `'node-drag'` with
+     * your own is the point: the built-ins are registrations, not privileged code.
+     */
+    register(tool: CanvasTool): Disposer;
+    /** Veto connections. All registered validators must pass. */
+    registerConnectionValidator(validator: ConnectionValidator): Disposer;
+    list(): string[];
+    has(id: string): boolean;
+}
+/**
+ * Contribute on-canvas UI (Card 6). This is the ONLY capability that hands back
+ * a DOM element, and it is scoped to the diagram's own layers — an extension
+ * cannot reach the rest of the page through it.
+ */
+export interface PanelCapability {
+    /** A floating panel pinned to the viewport (does not pan/zoom). */
+    createPanel(options?: PortalOptions): Portal;
+    /** Content that lives IN the diagram (pans/zooms with the canvas). */
+    createViewportPanel(options?: {
+        x?: number;
+        y?: number;
+        className?: string;
+        style?: string;
+    }): ViewportPortal;
+    /** World-space, but held at a constant on-screen size. */
+    createCounterScaledPanel(options?: {
+        x?: number;
+        y?: number;
+        className?: string;
+        style?: string;
+    }): ViewportPortal;
+}
+/**
+ * The full capability set. An extension's `activate()` receives a PARTIAL of
+ * this — exactly the keys its manifest declared.
+ */
+export interface ExtensionCapabilities {
+    shapes: ShapeCapability;
+    links: LinkCapability;
+    routers: RouterCapability;
+    templates: TemplateCapability;
+    animations: AnimationCapability;
+    tools: ToolCapability;
+    panels: PanelCapability;
+}
+/**
+ * What an extension is given at activation, beyond its capabilities: a scoped
+ * logger, its own resolved manifest, and a disposal bag. Deliberately NOT the
+ * engine — see Card 7.
+ */
+export interface ExtensionContext<C extends CapabilityName = CapabilityName> {
+    /** Only the capabilities the manifest declared. */
+    readonly capabilities: Pick<ExtensionCapabilities, C>;
+    /** The extension's own id. */
+    readonly id: string;
+    /**
+     * Anything pushed here is disposed with the extension. Use it for your own
+     * timers/listeners; registry registrations are tracked automatically.
+     */
+    onDispose(disposer: Disposer): void;
+}
+/**
+ * The host's own view of the world. Passed to the capability factories so they
+ * can reach the real registries. NOT exposed to extensions.
+ */
+export interface HostBindings {
+    engine: DiagramEngine;
+    /**
+     * The registry every contribution is written into. Pass `diagram.registry` and
+     * this host's extensions contribute to THAT DIAGRAM ONLY.
+     *
+     * Absent means the PROCESS-GLOBAL registries, which is what every host did
+     * before per-diagram registries existed and remains the right answer for an
+     * app-wide plugin. It is also why two hosts on one page used to fight: both
+     * wrote the same `badge`, the second won, and the first one's `dispose()`
+     * restored "no badge" over the top of the second's registration.
+     */
+    registry?: import('./diagram-registry').DiagramRegistry;
+    /**
+     * The engine's node-template registry.
+     *
+     * MUST be passed explicitly: `TemplateRegistry` is constructed with an
+     * `EventBus` and is NOT reachable from `DiagramEngine` (there is no
+     * `getTemplateRegistry()`), so the host cannot find it on its own. An
+     * extension declaring the `templates` capability is REJECTED when this is
+     * absent — rather than handed a capability object that would throw on use.
+     */
+    templateRegistry?: TemplateRegistry;
+    /** The diagram root element — panels attach here. May be absent (headless). */
+    root?: HTMLElement;
+    /** The camera-transformed HTML layer — world-space panels attach here. */
+    htmlLayer?: HTMLElement;
+    /** The camera, for counter-scaled panels. */
+    viewport?: import('../viewport/viewport-controller').ViewportController;
+    /** Ask the host to repaint (a contributed shape/connector changes the picture). */
+    requestRender?: () => void;
+}

package/src/libs/renderer/src/ext/capabilities.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * ============================================================================
+ * Card 0 — the typed CAPABILITY accessors
+ * ============================================================================
+ *
+ * An extension never receives the engine, the renderer, or a raw registry. It
+ * receives a set of narrow, typed capability objects — and ONLY the ones its
+ * manifest declared (Card 7). That is the least-privilege rule, and it is what
+ * makes an extension's blast radius readable from its manifest alone.
+ *
+ * Every `register*` here returns a {@link Disposer}, and every disposer RESTORES
+ * the previous registration rather than merely deleting the key — so an
+ * extension that overrode a built-in gives it back on unload.
+ *
+ * These are FACADES. Not one of them reimplements a registry: they delegate to
+ * the real ones (shape-registry, edge-templates, RoutingEngine, TemplateRegistry,
+ * CustomAnimationRegistry, and Wave 6's link-pipeline), adding only the disposer
+ * + restore semantics the underlying registries never had.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=capabilities.js.map

package/src/libs/renderer/src/ext/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../../../../renderer/src/ext/capabilities.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/src/libs/renderer/src/ext/capability-factory.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ============================================================================
+ * Card 0 — the FACADE. This is where capability objects meet the real registries.
+ * ============================================================================
+ *
+ * Read this file as the answer to "did they rewrite the registries?" — no. Every
+ * method below is a delegation to the registry that already existed, wrapped in
+ * exactly two things it did not have:
+ *
+ *   1. a DISPOSER, and
+ *   2. RESTORE-ON-DISPOSE (put back what was there before, don't just delete).
+ *
+ * `buildCapabilities` also enforces the grant: it materialises ONLY the keys the
+ * manifest declared. An extension that did not ask for `routers` does not get a
+ * `routers` object it could call — the property is absent, not merely typed away.
+ *
+ * ---------------------------------------------------------------------------
+ * WHOSE REGISTRY — the thing that used to be missing
+ * ---------------------------------------------------------------------------
+ * Every delegation below now goes through `bindings.registry`, which is
+ * `diagram.registry` when the host was bound to one and the process-global
+ * registry otherwise. Both are the SAME class (see `diagram-registry.ts`), so
+ * there is one implementation of restore-on-dispose rather than one per scope.
+ *
+ * That single indirection is the whole per-diagram isolation fix. Before it,
+ * two hosts on one page wrote the same module-global map: the second
+ * registration silently repainted the first diagram, and the first host's
+ * `dispose()` — faithfully restoring what was there before IT registered —
+ * deleted the second diagram's shape out from under it.
+ *
+ * NOT YET ROUTED: `tools` and `registerConnectionValidator`. Those registries are
+ * read on the INTERACTION path (`resolveTool` on pointerdown, `isValidConnection`
+ * during snapping), not inside the render pass, so scoping their storage without
+ * also scoping those four read sites would make a scoped tool invisible — a
+ * worse bug than the one being fixed. They are still process-global and still
+ * collide between diagrams; see the note on `tools` below.
+ */
+import type { CapabilityName, ExtensionCapabilities, HostBindings } from './capabilities';
+import type { DisposableStore } from './disposable';
+/**
+ * Build the capability objects for ONE extension, tracking every registration in
+ * that extension's own {@link DisposableStore}.
+ */
+export declare function buildCapabilities(granted: readonly CapabilityName[], bindings: HostBindings, store: DisposableStore): Partial<ExtensionCapabilities>;