@peter.prib/renderengine 0.14.0 → 0.15.1

package/src/SVGRenderer.js

@@ -1,455 +1,477 @@
-import { BaseRenderer } from './BaseRenderer.js';
-
-/**
- * @class SVGRenderer
- * Renders shapes by creating and appending SVG elements to an <svg> tag.
- */
-export class SVGRenderer extends BaseRenderer {
-    get type() { return 'svg'; }
-    get supportsSceneGraph() { return true; }
-
-    static #instances = 0;
-
-    /**
-     * The id of a line-end marker in this renderer's <defs>. Each renderer has
-     * its own prefix: ids are page-wide, and `url(#arrow)` would otherwise find
-     * the first SVG's marker, which may be hidden (another tab, another editor).
-     * @param {string} name - marker name, e.g. 'arrow', 'diamond-hollow'
-     */
-    markerId(name) { return `${this.markerPrefix}${name}`; }
-
-    /** The `marker-start`/`marker-end` value for a marker name. */
-    markerUrl(name) { return `url(#${this.markerId(name)})`; }
-
-    _createElement(tag,attributes = {},stroke = null) {
-        const el = document.createElementNS("http://www.w3.org/2000/svg", tag);
-        this._setAttributes(el, attributes);
-        if (stroke) {
-            this._setAttributes(el, { stroke: stroke.color || 'none', 'stroke-width': stroke.width || 1 });
-            // Used by the gauge arcs' rounded end-caps ({cap: 'round'}) — was
-            // silently dropped, so gauges always got default (butt) caps.
-            if (stroke.cap) this._setAttributes(el, { 'stroke-linecap': stroke.cap });
-        }
-        // Do not append here; let the caller decide.
-        // if (this.svg) this.svg.appendChild(el);
-        return el;
-    }
-    _elMap = new Map();
-    constructor(container, width, height) {
-        super(container, width, height);
-        this.markerPrefix = `re${SVGRenderer.#instances++}-`;
-        this.svg = this._createElement("svg",{ width, height, viewBox: `0 0 ${width} ${height}` });
-        // Inline elements (the default for <svg>) leave a few px of baseline
-        // whitespace below them inside a block container, making the
-        // container's scrollHeight exceed its clientHeight for every chart.
-        this.svg.style.display = 'block';
-
-        // Add a style tag for hover effects
-        const defs = this._createElement('defs');
-
-        // Default arrow marker
-        const arrowMarker = this._createElement('marker', { id: this.markerId('arrow'), viewBox: '0 0 10 10', refX: 8, refY: 5, markerWidth: 6, markerHeight: 6, orient: 'auto-start-reverse' });
-        arrowMarker.appendChild(this._createElement('path', { d: 'M 0 0 L 10 5 L 0 10 z', class: 'arrowhead-path' }));
-        defs.appendChild(arrowMarker);
-
-        // Circle marker
-        const circleMarker = this._createElement('marker', { id: this.markerId('circle'), viewBox: '0 0 10 10', refX: 5, refY: 5, markerWidth: 6, markerHeight: 6, orient: 'auto-start-reverse' });
-        circleMarker.appendChild(this._createElement('circle', { cx: 5, cy: 5, r: 4, class: 'arrowhead-path' }));
-        defs.appendChild(circleMarker);
-
-        // Tee marker
-        const teeMarker = this._createElement('marker', { id: this.markerId('tee'), viewBox: '0 0 10 10', refX: 1, refY: 5, markerWidth: 6, markerHeight: 6, orient: 'auto-start-reverse' });
-        teeMarker.appendChild(this._createElement('path', { d: 'M 0 0 L 0 10', 'stroke-width': 2, class: 'arrowhead-path' }));
-        defs.appendChild(teeMarker);
-
-        // The four markers below exist for graphDiagram's relationship-style
-        // notation (composition/aggregation/realization/specialization/
-        // serving/access/influence — see _archimateRelationshipStyle) but
-        // aren't ArchiMate-specific themselves: any edge can use them via
-        // `arrowhead`/`arrowheadStart`, same as 'arrow'/'circle'/'tee' above.
-        // Filled diamond (composition's "whole"-end glyph).
-        const diamondMarker = this._createElement('marker', { id: this.markerId('diamond'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
-        diamondMarker.appendChild(this._createElement('path', { d: 'M0,5 L5,0 L10,5 L5,10 Z', class: 'arrowhead-path' }));
-        defs.appendChild(diamondMarker);
-
-        // Hollow diamond (aggregation) — filled white, not transparent, so
-        // the line underneath doesn't show through the shape.
-        const diamondHollowMarker = this._createElement('marker', { id: this.markerId('diamond-hollow'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
-        diamondHollowMarker.appendChild(this._createElement('path', { d: 'M0,5 L5,0 L10,5 L5,10 Z', class: 'arrowhead-path-hollow' }));
-        defs.appendChild(diamondHollowMarker);
-
-        // Hollow triangle (realization/specialization) — same white-filled
-        // convention as the hollow diamond above.
-        const triangleHollowMarker = this._createElement('marker', { id: this.markerId('triangle-hollow'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
-        triangleHollowMarker.appendChild(this._createElement('path', { d: 'M0,0 L10,5 L0,10 Z', class: 'arrowhead-path-hollow' }));
-        defs.appendChild(triangleHollowMarker);
-
-        // Open/thin arrow (serving, access, influence) — an unfilled chevron,
-        // distinct from 'arrow's solid filled triangle.
-        const openArrowMarker = this._createElement('marker', { id: this.markerId('open-arrow'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
-        openArrowMarker.appendChild(this._createElement('path', { d: 'M0,0 L9,5 L0,10', class: 'arrowhead-path-open' }));
-        defs.appendChild(openArrowMarker);
-
-        // Half/single-barb open arrow — ArchiMate's DIRECTED association (the
-        // spec's own relationships figure shows association twice: a plain
-        // line, and this one-barb variant for the directed form).
-        const halfArrowMarker = this._createElement('marker', { id: this.markerId('open-arrow-half'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
-        halfArrowMarker.appendChild(this._createElement('path', { d: 'M0,0 L9,5', class: 'arrowhead-path-open' }));
-        defs.appendChild(halfArrowMarker);
-
-        // Crow's-foot ERD cardinality glyphs (dataModelDiagram's 'crowsfoot'
-        // notation — see src/datamodel.js) — a representative rendition, not
-        // every real-notation optionality combination. All four share a
-        // 16-wide viewBox with refX:15 (the point that sits ON the entity's
-        // edge) so the drawn glyph sits BETWEEN the entity and the line,
-        // extending away from it toward x:0.
-        // "Exactly one" (mandatory, single cardinality) — one perpendicular tick.
-        const crowsfootOneMarker = this._createElement('marker', { id: this.markerId('crowsfoot-one'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
-        crowsfootOneMarker.appendChild(this._createElement('path', { d: 'M10,1 L10,9', class: 'arrowhead-path-open' }));
-        defs.appendChild(crowsfootOneMarker);
-        // "Zero or one" (optional, single cardinality) — hollow circle (the
-        // "zero"/optional part) plus one tick (the "one" part) further out.
-        const crowsfootOneOptionalMarker = this._createElement('marker', { id: this.markerId('crowsfoot-one-optional'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
-        crowsfootOneOptionalMarker.appendChild(this._createElement('circle', { cx: 12, cy: 5, r: 3, class: 'arrowhead-path-hollow' }));
-        crowsfootOneOptionalMarker.appendChild(this._createElement('path', { d: 'M5,1 L5,9', class: 'arrowhead-path-open' }));
-        defs.appendChild(crowsfootOneOptionalMarker);
-        // "Zero or many" (optional, many cardinality) — the crow's-foot fork
-        // alone, its three prongs touching the entity edge.
-        const crowsfootManyMarker = this._createElement('marker', { id: this.markerId('crowsfoot-many'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
-        crowsfootManyMarker.appendChild(this._createElement('path', { d: 'M5,5 L15,0 M5,5 L15,5 M5,5 L15,10', class: 'arrowhead-path-open' }));
-        defs.appendChild(crowsfootManyMarker);
-        // "One or many" (mandatory, many cardinality) — the fork plus one
-        // tick further out (the "at least one" part).
-        const crowsfootManyMandatoryMarker = this._createElement('marker', { id: this.markerId('crowsfoot-many-mandatory'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
-        crowsfootManyMandatoryMarker.appendChild(this._createElement('path', { d: 'M5,5 L15,0 M5,5 L15,5 M5,5 L15,10 M2,2 L2,8', class: 'arrowhead-path-open' }));
-        defs.appendChild(crowsfootManyMandatoryMarker);
-
-        this.svg.appendChild(defs);
-        const style =this._createElement("style");
-        style.textContent = `
-            .hover {
-                fill: orange;
-                stroke: #333;
-                stroke-width: 2px;
-            }
-            .selected {
-                filter: drop-shadow(0 0 3px var(--ws-accent, #91cc75));
-            }
-            .selected > path,
-            .selected > rect,
-            .selected > circle,
-            .selected > ellipse,
-            .selected > polygon {
-                stroke: var(--ws-accent, #91cc75);
-                stroke-width: 3px;
-            }
-            .selected-edge {
-                stroke: var(--ws-accent, #91cc75);
-                stroke-width: 3px;
-            }
-            .arrowhead-path {
-                fill: inherit;
-                stroke: inherit;
-            }
-            .arrowhead-path-hollow {
-                fill: white;
-                stroke: black;
-                stroke-width: 1px;
-            }
-            .arrowhead-path-open {
-                fill: none;
-                stroke: black;
-                stroke-width: 1.5px;
-            }
-        `;
-        this.svg.appendChild(style);
-        // The main SVG is now the default parent for new elements.
-        this.container.appendChild(this.svg);
-    }
-
-    /**
-     * Resize the <svg>. Its viewBox follows only while it is still the size it
-     * was created with: a diagram sets its own viewBox to its content, and that
-     * must survive, so the diagram then scales to the new box instead of
-     * being cropped to it.
-     */
-    resize(width, height) {
-        const defaultViewBox = `0 0 ${this.width} ${this.height}`;
-        super.resize(width, height);
-        this.svg.setAttribute('width', width);
-        this.svg.setAttribute('height', height);
-        if (this.svg.getAttribute('viewBox') === defaultViewBox) {
-            this.svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
-        }
-    }
-
-    clear() {
-        this._elMap.clear();
-        // Keep <defs> and <style> elements; remove everything else.
-        for (const child of [...this.svg.children]) {
-            if (child.tagName !== 'style' && child.tagName !== 'defs') child.remove();
-        }
-    }
-    _defineShape(shape,attributes, stroke = null) {
-        shape.id=`shape_${this._elMap.size}`;
-        const parent = shape.parent || this.svg;
-        const el = this._createElement(shape.type, attributes, stroke);
-        parent.appendChild(el);
-        this._elMap.set(shape.id, { el, shape });
-        return shape.id;
-    }
-    rect(x, y, width, height, fill, stroke, extra) {
-        const shape = { type: 'rect', x, y, width, height, fill, stroke, ...extra };
-        this._defineShape(shape, { x, y, width, height, fill: fill || 'none', ...extra }, stroke);
-        return this._elMap.get(shape.id).el;
-    }
-
-    circle(cx, cy, r, fill, stroke, extra) {
-        const shape = { type: 'circle', cx, cy, r, fill, stroke, ...extra};
-        this._defineShape(shape, { cx, cy, r, fill: fill || 'none' }, stroke);
-        return this._elMap.get(shape.id).el;
-    }
-
-    path(d, fill, stroke, extra = {}) {
-        // `extra` (e.g. {tooltip}) merges into the shape descriptor only, not
-        // into DOM attributes — hitTest()/tooltip resolution reads it straight
-        // off `shape` (see _addTooltipListeners), it was never rendered as a
-        // real SVG attribute for rect/circle either. Previously missing here
-        // (CanvasRenderer.path already accepted it) — pie/doughnut wedges,
-        // candlestick bodies, and box-plot boxes all need path-level tooltips.
-        const shape = { type: 'path', d, fill, stroke, ...extra, id: `shape_${this._elMap.size}` };
-        // _createElement already applies stroke.color/width as real SVG attributes
-        // (see the `stroke` param handling above) — do NOT also set them as inline
-        // styles here. Setting style.fill = stroke.color previously clobbered any
-        // closed shape's real fill (e.g. graphDiagram's diamond node, filled with
-        // the group color but stroked white) with the stroke color instead, since
-        // inline styles win over attributes. Open paths (edge lines, fill:'none')
-        // never showed the bug since there's no enclosed area to paint either way.
-        const pathEl = this._createElement("path", { d, fill: fill || 'none' }, stroke);
-        this.svg.appendChild(pathEl);
-        this._elMap.set(shape.id, { el: pathEl, shape });
-        return pathEl;
-    }
-
-    /** Text width measured with a (shared, off-page) 2D canvas context; the estimate without a document. */
-    measureText(text, font = {}) {
-        if (typeof document === 'undefined' || typeof document.createElement !== 'function') return super.measureText(text, font);
-        const ctx = (SVGRenderer._measureContext ??= document.createElement('canvas').getContext?.('2d'));
-        if (!ctx) return super.measureText(text, font);
-        ctx.font = BaseRenderer.cssFont(font);
-        return ctx.measureText(String(text)).width;
-    }
-
-    text(text, x, y, options = {}) {
-        const shape = { type: 'text', text, x, y, ...options, id: `shape_${this._elMap.size}` };
-        const attrs = { x, y, fill: options.fill || 'black', 'font-family': options.fontFamily || 'sans-serif', 'font-size': options.fontSize || '12px', 'text-anchor': options.textAnchor || 'start' };
-        // Several call sites (graph-node initials/labels, table-node rows) pass
-        // verticalAlign:'middle' expecting the text to be vertically centred on
-        // its y-coordinate — this was silently ignored (SVG's default baseline
-        // is alphabetic, not middle), so multi-row content sat visibly low.
-        if (options.verticalAlign === 'middle') attrs['dominant-baseline'] = 'middle';
-        if (options.fontWeight) attrs['font-weight'] = options.fontWeight;
-        if (options.fontStyle) attrs['font-style'] = options.fontStyle;
-        // Every graphDiagram call site passes 'pointer-events':'none' on node
-        // initials/labels expecting clicks to fall through to the shape/badge
-        // underneath — silently dropped since it wasn't in this whitelist, so
-        // filled text always intercepted the click regardless of what callers
-        // asked for (surfaced by the new collapse-badge glyph sitting on top
-        // of its own circle and eating every click meant for it).
-        if (options['pointer-events']) attrs['pointer-events'] = options['pointer-events'];
-        // `rotation` is in radians (matches Canvas's ctx.rotate() convention) —
-        // convert to degrees for SVG's transform=rotate(deg, cx, cy). Every
-        // yAxisLabel call across the chart methods relies on this to render
-        // vertically instead of overlapping/clipping past the chart's left edge.
-        if (options.rotation) attrs.transform = `rotate(${options.rotation * 180 / Math.PI} ${x} ${y})`;
-        const el = this._createElement('text', attrs);
-        el.textContent = text;
-        this.svg.appendChild(el);
-        this._elMap.set(shape.id, { el, shape });
-        return el;
-    }
-
-    /** An SVG `<image>` — used for graphDiagram's `node.iconUrl` (a custom
-     *  icon/image file/data URI centred on a node, in place of the plain
-     *  initials text). `href` is set as the plain SVG2 attribute; every
-     *  renderer target this library ships against (real browsers, jsdom in
-     *  tests) resolves that without also needing the legacy `xlink:href`. */
-    image(href, x, y, width, height, options = {}) {
-        const shape = { type: 'image', href, x, y, width, height, ...options, id: `shape_${this._elMap.size}` };
-        const attrs = { href, x, y, width, height, preserveAspectRatio: options.preserveAspectRatio || 'xMidYMid meet' };
-        if (options['pointer-events']) attrs['pointer-events'] = options['pointer-events'];
-        const el = this._createElement('image', attrs);
-        this.svg.appendChild(el);
-        this._elMap.set(shape.id, { el, shape });
-        return el;
-    }
-
-    group(attributes = {}) {
-        const shape = { type: 'g', ...attributes, id: `shape_${this._elMap.size}` };
-        const el = this._createElement('g', attributes);
-        this.svg.appendChild(el);
-        this._elMap.set(shape.id, { el, shape });
-        return el;
-    }
-
-    hitTest(x, y) {
-        // This is a bit of a hack. We find the element and then iterate our map to find the shape.
-        // A more robust solution might use a WeakMap from element to shape.
-        //
-        // `x`/`y` are viewport coordinates (every caller in index.js passes
-        // event.clientX/clientY straight through) — document.elementFromPoint
-        // already takes coordinates in that same space. Adding this.svg's own
-        // getBoundingClientRect().left/top on top double-offset the query
-        // point by the canvas's on-page position, so hitTest silently queried
-        // the wrong spot on the page for any layout where the SVG isn't flush
-        // against the browser's top-left corner (i.e. basically always, once
-        // there's a toolbar/sidebar around it) — drag-start, the context
-        // menu, and tooltips all read this result directly, so all three
-        // misfired by exactly that offset. Zoom (the SVG's internal viewBox
-        // scale) doesn't factor in here at all: elementFromPoint operates on
-        // real rendered screen pixels, which already reflect whatever zoom is
-        // applied, so no CTM/zoom math belongs in this function.
-        const hitEl = this.svg.ownerDocument.elementFromPoint(x, y);
-        if (!hitEl) return null;
-        return SVGRenderer.resolveHit(this._elMap, hitEl);
-    }
-
-    /**
-     * Given the element under the cursor and the el→{el,shape} registry, picks
-     * which registered shape a hit resolves to. Split out from hitTest() so
-     * this candidate-selection logic is unit-testable without a real DOM
-     * (`hitEl`/registered `el`s just need a `.contains()` method).
-     *
-     * A graph node is drawn as an outer <g draggable nodeId tooltip> wrapping
-     * an inner shape primitive (circle/rect/path) plus text labels — each
-     * registered in _elMap separately, with the inner primitive inserted
-     * *before* the wrapping group. Since _elMap is iterated in insertion order
-     * and this used to return the *first* match, a click on the node's own
-     * visible body resolved to the inner primitive's bare shape (no
-     * draggable/tooltip/nodeId) instead of the wrapping group — silently
-     * breaking drag-start, the context menu, and hover tooltips (all of which
-     * read hitTest()'s result directly, unlike click-to-select which bubbles
-     * via a real DOM listener). Prefer a draggable node wrapper among the
-     * candidates when one is present; otherwise keep the original first-match
-     * behavior (legend markers etc. resolve via their own direct listeners
-     * already, not this method).
-     */
-    static resolveHit(elMap, hitEl) {
-        let first = null;
-        for (const { el, shape } of elMap.values()) {
-            if (el === hitEl || el.contains(hitEl)) {
-                if (!first) first = shape;
-                if (shape.draggable && shape.nodeId != null) return shape;
-            }
-        }
-        return first;
-    }
-
-    enterState(shape, stateName) {
-        this._elMap.get(shape.id)?.el.classList.add(stateName);
-    }
-
-    leaveState(shape, stateName) {
-        this._elMap.get(shape.id)?.el.classList.remove(stateName);
-    }
-
-    renderDiagram(diagram) {
-        // 20,20 padding matches this file's own DiagramNode.prototype.drawOn
-        // (railroadDiagram.js, the Canvas rendering path) — without a real
-        // starting x/y, every node's format() computes its own position as
-        // NaN (this used to be called with zero args, so x/y were undefined
-        // throughout the whole tree).
-        diagram.format(20, 20);
-
-        const group = this._createElement('g', {
-            'font-family': 'monospace',
-            'font-size': '12px'
-        });
-
-        // Collect every leaf first, then draw in a fixed path -> rect -> text
-        // paint order, rather than the tree's own traversal order. Connector
-        // lines (Sequence's backbone, ZeroOrMore's top line, Choice's arcs)
-        // legitimately run behind boxes they connect through — but walk()
-        // visits nodes in whatever order each FORMATTERS.* function happened
-        // to build its .item/.items — e.g. a Sequence's own backbone Path is
-        // appended (via addTo()) AFTER its child items are formatted, so it
-        // painted on top of and struck through every terminal/nonterminal
-        // box's text. A fixed paint order guarantees lines stay underneath
-        // opaque boxes and text stays readable on top, regardless of which
-        // order the diagram tree happens to store its children in.
-        const leaves = [];
-        diagram.walk(item => {
-            // The `if (item.type === 'rect'/'path'/'text')` chain below
-            // already correctly picks out only real leaf shapes — every
-            // intermediate DiagramNode-tree node (Sequence/Choice/Terminal/
-            // NonTerminal/...) has a .type that never matches any of those,
-            // so it's harmless to reach the chain and fall through. A prior
-            // `if (!item.width) return;` guard here was presumably meant to
-            // skip those same intermediate nodes, but 'text' and 'path'
-            // FakeSVG leaves never carry a .width at all (only 'rect' does —
-            // same as real SVG <text>/<path> elements), so it silently
-            // discarded every label and every connector line too.
-            if (item.type === 'rect' || item.type === 'path' || item.type === 'text') leaves.push(item);
-        });
-        const paintOrder = { path: 0, rect: 1, text: 2 };
-        leaves.sort((a, b) => paintOrder[a.type] - paintOrder[b.type]);
-        leaves.forEach(item => {
-            if (item.type === 'rect') {
-                // NonTerminal rects have no rx/ry (sharp corners, by design —
-                // see railroadDiagram.js's FORMATTERS.NonTerminal) — only
-                // pass them through when real, rather than setting a literal
-                // "undefined" string attribute value.
-                const extra = { parent: group };
-                if (item.rx != null) extra.rx = item.rx;
-                if (item.ry != null) extra.ry = item.ry;
-                this.rect(item.x, item.y, item.width, item.height, 'hsl(30,20%,95%)', { color: 'black', width: 2 }, extra);
-            } else if (item.type === 'path') {
-                const pathEl = this._createElement('path', { d: item.attrs.d }, { color: 'black', width: 3 });
-                pathEl.setAttribute('fill', 'none');
-                group.appendChild(pathEl);
-            } else if (item.type === 'text') {
-                const textEl = this._createElement('text', {
-                    x: item.x,
-                    y: item.y,
-                    'text-anchor': 'middle',
-                    fill: 'black'
-                });
-                if (item.attrs.class === 'comment') {
-                    textEl.setAttribute('font-style', 'italic');
-                } else if (item.type === 'NonTerminal') {
-                    textEl.setAttribute('font-weight', 'bold');
-                }
-                textEl.textContent = item.text;
-                group.appendChild(textEl);
-            }
-        });
-
-        // Every other SVGRenderer primitive (group()/rect()/circle()/...)
-        // appends itself to this.svg (or a specified parent) within its own
-        // method — this one built `group` and populated it via the walk
-        // callback's this.rect(...) calls (which do append into `group`,
-        // via the `parent: group` extra above), but never attached `group`
-        // to the actual <svg> itself, so nothing was ever visible.
-        this.svg.appendChild(group);
-
-        // A diagram's natural width is data-driven (however many rule
-        // elements it has) and routinely wider than a chart's fixed
-        // container box. Only the viewBox is updated to the content's real
-        // size — width/height stay at whatever they were set to at
-        // construction (the container's own clientWidth/clientHeight, same
-        // as every other chart type) — so the SVG's default
-        // preserveAspectRatio="xMidYMid meet" scales the whole diagram down
-        // to fit that fixed box, exactly like an <img>: no scrollbar, no
-        // clipping, just a smaller rendering for a wide diagram. (An
-        // earlier version of this also resized width/height to match the
-        // content, which fit the diagram at full native size but broke
-        // the page's CSS grid layout — a grid item's automatic minimum
-        // size is based on its content's intrinsic size unless something
-        // caps it — and even with that capped, still needed a scrollbar to
-        // reach the full content. Not resizing width/height avoids both.)
-        const w = diagram.width + 40, h = diagram.height + 40;
-        this.svg.setAttribute('viewBox', `0 0 ${w} ${h}`);
-
-        return group;
-    }
+import { BaseRenderer } from './BaseRenderer.js';
+
+/**
+ * @class SVGRenderer
+ * Renders shapes by creating and appending SVG elements to an <svg> tag.
+ */
+export class SVGRenderer extends BaseRenderer {
+    get type() { return 'svg'; }
+    get supportsSceneGraph() { return true; }
+
+    static #instances = 0;
+
+    /**
+     * The id of a line-end marker in this renderer's <defs>. Each renderer has
+     * its own prefix: ids are page-wide, and `url(#arrow)` would otherwise find
+     * the first SVG's marker, which may be hidden (another tab, another editor).
+     * @param {string} name - marker name, e.g. 'arrow', 'diamond-hollow'
+     */
+    markerId(name) { return `${this.markerPrefix}${name}`; }
+
+    /** The `marker-start`/`marker-end` value for a marker name. */
+    markerUrl(name) { return `url(#${this.markerId(name)})`; }
+
+    _createElement(tag,attributes = {},stroke = null) {
+        const el = document.createElementNS("http://www.w3.org/2000/svg", tag);
+        this._setAttributes(el, attributes);
+        if (stroke) {
+            this._setAttributes(el, { stroke: stroke.color || 'none', 'stroke-width': stroke.width || 1 });
+            // Used by the gauge arcs' rounded end-caps ({cap: 'round'}) — was
+            // silently dropped, so gauges always got default (butt) caps.
+            if (stroke.cap) this._setAttributes(el, { 'stroke-linecap': stroke.cap });
+        }
+        // Do not append here; let the caller decide.
+        // if (this.svg) this.svg.appendChild(el);
+        return el;
+    }
+    _elMap = new Map();
+    constructor(container, width, height) {
+        super(container, width, height);
+        this.markerPrefix = `re${SVGRenderer.#instances++}-`;
+        this.svg = this._createElement("svg",{ width, height, viewBox: `0 0 ${width} ${height}` });
+        // Inline elements (the default for <svg>) leave a few px of baseline
+        // whitespace below them inside a block container, making the
+        // container's scrollHeight exceed its clientHeight for every chart.
+        this.svg.style.display = 'block';
+
+        // Add a style tag for hover effects
+        const defs = this._createElement('defs');
+        this.defs = defs;
+
+        // Default arrow marker
+        const arrowMarker = this._createElement('marker', { id: this.markerId('arrow'), viewBox: '0 0 10 10', refX: 8, refY: 5, markerWidth: 6, markerHeight: 6, orient: 'auto-start-reverse' });
+        arrowMarker.appendChild(this._createElement('path', { d: 'M 0 0 L 10 5 L 0 10 z', class: 'arrowhead-path' }));
+        defs.appendChild(arrowMarker);
+
+        // Circle marker
+        const circleMarker = this._createElement('marker', { id: this.markerId('circle'), viewBox: '0 0 10 10', refX: 5, refY: 5, markerWidth: 6, markerHeight: 6, orient: 'auto-start-reverse' });
+        circleMarker.appendChild(this._createElement('circle', { cx: 5, cy: 5, r: 4, class: 'arrowhead-path' }));
+        defs.appendChild(circleMarker);
+
+        // Tee marker
+        const teeMarker = this._createElement('marker', { id: this.markerId('tee'), viewBox: '0 0 10 10', refX: 1, refY: 5, markerWidth: 6, markerHeight: 6, orient: 'auto-start-reverse' });
+        teeMarker.appendChild(this._createElement('path', { d: 'M 0 0 L 0 10', 'stroke-width': 2, class: 'arrowhead-path' }));
+        defs.appendChild(teeMarker);
+
+        // The four markers below exist for graphDiagram's relationship-style
+        // notation (composition/aggregation/realization/specialization/
+        // serving/access/influence — see _archimateRelationshipStyle) but
+        // aren't ArchiMate-specific themselves: any edge can use them via
+        // `arrowhead`/`arrowheadStart`, same as 'arrow'/'circle'/'tee' above.
+        // Filled diamond (composition's "whole"-end glyph).
+        const diamondMarker = this._createElement('marker', { id: this.markerId('diamond'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
+        diamondMarker.appendChild(this._createElement('path', { d: 'M0,5 L5,0 L10,5 L5,10 Z', class: 'arrowhead-path' }));
+        defs.appendChild(diamondMarker);
+
+        // Hollow diamond (aggregation) — filled white, not transparent, so
+        // the line underneath doesn't show through the shape.
+        const diamondHollowMarker = this._createElement('marker', { id: this.markerId('diamond-hollow'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
+        diamondHollowMarker.appendChild(this._createElement('path', { d: 'M0,5 L5,0 L10,5 L5,10 Z', class: 'arrowhead-path-hollow' }));
+        defs.appendChild(diamondHollowMarker);
+
+        // Hollow triangle (realization/specialization) — same white-filled
+        // convention as the hollow diamond above.
+        const triangleHollowMarker = this._createElement('marker', { id: this.markerId('triangle-hollow'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
+        triangleHollowMarker.appendChild(this._createElement('path', { d: 'M0,0 L10,5 L0,10 Z', class: 'arrowhead-path-hollow' }));
+        defs.appendChild(triangleHollowMarker);
+
+        // Open/thin arrow (serving, access, influence) — an unfilled chevron,
+        // distinct from 'arrow's solid filled triangle.
+        const openArrowMarker = this._createElement('marker', { id: this.markerId('open-arrow'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
+        openArrowMarker.appendChild(this._createElement('path', { d: 'M0,0 L9,5 L0,10', class: 'arrowhead-path-open' }));
+        defs.appendChild(openArrowMarker);
+
+        // Half/single-barb open arrow — ArchiMate's DIRECTED association (the
+        // spec's own relationships figure shows association twice: a plain
+        // line, and this one-barb variant for the directed form).
+        const halfArrowMarker = this._createElement('marker', { id: this.markerId('open-arrow-half'), viewBox: '0 0 10 10', refX: 9, refY: 5, markerWidth: 8, markerHeight: 8, orient: 'auto-start-reverse' });
+        halfArrowMarker.appendChild(this._createElement('path', { d: 'M0,0 L9,5', class: 'arrowhead-path-open' }));
+        defs.appendChild(halfArrowMarker);
+
+        // Crow's-foot ERD cardinality glyphs (dataModelDiagram's 'crowsfoot'
+        // notation — see src/datamodel.js) — a representative rendition, not
+        // every real-notation optionality combination. All four share a
+        // 16-wide viewBox with refX:15 (the point that sits ON the entity's
+        // edge) so the drawn glyph sits BETWEEN the entity and the line,
+        // extending away from it toward x:0.
+        // "Exactly one" (mandatory, single cardinality) — one perpendicular tick.
+        const crowsfootOneMarker = this._createElement('marker', { id: this.markerId('crowsfoot-one'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
+        crowsfootOneMarker.appendChild(this._createElement('path', { d: 'M10,1 L10,9', class: 'arrowhead-path-open' }));
+        defs.appendChild(crowsfootOneMarker);
+        // "Zero or one" (optional, single cardinality) — hollow circle (the
+        // "zero"/optional part) plus one tick (the "one" part) further out.
+        const crowsfootOneOptionalMarker = this._createElement('marker', { id: this.markerId('crowsfoot-one-optional'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
+        crowsfootOneOptionalMarker.appendChild(this._createElement('circle', { cx: 12, cy: 5, r: 3, class: 'arrowhead-path-hollow' }));
+        crowsfootOneOptionalMarker.appendChild(this._createElement('path', { d: 'M5,1 L5,9', class: 'arrowhead-path-open' }));
+        defs.appendChild(crowsfootOneOptionalMarker);
+        // "Zero or many" (optional, many cardinality) — the crow's-foot fork
+        // alone, its three prongs touching the entity edge.
+        const crowsfootManyMarker = this._createElement('marker', { id: this.markerId('crowsfoot-many'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
+        crowsfootManyMarker.appendChild(this._createElement('path', { d: 'M5,5 L15,0 M5,5 L15,5 M5,5 L15,10', class: 'arrowhead-path-open' }));
+        defs.appendChild(crowsfootManyMarker);
+        // "One or many" (mandatory, many cardinality) — the fork plus one
+        // tick further out (the "at least one" part).
+        const crowsfootManyMandatoryMarker = this._createElement('marker', { id: this.markerId('crowsfoot-many-mandatory'), viewBox: '0 0 16 10', refX: 15, refY: 5, markerWidth: 12, markerHeight: 8, orient: 'auto-start-reverse' });
+        crowsfootManyMandatoryMarker.appendChild(this._createElement('path', { d: 'M5,5 L15,0 M5,5 L15,5 M5,5 L15,10 M2,2 L2,8', class: 'arrowhead-path-open' }));
+        defs.appendChild(crowsfootManyMandatoryMarker);
+
+        this.svg.appendChild(defs);
+        const style =this._createElement("style");
+        style.textContent = `
+            .hover {
+                fill: orange;
+                stroke: #333;
+                stroke-width: 2px;
+            }
+            .selected {
+                filter: drop-shadow(0 0 3px var(--ws-accent, #91cc75));
+            }
+            .selected > path,
+            .selected > rect,
+            .selected > circle,
+            .selected > ellipse,
+            .selected > polygon {
+                stroke: var(--ws-accent, #91cc75);
+                stroke-width: 3px;
+            }
+            .selected-edge {
+                stroke: var(--ws-accent, #91cc75);
+                stroke-width: 3px;
+            }
+            .arrowhead-path {
+                fill: inherit;
+                stroke: inherit;
+            }
+            .arrowhead-path-hollow {
+                fill: white;
+                stroke: black;
+                stroke-width: 1px;
+            }
+            .arrowhead-path-open {
+                fill: none;
+                stroke: black;
+                stroke-width: 1.5px;
+            }
+        `;
+        this.svg.appendChild(style);
+        // The main SVG is now the default parent for new elements.
+        this.container.appendChild(this.svg);
+    }
+
+    /**
+     * Resize the <svg>. Its viewBox follows only while it is still the size it
+     * was created with: a diagram sets its own viewBox to its content, and that
+     * must survive, so the diagram then scales to the new box instead of
+     * being cropped to it.
+     */
+    resize(width, height) {
+        const defaultViewBox = `0 0 ${this.width} ${this.height}`;
+        super.resize(width, height);
+        this.svg.setAttribute('width', width);
+        this.svg.setAttribute('height', height);
+        if (this.svg.getAttribute('viewBox') === defaultViewBox) {
+            this.svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
+        }
+    }
+
+    clear() {
+        this._elMap.clear();
+        // Keep <defs> and <style> elements; remove everything else.
+        for (const child of [...this.svg.children]) {
+            if (child.tagName !== 'style' && child.tagName !== 'defs') child.remove();
+        }
+    }
+    _defineShape(shape,attributes, stroke = null) {
+        shape.id=`shape_${this._elMap.size}`;
+        const parent = shape.parent || this.svg;
+        const el = this._createElement(shape.type, attributes, stroke);
+        parent.appendChild(el);
+        this._elMap.set(shape.id, { el, shape });
+        return shape.id;
+    }
+    rect(x, y, width, height, fill, stroke, extra) {
+        const shape = { type: 'rect', x, y, width, height, fill, stroke, ...extra };
+        this._defineShape(shape, { x, y, width, height, fill: fill || 'none', ...extra }, stroke);
+        return this._elMap.get(shape.id).el;
+    }
+
+    circle(cx, cy, r, fill, stroke, extra) {
+        const shape = { type: 'circle', cx, cy, r, fill, stroke, ...extra};
+        this._defineShape(shape, { cx, cy, r, fill: fill || 'none' }, stroke);
+        return this._elMap.get(shape.id).el;
+    }
+
+    path(d, fill, stroke, extra = {}) {
+        // `extra` (e.g. {tooltip}) merges into the shape descriptor only, not
+        // into DOM attributes — hitTest()/tooltip resolution reads it straight
+        // off `shape` (see _addTooltipListeners), it was never rendered as a
+        // real SVG attribute for rect/circle either. Previously missing here
+        // (CanvasRenderer.path already accepted it) — pie/doughnut wedges,
+        // candlestick bodies, and box-plot boxes all need path-level tooltips.
+        const shape = { type: 'path', d, fill, stroke, ...extra, id: `shape_${this._elMap.size}` };
+        // _createElement already applies stroke.color/width as real SVG attributes
+        // (see the `stroke` param handling above) — do NOT also set them as inline
+        // styles here. Setting style.fill = stroke.color previously clobbered any
+        // closed shape's real fill (e.g. graphDiagram's diamond node, filled with
+        // the group color but stroked white) with the stroke color instead, since
+        // inline styles win over attributes. Open paths (edge lines, fill:'none')
+        // never showed the bug since there's no enclosed area to paint either way.
+        const pathEl = this._createElement("path", { d, fill: fill || 'none' }, stroke);
+        this.svg.appendChild(pathEl);
+        this._elMap.set(shape.id, { el: pathEl, shape });
+        return pathEl;
+    }
+
+    /** Text width measured with a (shared, off-page) 2D canvas context; the estimate without a document. */
+    measureText(text, font = {}) {
+        if (typeof document === 'undefined' || typeof document.createElement !== 'function') return super.measureText(text, font);
+        const ctx = (SVGRenderer._measureContext ??= document.createElement('canvas').getContext?.('2d'));
+        if (!ctx) return super.measureText(text, font);
+        ctx.font = BaseRenderer.cssFont(font);
+        return ctx.measureText(String(text)).width;
+    }
+
+    text(text, x, y, options = {}) {
+        const shape = { type: 'text', text, x, y, ...options, id: `shape_${this._elMap.size}` };
+        const attrs = { x, y, fill: options.fill || 'black', 'font-family': options.fontFamily || 'sans-serif', 'font-size': options.fontSize || '12px', 'text-anchor': options.textAnchor || 'start' };
+        // Several call sites (graph-node initials/labels, table-node rows) pass
+        // verticalAlign:'middle' expecting the text to be vertically centred on
+        // its y-coordinate — this was silently ignored (SVG's default baseline
+        // is alphabetic, not middle), so multi-row content sat visibly low.
+        if (options.verticalAlign === 'middle') attrs['dominant-baseline'] = 'middle';
+        if (options.fontWeight) attrs['font-weight'] = options.fontWeight;
+        if (options.fontStyle) attrs['font-style'] = options.fontStyle;
+        // Every graphDiagram call site passes 'pointer-events':'none' on node
+        // initials/labels expecting clicks to fall through to the shape/badge
+        // underneath — silently dropped since it wasn't in this whitelist, so
+        // filled text always intercepted the click regardless of what callers
+        // asked for (surfaced by the new collapse-badge glyph sitting on top
+        // of its own circle and eating every click meant for it).
+        if (options['pointer-events']) attrs['pointer-events'] = options['pointer-events'];
+        // `rotation` is in radians (matches Canvas's ctx.rotate() convention) —
+        // convert to degrees for SVG's transform=rotate(deg, cx, cy). Every
+        // yAxisLabel call across the chart methods relies on this to render
+        // vertically instead of overlapping/clipping past the chart's left edge.
+        if (options.rotation) attrs.transform = `rotate(${options.rotation * 180 / Math.PI} ${x} ${y})`;
+        const el = this._createElement('text', attrs);
+        el.textContent = text;
+        this.svg.appendChild(el);
+        this._elMap.set(shape.id, { el, shape });
+        return el;
+    }
+
+    /** An SVG `<image>` — used for graphDiagram's `node.iconUrl` (a custom
+     *  icon/image file/data URI centred on a node, in place of the plain
+     *  initials text). `href` is set as the plain SVG2 attribute; every
+     *  renderer target this library ships against (real browsers, jsdom in
+     *  tests) resolves that without also needing the legacy `xlink:href`. */
+    image(href, x, y, width, height, options = {}) {
+        const shape = { type: 'image', href, x, y, width, height, ...options, id: `shape_${this._elMap.size}` };
+        const attrs = { href, x, y, width, height, preserveAspectRatio: options.preserveAspectRatio || 'xMidYMid meet' };
+        if (options['pointer-events']) attrs['pointer-events'] = options['pointer-events'];
+        const el = this._createElement('image', attrs);
+        this.svg.appendChild(el);
+        this._elMap.set(shape.id, { el, shape });
+        return el;
+    }
+
+    group(attributes = {}) {
+        const shape = { type: 'g', ...attributes, id: `shape_${this._elMap.size}` };
+        const el = this._createElement('g', attributes);
+        this.svg.appendChild(el);
+        this._elMap.set(shape.id, { el, shape });
+        return el;
+    }
+
+    hitTest(x, y) {
+        // This is a bit of a hack. We find the element and then iterate our map to find the shape.
+        // A more robust solution might use a WeakMap from element to shape.
+        //
+        // `x`/`y` are viewport coordinates (every caller in index.js passes
+        // event.clientX/clientY straight through) — document.elementFromPoint
+        // already takes coordinates in that same space. Adding this.svg's own
+        // getBoundingClientRect().left/top on top double-offset the query
+        // point by the canvas's on-page position, so hitTest silently queried
+        // the wrong spot on the page for any layout where the SVG isn't flush
+        // against the browser's top-left corner (i.e. basically always, once
+        // there's a toolbar/sidebar around it) — drag-start, the context
+        // menu, and tooltips all read this result directly, so all three
+        // misfired by exactly that offset. Zoom (the SVG's internal viewBox
+        // scale) doesn't factor in here at all: elementFromPoint operates on
+        // real rendered screen pixels, which already reflect whatever zoom is
+        // applied, so no CTM/zoom math belongs in this function.
+        const hitEl = this.svg.ownerDocument.elementFromPoint(x, y);
+        if (!hitEl) return null;
+        return SVGRenderer.resolveHit(this._elMap, hitEl);
+    }
+
+    /**
+     * Given the element under the cursor and the el→{el,shape} registry, picks
+     * which registered shape a hit resolves to. Split out from hitTest() so
+     * this candidate-selection logic is unit-testable without a real DOM
+     * (`hitEl`/registered `el`s just need a `.contains()` method).
+     *
+     * A graph node is drawn as an outer <g draggable nodeId tooltip> wrapping
+     * an inner shape primitive (circle/rect/path) plus text labels — each
+     * registered in _elMap separately, with the inner primitive inserted
+     * *before* the wrapping group. Since _elMap is iterated in insertion order
+     * and this used to return the *first* match, a click on the node's own
+     * visible body resolved to the inner primitive's bare shape (no
+     * draggable/tooltip/nodeId) instead of the wrapping group — silently
+     * breaking drag-start, the context menu, and hover tooltips (all of which
+     * read hitTest()'s result directly, unlike click-to-select which bubbles
+     * via a real DOM listener). Prefer a draggable node wrapper among the
+     * candidates when one is present; otherwise keep the original first-match
+     * behavior (legend markers etc. resolve via their own direct listeners
+     * already, not this method).
+     */
+    static resolveHit(elMap, hitEl) {
+        let first = null;
+        for (const { el, shape } of elMap.values()) {
+            if (el === hitEl || el.contains(hitEl)) {
+                if (!first) first = shape;
+                if (shape.draggable && shape.nodeId != null) return shape;
+            }
+        }
+        return first;
+    }
+
+    enterState(shape, stateName) {
+        this._elMap.get(shape.id)?.el.classList.add(stateName);
+    }
+
+    leaveState(shape, stateName) {
+        this._elMap.get(shape.id)?.el.classList.remove(stateName);
+    }
+
+    renderDiagram(diagram) {
+        // 20,20 padding matches this file's own DiagramNode.prototype.drawOn
+        // (railroadDiagram.js, the Canvas rendering path) — without a real
+        // starting x/y, every node's format() computes its own position as
+        // NaN (this used to be called with zero args, so x/y were undefined
+        // throughout the whole tree).
+        diagram.format(20, 20);
+
+        const group = this._createElement('g', {
+            'font-family': 'monospace',
+            'font-size': '12px'
+        });
+
+        // Collect every leaf first, then draw in a fixed path -> rect -> text
+        // paint order, rather than the tree's own traversal order. Connector
+        // lines (Sequence's backbone, ZeroOrMore's top line, Choice's arcs)
+        // legitimately run behind boxes they connect through — but walk()
+        // visits nodes in whatever order each FORMATTERS.* function happened
+        // to build its .item/.items — e.g. a Sequence's own backbone Path is
+        // appended (via addTo()) AFTER its child items are formatted, so it
+        // painted on top of and struck through every terminal/nonterminal
+        // box's text. A fixed paint order guarantees lines stay underneath
+        // opaque boxes and text stays readable on top, regardless of which
+        // order the diagram tree happens to store its children in.
+        const leaves = [];
+        diagram.walk(item => {
+            // The `if (item.type === 'rect'/'path'/'text')` chain below
+            // already correctly picks out only real leaf shapes — every
+            // intermediate DiagramNode-tree node (Sequence/Choice/Terminal/
+            // NonTerminal/...) has a .type that never matches any of those,
+            // so it's harmless to reach the chain and fall through. A prior
+            // `if (!item.width) return;` guard here was presumably meant to
+            // skip those same intermediate nodes, but 'text' and 'path'
+            // FakeSVG leaves never carry a .width at all (only 'rect' does —
+            // same as real SVG <text>/<path> elements), so it silently
+            // discarded every label and every connector line too.
+            if (item.type === 'rect' || item.type === 'path' || item.type === 'text') leaves.push(item);
+        });
+        const paintOrder = { path: 0, rect: 1, text: 2 };
+        leaves.sort((a, b) => paintOrder[a.type] - paintOrder[b.type]);
+        leaves.forEach(item => {
+            if (item.type === 'rect') {
+                // NonTerminal rects have no rx/ry (sharp corners, by design —
+                // see railroadDiagram.js's FORMATTERS.NonTerminal) — only
+                // pass them through when real, rather than setting a literal
+                // "undefined" string attribute value.
+                const extra = { parent: group };
+                if (item.rx != null) extra.rx = item.rx;
+                if (item.ry != null) extra.ry = item.ry;
+                this.rect(item.x, item.y, item.width, item.height, 'hsl(30,20%,95%)', { color: 'black', width: 2 }, extra);
+            } else if (item.type === 'path') {
+                const pathEl = this._createElement('path', { d: item.attrs.d }, { color: 'black', width: 3 });
+                pathEl.setAttribute('fill', 'none');
+                group.appendChild(pathEl);
+            } else if (item.type === 'text') {
+                const textEl = this._createElement('text', {
+                    x: item.x,
+                    y: item.y,
+                    'text-anchor': 'middle',
+                    fill: 'black'
+                });
+                if (item.attrs.class === 'comment') {
+                    textEl.setAttribute('font-style', 'italic');
+                } else if (item.type === 'NonTerminal') {
+                    textEl.setAttribute('font-weight', 'bold');
+                }
+                textEl.textContent = item.text;
+                group.appendChild(textEl);
+            }
+        });
+
+        // Every other SVGRenderer primitive (group()/rect()/circle()/...)
+        // appends itself to this.svg (or a specified parent) within its own
+        // method — this one built `group` and populated it via the walk
+        // callback's this.rect(...) calls (which do append into `group`,
+        // via the `parent: group` extra above), but never attached `group`
+        // to the actual <svg> itself, so nothing was ever visible.
+        this.svg.appendChild(group);
+
+        // A diagram's natural width is data-driven (however many rule
+        // elements it has) and routinely wider than a chart's fixed
+        // container box. Only the viewBox is updated to the content's real
+        // size — width/height stay at whatever they were set to at
+        // construction (the container's own clientWidth/clientHeight, same
+        // as every other chart type) — so the SVG's default
+        // preserveAspectRatio="xMidYMid meet" scales the whole diagram down
+        // to fit that fixed box, exactly like an <img>: no scrollbar, no
+        // clipping, just a smaller rendering for a wide diagram. (An
+        // earlier version of this also resized width/height to match the
+        // content, which fit the diagram at full native size but broke
+        // the page's CSS grid layout — a grid item's automatic minimum
+        // size is based on its content's intrinsic size unless something
+        // caps it — and even with that capped, still needed a scrollbar to
+        // reach the full content. Not resizing width/height avoids both.)
+        const w = diagram.width + 40, h = diagram.height + 40;
+        this.svg.setAttribute('viewBox', `0 0 ${w} ${h}`);
+
+        return group;
+    }
+
+    /**
+     * Add a <linearGradient> to <defs> and return its url(#id) reference.
+     * @param {string} id
+     * @param {Array<{offset: string|number, color: string, opacity?: number}>} stops
+     * @param {{x1?: string, y1?: string, x2?: string, y2?: string}} [options]
+     * @returns {string} url(#id)
+     */
+    linearGradient(id, stops = [], { x1 = '0%', y1 = '0%', x2 = '0%', y2 = '100%' } = {}) {
+        const existing = this.svg?.querySelector ? this.svg.querySelector(`#${id}`) : null;
+        if (existing) return `url(#${id})`;
+        const grad = this._createElement('linearGradient', { id, x1, y1, x2, y2 });
+        for (const stop of stops) {
+            const offset = typeof stop.offset === 'number' ? `${stop.offset * 100}%` : stop.offset;
+            const attrs = { offset, 'stop-color': stop.color };
+            if (stop.opacity !== undefined) attrs['stop-opacity'] = String(stop.opacity);
+            grad.appendChild(this._createElement('stop', attrs));
+        }
+        this.defs?.appendChild(grad);
+        return `url(#${id})`;
+    }
 }