@peter.prib/renderengine 0.14.0 → 0.15.0

package/src/charting/charts/RidgelineChart.js

@@ -0,0 +1,113 @@
+import { Axis } from '../Axis.js';
+import { Statistics } from '../Statistics.js';
+import { GroupedDistributionChart } from './GroupedDistributionChart.js';
+
+/**
+ * RidgelineChart (Joy Plot) — vertically staggered, partially overlapping
+ * Gaussian-KDE density curves (`Array<{label, values: number[]}>`, the same
+ * data contract as `BoxPlotChart`, `DensityChart`, and `ViolinChart`).
+ *
+ * Reuses `GroupedDistributionChart` for cartesian setup and value-domain math
+ * and `Statistics.kernelDensityEstimate` for smooth density estimation.
+ */
+export class RidgelineChart extends GroupedDistributionChart {
+    static chartType = 'ridgeline';
+
+    _render() {
+        if (!Array.isArray(this.data) || !this.data.length) return;
+        this._setup();
+        this._domain = this._computeDomain();
+
+        const options = this.options;
+        const {
+            overlap = 0.65,
+            fillOpacity = 0.74,
+            showMedian = true,
+        } = options;
+
+        const data = this.data;
+        const n = data.length;
+        const leftPad = 56;
+        const plotX = this._plotBox.x + leftPad;
+        const plotW = Math.max(40, this._plotBox.width - leftPad);
+        const plotY = this._plotBox.y;
+        const plotH = this._plotBox.height;
+
+        // Allocate vertical lanes with headroom for the top ridge's peak
+        const rowStep = plotH / (n + overlap);
+        const maxPeakH = rowStep * (1 + Math.max(0, overlap));
+        const { vMin, vMax, range } = this._domain;
+        const toX = v => plotX + ((v - vMin) / range) * plotW;
+
+        // Draw bottom X-axis and nice ticks
+        this.renderer.path(`M${plotX},${plotY + plotH} L${plotX + plotW},${plotY + plotH}`, 'none', {
+            color: 'black', width: 1,
+        });
+        const ticks = Axis.niceTicks(range, 5).map(t => vMin + t).filter(t => t <= vMax + 1e-6);
+        for (const tick of ticks) {
+            const tx = toX(tick);
+            this.renderer.path(`M${tx},${plotY} L${tx},${plotY + plotH}`, 'none', {
+                color: '#eee', width: 1, dasharray: '3,3',
+            });
+            this.renderer.text(Axis.formatValue(tick), tx, plotY + plotH + 16, {
+                textAnchor: this.renderer.centerTextAnchor, fontSize: '10px', fill: '#666',
+            });
+        }
+
+        // Render from top row (i=0) to bottom row (i=n-1) so lower ridges
+        // naturally overlap in front of upper ridges (the classic Joy Plot look).
+        data.forEach((d, i) => {
+            const values = Array.isArray(d.values) ? d.values : [];
+            if (!values.length) return;
+            const baselineY = plotY + (i + 1 + overlap * 0.35) * rowStep;
+            const clampedBaselineY = Math.min(plotY + plotH, baselineY);
+            const color = this._palette.colorAt(i);
+            const curve = Statistics.kernelDensityEstimate(values, { min: vMin, max: vMax });
+            const maxDensity = Math.max(...curve.map(p => p.density)) || 1;
+
+            const pts = curve.map(p => ({
+                px: toX(p.x),
+                py: clampedBaselineY - (p.density / maxDensity) * maxPeakH,
+            }));
+
+            const sorted = [...values].sort((a, b) => a - b);
+            const median = Statistics.quantile(sorted, 0.5);
+            const tooltip = `${d.label}: n=${values.length}, median=${Axis.formatValue(median)}`;
+
+            // Baseline guide + category label on left
+            this.renderer.path(`M${plotX},${clampedBaselineY} L${plotX + plotW},${clampedBaselineY}`, 'none', {
+                color: '#ddd', width: 1,
+            });
+            this.renderer.text(d.label, plotX - 8, clampedBaselineY - 2, {
+                textAnchor: 'end', verticalAlign: 'middle', fontSize: '11px', fontWeight: '600', fill: '#333',
+            });
+
+            // Closed area path + crisp upper ridge stroke
+            const areaPath = `M${pts[0].px},${clampedBaselineY} L`
+                + pts.map(p => `${p.px},${p.py}`).join(' L')
+                + ` L${pts[pts.length - 1].px},${clampedBaselineY} Z`;
+            const ridgePath = 'M' + pts.map(p => `${p.px},${p.py}`).join(' L');
+
+            const areaEl = this._datum(this.renderer.path(areaPath, color, null, {
+                'fill-opacity': fillOpacity, tooltip,
+            }), { label: d.label, series: d.label, value: median });
+            const strokeEl = this.renderer.path(ridgePath, 'none', {
+                color: this._palette.darken(color, 0.22), width: 2,
+            }, { tooltip });
+
+            const groupEls = [areaEl, strokeEl];
+            if (showMedian) {
+                const mx = toX(median);
+                // Interpolate density at median for median tick height
+                const nearest = curve.reduce((best, p) => Math.abs(p.x - median) < Math.abs(best.x - median) ? p : best, curve[0]);
+                const myTop = clampedBaselineY - ((nearest?.density ?? maxDensity * 0.5) / maxDensity) * maxPeakH;
+                const medLine = this.renderer.path(`M${mx},${clampedBaselineY} L${mx},${myTop}`, 'none', {
+                    color: '#ffffff', width: 1.8, dasharray: '3,2',
+                });
+                groupEls.push(medLine);
+            }
+
+            this._wireHoverTransform(groupEls, { dx: 0, dy: -4 });
+        });
+    }
+}

package/src/charting/charts/SankeyDiagram.js

@@ -83,8 +83,12 @@ export class SankeyDiagram extends Chart {
             let cy = y + (height - totalH) / 2;
             levelNodes.forEach(n => {
                 n.x = x + n.level * levelWidth;
-                n.y = cy;
                 n.h = n.value * scale;
+                if (options.nodePositions && options.nodePositions[n.id] != null) {
+                    n.y = options.nodePositions[n.id];
+                } else {
+                    n.y = cy;
+                }
                 cy += n.h + nodePadding;
             });
         });
@@ -103,6 +107,7 @@ export class SankeyDiagram extends Chart {
         }
 
         // Draw links first so nodes sit on top.
+        const linkRecords = [];
         nodes.forEach(n => {
             let outY = n.y;
             n.out.forEach(l => {
@@ -113,22 +118,140 @@ export class SankeyDiagram extends Chart {
                 const linkH = l.value * scale;
                 const path = this._linkPath(n.x + nodeWidth, outY + linkH / 2, t.x, inY + linkH / 2, linkH);
                 const { r, g, b: bl } = palette.hexToRgb(n.color);
-                this._datum(this.renderer.path(path, `rgba(${r},${g},${bl},${linkOpacity})`, null, {
+                const el = this._datum(this.renderer.path(path, `rgba(${r},${g},${bl},${linkOpacity})`, null, {
                     tooltip: `${n.label} → ${t.label}: ${l.value}`,
                 }), { label: n.label, series: t.label });
+                linkRecords.push({ el, source: n, target: t, link: l, r, g, b: bl, value: l.value });
                 outY += linkH;
             });
         });
 
         // Draw nodes.
+        const nodeRecords = [];
         nodes.forEach(n => {
-            this._datum(this.renderer.rect(n.x, n.y, nodeWidth, Math.max(1, n.h), n.color, null, {
+            const el = this._datum(this.renderer.rect(n.x, n.y, nodeWidth, Math.max(1, n.h), n.color, null, {
                 tooltip: `${n.label}: ${n.value}`,
             }), { label: n.label });
-            this.renderer.text(n.label, n.x + nodeWidth / 2, n.y - 6, {
+            const textEl = this.renderer.text(n.label, n.x + nodeWidth / 2, n.y - 6, {
                 textAnchor: 'middle', fontSize: '10px', fill: '#333',
             });
+            nodeRecords.push({ el, textEl, node: n });
         });
+
+        this._wireFlowHover(nodeRecords, linkRecords, linkOpacity, { y, height, nodeWidth, scale, options });
+    }
+
+    _wireFlowHover(nodeRecords, linkRecords, baseOpacity, layoutContext = {}) {
+        if (this.renderer?.supportsSceneGraph !== true || this.options?.hoverEffect === false) return;
+        const { y = 0, height = 400, nodeWidth = 16, scale = 1, options = {} } = layoutContext;
+
+        const updateLinks = () => {
+            linkRecords.forEach(rec => {
+                const s = rec.source;
+                const t = rec.target;
+                let outY = s.y;
+                for (let k = 0; k < s.out.indexOf(rec.link); k++) outY += s.out[k].value * scale;
+                const inIndex = t.in.findIndex(inL => inL.source === s);
+                let inY = t.y;
+                for (let k = 0; k < inIndex; k++) inY += t.in[k].value * scale;
+                const linkH = rec.value * scale;
+                const path = this._linkPath(s.x + nodeWidth, outY + linkH / 2, t.x, inY + linkH / 2, linkH);
+                rec.el?.setAttribute?.('d', path);
+            });
+        };
+
+        const setLinkVisual = (rec, alpha, shadow = '') => {
+            if (!rec.el) return;
+            rec.el.setAttribute?.('fill', `rgba(${rec.r},${rec.g},${rec.b},${alpha})`);
+            if (rec.el.style) rec.el.style.filter = shadow;
+        };
+        const resetAll = () => {
+            for (const rec of linkRecords) setLinkVisual(rec, baseOpacity, '');
+            for (const nRec of nodeRecords) {
+                if (nRec.el?.style) {
+                    nRec.el.style.opacity = '';
+                    nRec.el.style.filter = '';
+                }
+            }
+        };
+
+        for (const nRec of nodeRecords) {
+            if (typeof nRec.el?.addEventListener !== 'function') continue;
+            nRec.el._hoverWired = true;
+            if (nRec.el.style) {
+                nRec.el.style.transition = 'opacity 0.2s ease, filter 0.2s ease';
+                nRec.el.style.cursor = options.draggable !== false ? 'ns-resize' : 'pointer';
+            }
+
+            if (options.draggable !== false) {
+                nRec.el.addEventListener('pointerdown', (e) => {
+                    if (e.button !== 0) return;
+                    e.preventDefault();
+                    const startClientY = e.clientY;
+                    const initialY = nRec.node.y;
+                    const onPointerMove = (me) => {
+                        const dy = me.clientY - startClientY;
+                        const newY = Math.max(y, Math.min(y + height - nRec.node.h, initialY + dy));
+                        nRec.node.y = newY;
+                        nRec.el?.setAttribute?.('y', newY);
+                        nRec.textEl?.setAttribute?.('y', newY - 6);
+                        updateLinks();
+                        options.onNodeDrag?.(nRec.node.id, newY);
+                    };
+                    const onPointerUp = () => {
+                        window.removeEventListener('pointermove', onPointerMove);
+                        window.removeEventListener('pointerup', onPointerUp);
+                    };
+                    window.addEventListener('pointermove', onPointerMove);
+                    window.addEventListener('pointerup', onPointerUp);
+                });
+            }
+
+            nRec.el.addEventListener('mouseenter', () => {
+                const connectedNodes = new Set([nRec.node]);
+                for (const rec of linkRecords) {
+                    const hit = rec.source === nRec.node || rec.target === nRec.node;
+                    if (hit) {
+                        connectedNodes.add(rec.source);
+                        connectedNodes.add(rec.target);
+                        setLinkVisual(rec, Math.min(0.88, baseOpacity + 0.38), 'drop-shadow(0 2px 5px rgba(0,0,0,0.2))');
+                    } else {
+                        setLinkVisual(rec, Math.max(0.1, baseOpacity * 0.28), '');
+                    }
+                }
+                for (const other of nodeRecords) {
+                    if (!other.el?.style) continue;
+                    other.el.style.opacity = connectedNodes.has(other.node) ? '1' : '0.45';
+                    other.el.style.filter = other.node === nRec.node ? 'drop-shadow(0 3px 6px rgba(0,0,0,0.25))' : '';
+                }
+            });
+            nRec.el.addEventListener('mouseleave', resetAll);
+        }
+
+        for (const rec of linkRecords) {
+            if (typeof rec.el?.addEventListener !== 'function') continue;
+            rec.el._hoverWired = true;
+            if (rec.el.style) {
+                rec.el.style.transition = 'filter 0.2s ease, opacity 0.2s ease';
+                rec.el.style.cursor = 'pointer';
+            }
+            rec.el.addEventListener('mouseenter', () => {
+                for (const other of linkRecords) {
+                    if (other === rec) {
+                        setLinkVisual(other, Math.min(0.9, baseOpacity + 0.42), 'drop-shadow(0 3px 6px rgba(0,0,0,0.24))');
+                    } else {
+                        setLinkVisual(other, Math.max(0.1, baseOpacity * 0.28), '');
+                    }
+                }
+                for (const nRec of nodeRecords) {
+                    if (!nRec.el?.style) continue;
+                    const hit = nRec.node === rec.source || nRec.node === rec.target;
+                    nRec.el.style.opacity = hit ? '1' : '0.45';
+                    nRec.el.style.filter = hit ? 'drop-shadow(0 2px 5px rgba(0,0,0,0.22))' : '';
+                }
+            });
+            rec.el.addEventListener('mouseleave', resetAll);
+        }
     }
 
     _assignLevels(nodes) {

package/src/charting/charts/ScatterChart.js

@@ -4,6 +4,7 @@ import { ChartBox, ChartLabels } from '../ChartBox.js';
 import { ColorPalette } from '../ColorPalette.js';
 import { ChartData } from '../ChartData.js';
 import { ErrorBars } from '../ErrorBars.js';
+import { Annotations } from '../Annotations.js';
 
 /**
  * ScatterChart — x/y point scatter plot with optional categorical coloring.
@@ -59,6 +60,9 @@ export class ScatterChart extends Chart {
 
         this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
 
+        // Threshold bands
+        Annotations.drawThresholdBands(this.renderer, plotBox, options.thresholdBands, { toY });
+
         if (referenceLine) {
             let from, to;
             if (referenceLine === true) {
@@ -72,6 +76,15 @@ export class ScatterChart extends Chart {
                 line?.setAttribute?.('stroke-dasharray', '4 3');
             }
         }
+        if (options.referenceLines) {
+            Annotations.drawReferenceLines(this.renderer, plotBox, options.referenceLines, { toX, toY });
+        }
+
+        // Linear regression trendline
+        if (options.trendline) {
+            const numericPts = data.filter(d => typeof d.x === 'number' && typeof d.y === 'number');
+            Annotations.drawTrendline(this.renderer, plotBox, numericPts, options.trendline, { toX, toY, xMin, xMax });
+        }
 
         data.forEach(d => {
             const cx = toX(d.x);

package/src/charting/charts/ScatterMatrixChart.js

@@ -0,0 +1,119 @@
+import { Axis } from '../Axis.js';
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { Legend } from '../Legend.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { Statistics } from '../Statistics.js';
+
+/**
+ * ScatterMatrixChart (SPLOM) — N x N grid of pairwise scatter plots for
+ * multi-variable numeric datasets, with univariate histograms or KDE curves
+ * on the diagonal cells.
+ */
+export class ScatterMatrixChart extends Chart {
+    static chartType = 'splom';
+
+    _render() {
+        const data = this.data;
+        if (!Array.isArray(data) || !data.length) return;
+
+        const options = this.options;
+        const box = ChartBox.fromRenderer(this.renderer);
+        const {
+            x = box.x, y = box.y, width: optWidth, height = box.height,
+            title, colors, colorCol, dotRadius = 3,
+        } = options;
+
+        // Auto-detect numeric dimensions if not explicitly passed
+        const dimensions = options.dimensions ?? Object.keys(data[0]).filter(k => {
+            if (k === colorCol || k === 'category' || k === 'label') return false;
+            return typeof data[0][k] === 'number';
+        });
+
+        const N = dimensions.length;
+        if (N < 2) return;
+
+        // Group categories for coloring
+        const categoryKey = colorCol ?? ('category' in data[0] ? 'category' : null);
+        const categories = categoryKey ? [...new Set(data.map(d => String(d[categoryKey])))] : [];
+        const palette = new ColorPalette(colors);
+        const legendItems = categories.map((cat, i) => ({ label: cat, color: palette.colorAt(i), marker: 'circle' }));
+
+        const width = optWidth ?? (categories.length > 1
+            ? Legend.plotWidthBeside({ x, width: box.width }, this.renderer.width, { items: legendItems })
+            : box.width);
+        const plotBox = { x, y, width, height };
+
+        new ChartLabels({ title }).draw(this.renderer, plotBox);
+
+        // Precompute min/max range for each dimension
+        const dimStats = new Map();
+        for (const dim of dimensions) {
+            const vals = data.map(d => Number(d[dim]) || 0);
+            const min = Math.min(...vals);
+            const max = Math.max(...vals);
+            dimStats.set(dim, { min, max, range: (max - min) || 1, vals });
+        }
+
+        const cellPadding = 6;
+        const cellW = (width - cellPadding * (N - 1)) / N;
+        const cellH = (height - cellPadding * (N - 1)) / N;
+
+        for (let row = 0; row < N; row++) {
+            const yDim = dimensions[row];
+            const yStat = dimStats.get(yDim);
+            const cellY = y + row * (cellH + cellPadding);
+
+            for (let col = 0; col < N; col++) {
+                const xDim = dimensions[col];
+                const xStat = dimStats.get(xDim);
+                const cellX = x + col * (cellW + cellPadding);
+
+                // Cell boundary
+                this.renderer.rect(cellX, cellY, cellW, cellH, 'rgba(0,0,0,0.02)', { color: '#ddd', width: 1 });
+
+                if (row === col) {
+                    // Diagonal: Univariate KDE curve or histogram + dimension label
+                    const vals = xStat.vals;
+                    const curve = Statistics.kernelDensityEstimate(vals, { min: xStat.min, max: xStat.max });
+                    const maxDensity = Math.max(...curve.map(p => p.density)) || 1;
+                    const pts = curve.map(p => ({
+                        px: cellX + ((p.x - xStat.min) / xStat.range) * cellW,
+                        py: cellY + cellH - 4 - (p.density / maxDensity) * (cellH * 0.65),
+                    }));
+                    const curvePath = 'M' + pts.map(p => `${p.px},${p.py}`).join(' L');
+                    const areaPath = curvePath + ` L${cellX + cellW},${cellY + cellH - 4} L${cellX},${cellY + cellH - 4} Z`;
+
+                    this.renderer.path(areaPath, 'rgba(79, 142, 247, 0.2)', null);
+                    this.renderer.path(curvePath, 'none', { color: '#4f8ef7', width: 1.5 });
+
+                    // Centered dimension label
+                    this.renderer.text(xDim, cellX + cellW / 2, cellY + 16, {
+                        textAnchor: this.renderer.centerTextAnchor, fontSize: '11px', fontWeight: 'bold', fill: '#222',
+                    });
+                } else {
+                    // Off-diagonal: Pairwise scatter plot
+                    data.forEach((d, idx) => {
+                        const valX = Number(d[xDim]) || 0;
+                        const valY = Number(d[yDim]) || 0;
+                        const px = cellX + ((valX - xStat.min) / xStat.range) * cellW;
+                        const py = cellY + cellH - ((valY - yStat.min) / yStat.range) * cellH;
+
+                        const catIdx = categoryKey ? categories.indexOf(String(d[categoryKey])) : 0;
+                        const color = palette.colorAt(catIdx !== -1 ? catIdx : 0);
+                        const label = d.label ?? `#${idx + 1}`;
+                        const tooltip = `${label} (${xDim}: ${Axis.formatValue(valX)}, ${yDim}: ${Axis.formatValue(valY)})`;
+
+                        this._datum(this.renderer.circle(px, py, dotRadius, color, { color: '#ffffff', width: 0.8 }, {
+                            tooltip,
+                        }), { label, x: valX, y: valY });
+                    });
+                }
+            }
+        }
+
+        if (categories.length > 1) {
+            Legend.beside({ x, y, width }, this.renderer.width, { items: legendItems }).draw(this.renderer);
+        }
+    }
+}

package/src/charting/charts/SlopegraphChart.js

@@ -0,0 +1,205 @@
+import { Chart } from '../Chart.js';
+import { Axis } from '../Axis.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { DumbbellChart } from './DumbbellChart.js';
+
+/**
+ * SlopegraphChart — two (or K) vertical parallel axes connecting categories'
+ * values across time points or stages (`Array<{label, start, end}>`,
+ * `Array<{label, values: number[]}>`, or multi-series `Array<{name, values}>`).
+ *
+ * Features direct left/right labels with automatic vertical collision avoidance
+ * and interactive hover highlighting that elevates the hovered category's
+ * trajectory while dimming non-hovered lines.
+ */
+export class SlopegraphChart extends Chart {
+    static chartType = 'slopegraph';
+
+    /**
+     * Normalize input into `{ stageLabels: string[], series: Array<{label: string, values: number[], color?: string}> }`.
+     */
+    static normalizeData(data, options = {}) {
+        if (!Array.isArray(data) || !data.length) {
+            return { stageLabels: options.stageLabels ?? ['Start', 'End'], series: [] };
+        }
+
+        const first = data[0];
+        // Case 1: Array<{label, values: number[]}> (e.g. K stages per category)
+        if (first && typeof first === 'object' && Array.isArray(first.values) && typeof first.values[0] === 'number' && !('name' in first && !('label' in first))) {
+            const k = Math.max(2, ...data.map(d => d.values?.length ?? 0));
+            const stageLabels = options.stageLabels ?? Array.from({ length: k }, (_, i) => `Stage ${i + 1}`);
+            const series = data.map((d, i) => ({
+                label: String(d.label ?? d.name ?? `#${i + 1}`),
+                values: Array.from({ length: k }, (_, j) => Number(d.values?.[j] ?? 0) || 0),
+                color: d.color,
+            }));
+            return { stageLabels, series };
+        }
+
+        // Case 2: Multi-series [{ name: '2025', values: [{label, value}, ...] }, { name: '2026', values: [...] }]
+        if (first && typeof first === 'object' && Array.isArray(first.values) && ('name' in first || typeof first.values[0] === 'object')) {
+            const stageLabels = options.stageLabels ?? data.map((s, i) => String(s.name ?? `Stage ${i + 1}`));
+            const catCount = Math.max(0, ...data.map(s => s.values?.length ?? 0));
+            const series = [];
+            for (let c = 0; c < catCount; c++) {
+                let label = `#${c + 1}`;
+                const values = data.map(s => {
+                    const v = s.values?.[c];
+                    if (typeof v === 'object' && v !== null) {
+                        if (v.label != null) label = String(v.label);
+                        return Number(v.value) || 0;
+                    }
+                    return Number(v) || 0;
+                });
+                series.push({ label, values });
+            }
+            return { stageLabels, series };
+        }
+
+        // Case 3: {label, start, end} (or before/after, from/to)
+        const { items, startLabel, endLabel } = DumbbellChart.normalizeData(data, options);
+        const stageLabels = options.stageLabels ?? [startLabel, endLabel];
+        const series = items.map(it => ({
+            label: it.label,
+            values: [it.start, it.end],
+        }));
+        return { stageLabels, series };
+    }
+
+    /**
+     * Nudge label Y positions (`Array<{y: number, ...}>`) apart so adjacent
+     * labels stay at least `minGap` pixels apart within `[minY, maxY]`.
+     */
+    static resolveLabelCollisions(entries, minGap = 13, minY = 0, maxY = 1000) {
+        const sorted = [...entries].sort((a, b) => a.y - b.y);
+        for (let pass = 0; pass < 4; pass++) {
+            for (let i = 1; i < sorted.length; i++) {
+                const overlap = (sorted[i - 1].y + minGap) - sorted[i].y;
+                if (overlap > 0) {
+                    sorted[i - 1].y = Math.max(minY, sorted[i - 1].y - overlap * 0.5);
+                    sorted[i].y = Math.min(maxY, sorted[i].y + overlap * 0.5);
+                }
+            }
+        }
+        return sorted;
+    }
+
+    _render() {
+        const { stageLabels, series } = SlopegraphChart.normalizeData(this.data, this.options);
+        if (!series.length || stageLabels.length < 2) return;
+
+        const box = ChartBox.fromRenderer(this.renderer);
+        const options = this.options;
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            title, colors, dotRadius = 5,
+        } = options;
+
+        const palette = new ColorPalette(colors);
+        const sidePad = Math.min(115, Math.max(72, width * 0.22));
+        const topPad = 24;
+        const plotBox = {
+            x: x + sidePad,
+            y: y + topPad,
+            width: Math.max(40, width - sidePad * 2),
+            height: Math.max(40, height - topPad),
+        };
+
+        new ChartLabels({ title }).draw(this.renderer, { x, y, width, height });
+
+        const allVals = series.flatMap(s => s.values);
+        const vMin = Math.min(...allVals);
+        const vMax = Math.max(...allVals);
+        const vRange = (vMax - vMin) || 1;
+        const toY = v => plotBox.y + plotBox.height - ((v - vMin) / vRange) * plotBox.height;
+
+        const k = stageLabels.length;
+        const stageX = stageLabels.map((_, j) => plotBox.x + (j / (k - 1)) * plotBox.width);
+
+        // Draw vertical stage axes and headers
+        stageX.forEach((sx, j) => {
+            this.renderer.path(`M${sx},${plotBox.y - 6} L${sx},${plotBox.y + plotBox.height + 6}`, 'none', {
+                color: '#ccd6e0', width: 1.5, dasharray: '4,3',
+            });
+            this.renderer.text(stageLabels[j], sx, plotBox.y - 14, {
+                textAnchor: this.renderer.centerTextAnchor, fontSize: '11px', fontWeight: 'bold', fill: '#333',
+            });
+        });
+
+        // Precompute collision-resolved left & right label positions
+        const leftLabels = SlopegraphChart.resolveLabelCollisions(
+            series.map((s, i) => ({ idx: i, y: toY(s.values[0]), text: `${s.label} (${Axis.formatValue(s.values[0])})` })),
+            13, plotBox.y, plotBox.y + plotBox.height
+        );
+        const rightLabels = SlopegraphChart.resolveLabelCollisions(
+            series.map((s, i) => ({
+                idx: i,
+                y: toY(s.values[k - 1]),
+                text: `${Axis.formatValue(s.values[k - 1])}  ${s.label}`,
+            })),
+            13, plotBox.y, plotBox.y + plotBox.height
+        );
+        const leftYByIdx = new Map(leftLabels.map(l => [l.idx, l]));
+        const rightYByIdx = new Map(rightLabels.map(l => [l.idx, l]));
+
+        const seriesGroups = [];
+
+        series.forEach((s, i) => {
+            const color = s.color ?? palette.colorAt(i);
+            const pts = s.values.map((v, j) => ({ x: stageX[j], y: toY(v), v }));
+            const delta = s.values[k - 1] - s.values[0];
+            const sign = delta > 0 ? '+' : '';
+            const tooltip = `${s.label}: ${s.values.map((v, j) => `${stageLabels[j]}=${Axis.formatValue(v)}`).join(' → ')} (${sign}${Axis.formatValue(delta)})`;
+
+            const pathD = 'M' + pts.map(p => `${p.x},${p.y}`).join(' L');
+            const lineEl = this._datum(this.renderer.path(pathD, 'none', {
+                color, width: 2.5, 'stroke-linecap': 'round', 'stroke-linejoin': 'round',
+            }, { tooltip }), { label: s.label, series: s.label, value: s.values[k - 1] });
+
+            const dotEls = pts.map((p, j) => this._datum(this.renderer.circle(p.x, p.y, dotRadius, color, {
+                color: '#ffffff', width: 1.5,
+            }, { tooltip: `${s.label} (${stageLabels[j]}): ${Axis.formatValue(p.v)}` }), {
+                label: stageLabels[j], series: s.label, value: p.v,
+            }));
+
+            const leftInfo = leftYByIdx.get(i);
+            const rightInfo = rightYByIdx.get(i);
+            const leftLbl = this.renderer.text(leftInfo.text, stageX[0] - 10, leftInfo.y, {
+                textAnchor: 'end', verticalAlign: 'middle', fontSize: '10px', fontWeight: '600', fill: color,
+            });
+            const rightLbl = this.renderer.text(rightInfo.text, stageX[k - 1] + 10, rightInfo.y, {
+                textAnchor: 'start', verticalAlign: 'middle', fontSize: '10px', fontWeight: '600', fill: color,
+            });
+
+            seriesGroups.push({ idx: i, lineEl, dotEls, leftLbl, rightLbl, allEls: [lineEl, ...dotEls, leftLbl, rightLbl] });
+        });
+
+        // Interactive hover highlighting: emphasize hovered trajectory, dim non-hovered
+        const highlightSeries = (activeIdx) => {
+            for (const g of seriesGroups) {
+                const isHovered = activeIdx === null || g.idx === activeIdx;
+                if (g.lineEl?.setAttribute) {
+                    g.lineEl.setAttribute('stroke-width', activeIdx !== null && g.idx === activeIdx ? '4' : '2.5');
+                }
+                for (const el of g.allEls) {
+                    if (!el?.style) continue;
+                    el.style.transition = 'opacity 0.16s ease, filter 0.16s ease';
+                    el.style.opacity = isHovered ? '1' : '0.22';
+                    el.style.filter = (activeIdx !== null && g.idx === activeIdx)
+                        ? 'drop-shadow(0 3px 6px rgba(0,0,0,0.28))'
+                        : '';
+                }
+            }
+        };
+
+        for (const g of seriesGroups) {
+            for (const el of g.allEls) {
+                if (!el?.addEventListener) continue;
+                el.style.cursor = 'pointer';
+                el.addEventListener('mouseenter', () => highlightSeries(g.idx));
+                el.addEventListener('mouseleave', () => highlightSeries(null));
+            }
+        }
+    }
+}