@svgrid/grid 1.0.2 → 1.1.0

package/dist/chart.js

@@ -1,3 +1,6 @@
+/** Cycle used when `ChartSpec.patternFallback` is true and a series has no
+ *  explicit `pattern` set. Skips `'solid'` so every series gets a texture. */
+const PATTERN_CYCLE = ['stripe', 'crosshatch', 'dots', 'diagonal'];
 export const DEFAULT_PALETTE = [
     '#2563eb',
     '#16a34a',
@@ -23,6 +26,261 @@ function niceNum(range, roundIt) {
         nf = f <= 1 ? 1 : f <= 2 ? 2 : f <= 5 ? 5 : 10;
     return nf * Math.pow(10, exp);
 }
+// ---- Color helpers for heatmap / pattern fills ----------------------
+/** Built-in sequential ramp (light cyan -> deep blue), perception-friendly. */
+const SEQUENTIAL_STOPS = ['#eff6ff', '#bfdbfe', '#60a5fa', '#2563eb', '#1e3a8a'];
+/** Built-in diverging ramp (red -> neutral -> blue). Use for signed data. */
+const DIVERGING_STOPS = ['#b91c1c', '#fca5a5', '#f1f5f9', '#93c5fd', '#1d4ed8'];
+/** Dark-theme ramps. The low (sequential) / neutral (diverging) end sits just
+ *  above the dark grid surface instead of near-white, so empty / low cells read
+ *  as "cold" rather than as glaring white rectangles. */
+const SEQUENTIAL_STOPS_DARK = ['#1c2c4d', '#1d4ed8', '#3b82f6', '#60a5fa', '#bae6fd'];
+const DIVERGING_STOPS_DARK = ['#f87171', '#b91c1c', '#222b3d', '#1d4ed8', '#60a5fa'];
+function resolveColorScale(scale, vMin, vMax, theme = 'light') {
+    if (Array.isArray(scale) && scale.length >= 2)
+        return scale;
+    const dark = theme === 'dark';
+    if (scale === 'diverging' || (scale == null && vMin < 0 && vMax > 0)) {
+        return dark ? DIVERGING_STOPS_DARK : DIVERGING_STOPS;
+    }
+    return dark ? SEQUENTIAL_STOPS_DARK : SEQUENTIAL_STOPS;
+}
+/** Sample a hex color from an array of hex stops at fractional position t.
+ *  Linearly interpolates between the two nearest stops in RGB space. */
+export function sampleGradient(stops, t) {
+    if (!stops.length)
+        return '#888';
+    const clamped = Math.max(0, Math.min(1, t));
+    if (stops.length === 1)
+        return stops[0];
+    const pos = clamped * (stops.length - 1);
+    const i = Math.floor(pos);
+    const frac = pos - i;
+    const a = hexToRgb(stops[i]);
+    const b = hexToRgb(stops[Math.min(stops.length - 1, i + 1)]);
+    if (!a || !b)
+        return stops[i] ?? '#888';
+    const lerp = (x, y) => Math.round(x + (y - x) * frac);
+    const toHex = (n) => n.toString(16).padStart(2, '0');
+    return '#' + toHex(lerp(a.r, b.r)) + toHex(lerp(a.g, b.g)) + toHex(lerp(a.b, b.b));
+}
+function hexToRgb(hex) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 16);
+    return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+}
+/** Pick a black or white text color that has the better contrast against
+ *  the given background. Uses the WCAG relative-luminance heuristic. */
+export function pickContrastText(bgHex) {
+    const rgb = hexToRgb(bgHex);
+    if (!rgb)
+        return '#0f172a';
+    const lin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    const L = 0.2126 * lin(rgb.r) + 0.7152 * lin(rgb.g) + 0.0722 * lin(rgb.b);
+    return L > 0.5 ? '#0f172a' : '#ffffff';
+}
+/** Pick the largest power of 10 that fits at the bottom of [min,max], and
+ *  the smallest that covers the top, then enumerate decade boundaries. Used
+ *  by log-scale axes (yScale: 'log'). */
+export function niceLogScale(min, max) {
+    // Only positive values are plottable on a log scale; callers should
+    // strip non-positive values before passing them in.
+    if (!Number.isFinite(min) || min <= 0)
+        min = 1;
+    if (!Number.isFinite(max) || max <= min)
+        max = min * 10;
+    const lo = Math.floor(Math.log10(min));
+    const hi = Math.ceil(Math.log10(max));
+    const ticks = [];
+    for (let p = lo; p <= hi; p += 1)
+        ticks.push(Math.pow(10, p));
+    return { min: Math.pow(10, lo), max: Math.pow(10, hi), step: 10, ticks };
+}
+/** Map a value to a fractional position [0..1] across the axis domain.
+ *  Pass the appropriate fn into projection code so linear / log share the
+ *  same plumbing. Returns null for non-positive values on log. */
+function project(value, min, max, isLog) {
+    if (!Number.isFinite(value))
+        return null;
+    if (isLog) {
+        if (value <= 0 || min <= 0)
+            return null;
+        return (Math.log10(value) - Math.log10(min)) / (Math.log10(max) - Math.log10(min));
+    }
+    return (value - min) / (max - min);
+}
+// ---- Overlay math: trendline + moving averages -----------------------
+/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
+ *  Returns the fitted value at each x index, or NaN where the source value
+ *  was non-finite. */
+/** Build an SVG path from a list of (x,y) pairs, optionally smoothed via
+ *  monotone cubic interpolation (preserves local extrema - no overshoots).
+ *  Breaks the path at `defined === false` gaps. */
+export function buildLinePath(pts, smooth) {
+    if (!smooth) {
+        let path = '';
+        let pen = false;
+        for (const p of pts) {
+            if (!p.defined) {
+                pen = false;
+                continue;
+            }
+            path += `${pen ? 'L' : 'M'}${p.x},${p.y} `;
+            pen = true;
+        }
+        return path.trim();
+    }
+    // Group defined-only runs; each run is smoothed independently.
+    const runs = [];
+    let cur = [];
+    for (const p of pts) {
+        if (p.defined)
+            cur.push({ x: p.x, y: p.y });
+        else if (cur.length) {
+            runs.push(cur);
+            cur = [];
+        }
+    }
+    if (cur.length)
+        runs.push(cur);
+    return runs.map(monotoneCubicPath).filter(Boolean).join(' ');
+}
+/** Fritsch-Carlson monotone cubic interpolation -> cubic-Bezier path.
+ *  Slope at each point chosen so the curve passes through every (xi, yi)
+ *  AND stays monotonic between them; control points sit 1/3 of the way
+ *  to the neighbours along that tangent. */
+function monotoneCubicPath(pts) {
+    const n = pts.length;
+    if (n === 0)
+        return '';
+    if (n === 1)
+        return `M${pts[0].x},${pts[0].y}`;
+    if (n === 2)
+        return `M${pts[0].x},${pts[0].y} L${pts[1].x},${pts[1].y}`;
+    // Secant slopes between adjacent points.
+    const dx = new Array(n - 1);
+    const m = new Array(n - 1);
+    for (let i = 0; i < n - 1; i += 1) {
+        const d = pts[i + 1].x - pts[i].x;
+        dx[i] = d;
+        m[i] = d === 0 ? 0 : (pts[i + 1].y - pts[i].y) / d;
+    }
+    // Tangent at each point: average of neighbouring slopes, with sign
+    // checks that flatten the tangent when slopes change sign.
+    const tan = new Array(n);
+    tan[0] = m[0];
+    tan[n - 1] = m[n - 2];
+    for (let i = 1; i < n - 1; i += 1) {
+        if (m[i - 1] * m[i] <= 0)
+            tan[i] = 0;
+        else
+            tan[i] = (m[i - 1] + m[i]) / 2;
+    }
+    // Fritsch-Carlson correction: ensure |tan / m| <= 3 to stay monotonic.
+    for (let i = 0; i < n - 1; i += 1) {
+        if (m[i] === 0) {
+            tan[i] = 0;
+            tan[i + 1] = 0;
+            continue;
+        }
+        const a = tan[i] / m[i];
+        const b = tan[i + 1] / m[i];
+        const h = Math.hypot(a, b);
+        if (h > 3) {
+            tan[i] = (3 / h) * a * m[i];
+            tan[i + 1] = (3 / h) * b * m[i];
+        }
+    }
+    // Build the Bezier path. Each segment: control points at 1/3 of dx.
+    let path = `M${pts[0].x},${pts[0].y}`;
+    for (let i = 0; i < n - 1; i += 1) {
+        const h = dx[i];
+        const c1x = pts[i].x + h / 3;
+        const c1y = pts[i].y + (tan[i] * h) / 3;
+        const c2x = pts[i + 1].x - h / 3;
+        const c2y = pts[i + 1].y - (tan[i + 1] * h) / 3;
+        path += ` C${c1x},${c1y} ${c2x},${c2y} ${pts[i + 1].x},${pts[i + 1].y}`;
+    }
+    return path;
+}
+export function linearTrend(values) {
+    let n = 0, sumX = 0, sumY = 0, sumXX = 0, sumXY = 0;
+    for (let i = 0; i < values.length; i += 1) {
+        const y = values[i];
+        if (!Number.isFinite(y))
+            continue;
+        n += 1;
+        sumX += i;
+        sumY += y;
+        sumXX += i * i;
+        sumXY += i * y;
+    }
+    if (n < 2)
+        return values.map(() => NaN);
+    const denom = n * sumXX - sumX * sumX;
+    if (denom === 0)
+        return values.map(() => sumY / n);
+    const slope = (n * sumXY - sumX * sumY) / denom;
+    const intercept = (sumY - slope * sumX) / n;
+    return values.map((_, i) => slope * i + intercept);
+}
+/** Simple moving average over a window of `period` values. Window centres
+ *  trail to the right (typical for time-series). NaN for points before the
+ *  window is full. */
+export function simpleMovingAverage(values, period) {
+    if (period < 1)
+        return values.slice();
+    const out = new Array(values.length).fill(NaN);
+    let sum = 0, count = 0;
+    for (let i = 0; i < values.length; i += 1) {
+        const v = values[i];
+        if (Number.isFinite(v)) {
+            sum += v;
+            count += 1;
+        }
+        if (i >= period) {
+            const drop = values[i - period];
+            if (Number.isFinite(drop)) {
+                sum -= drop;
+                count -= 1;
+            }
+        }
+        if (i >= period - 1 && count > 0)
+            out[i] = sum / count;
+    }
+    return out;
+}
+/** Exponential moving average. Smoothing factor alpha = 2 / (period + 1). */
+export function exponentialMovingAverage(values, period) {
+    const alpha = 2 / (Math.max(1, period) + 1);
+    const out = new Array(values.length).fill(NaN);
+    let prev = null;
+    for (let i = 0; i < values.length; i += 1) {
+        const v = values[i];
+        if (!Number.isFinite(v)) {
+            out[i] = prev ?? NaN;
+            continue;
+        }
+        prev = prev == null ? v : alpha * v + (1 - alpha) * prev;
+        out[i] = prev;
+    }
+    return out;
+}
+/** Compute overlay values for a series spec like 'sma:7' / 'ema:14' / 'linear'. */
+export function computeOverlay(values, spec) {
+    if (spec === 'linear')
+        return linearTrend(values);
+    const m = /^(sma|ema):(\d+)$/.exec(spec);
+    if (!m)
+        return values.map(() => NaN);
+    const period = Number(m[2]);
+    return m[1] === 'ema' ? exponentialMovingAverage(values, period) : simpleMovingAverage(values, period);
+}
 /** Round a [min,max] domain out to nice tick boundaries. */
 export function niceScale(min, max, tickCount = 4) {
     if (!Number.isFinite(min) || !Number.isFinite(max)) {
@@ -76,13 +334,17 @@ function fmtDate(t, span) {
         return d.toLocaleDateString(undefined, { month: 'short', year: '2-digit' });
     return String(d.getFullYear());
 }
-/** Data domain for one axis, honoring stacking of its bar/area series. */
-function axisDomain(list, categories, stacked, extra = []) {
+/** Data domain for one axis, honoring stacking of its bar/area series.
+ *  When `isLog` is true, non-positive values are discarded (log undefined)
+ *  and the domain is rounded to decade boundaries instead of nice steps. */
+function axisDomain(list, categories, stacked, extra = [], isLog = false) {
     let dMin = Infinity;
     let dMax = -Infinity;
     const note = (v) => {
         if (!Number.isFinite(v))
             return;
+        if (isLog && v <= 0)
+            return;
         if (v < dMin)
             dMin = v;
         if (v > dMax)
@@ -116,17 +378,18 @@ function axisDomain(list, categories, stacked, extra = []) {
         for (const v of s.values)
             note(v);
     if (dMin === Infinity) {
-        dMin = 0;
-        dMax = 1;
+        dMin = isLog ? 1 : 0;
+        dMax = isLog ? 10 : 1;
     }
-    // Bar / area charts read against a zero baseline, so always include 0.
-    if (stackable.length) {
+    // Bar / area charts read against a zero baseline, so always include 0
+    // - but only on linear axes (0 is invalid in log).
+    if (stackable.length && !isLog) {
         dMin = Math.min(dMin, 0);
         dMax = Math.max(dMax, 0);
     }
-    return niceScale(dMin, dMax);
+    return isLog ? niceLogScale(dMin, dMax) : niceScale(dMin, dMax);
 }
-export function buildChart(spec) {
+export function buildChart(spec, theme = 'light') {
     const width = spec.width ?? 520;
     const height = spec.height ?? 300;
     const palette = spec.palette ?? DEFAULT_PALETTE;
@@ -159,7 +422,705 @@ export function buildChart(spec) {
         valueTicks: [],
         catTicks: [],
         referenceLinesV: [],
+        overlays: [],
+        annotations: [],
+        heatmapCells: [],
+        heatmapRowTicks: [],
+        heatmapColTicks: [],
+        heatmapLegend: [],
+        funnelSegments: [],
+        radarRings: [],
+        radarAxes: [],
+        radarSeries: [],
+        radarCenter: null,
+        treemapCells: [],
+        calendarCells: [],
+        calendarMonthTicks: [],
+        calendarLegend: [],
+        gauge: null,
+        sankeyNodes: [],
+        sankeyLinks: [],
     };
+    // ---- Waterfall ----------------------------------------------------
+    // First series provides the values. Each non-total bar starts at the
+    // running cumulative sum; total bars (waterfallTotals[i]) reset and
+    // span from 0 to that sum. Color is derived from sign + total flag, with
+    // optional palette overrides via spec.waterfallColors.
+    if (spec.type === 'waterfall') {
+        const src = series[0];
+        if (!src)
+            return { ...empty };
+        const colors = spec.waterfallColors ?? {};
+        const positive = colors.positive ?? '#16a34a';
+        const negative = colors.negative ?? '#ef4444';
+        const total = colors.total ?? '#475569';
+        const maxLabel = spec.categories.reduce((m, c) => Math.max(m, c.length), 0);
+        const xLabelRotated = spec.categories.length > 8 || maxLabel > 9;
+        const padL = 48 + (spec.yAxisTitle ? 16 : 0);
+        const padR = 12;
+        const padT = 10;
+        const padB = (xLabelRotated ? 54 : 28) + (spec.xAxisTitle ? 16 : 0);
+        const plotW = Math.max(1, width - padL - padR);
+        const plotH = Math.max(1, height - padT - padB);
+        const plot = { x: padL, y: padT, w: plotW, h: plotH };
+        // Compute the running cumulative + per-bar (from, to) pairs.
+        const totals = spec.waterfallTotals ?? [];
+        const pairs = [];
+        let cum = 0;
+        spec.categories.forEach((_, i) => {
+            const v = src.values[i] ?? 0;
+            const isTotal = !!totals[i];
+            if (isTotal) {
+                pairs.push({ from: 0, to: cum, value: cum, isTotal: true });
+            }
+            else {
+                pairs.push({ from: cum, to: cum + v, value: v, isTotal: false });
+                cum += v;
+            }
+        });
+        // Y-axis domain spans every visited level (including 0).
+        let dMin = 0, dMax = 0;
+        for (const p of pairs) {
+            if (p.from < dMin)
+                dMin = p.from;
+            if (p.to < dMin)
+                dMin = p.to;
+            if (p.from > dMax)
+                dMax = p.from;
+            if (p.to > dMax)
+                dMax = p.to;
+        }
+        const dom = niceScale(dMin, dMax);
+        const yOfW = (v) => round(padT + plotH - ((v - dom.min) / (dom.max - dom.min || 1)) * plotH);
+        const slotW = plotW / Math.max(1, spec.categories.length);
+        const barPad = slotW * 0.2;
+        const barW = Math.max(1, slotW - barPad);
+        const bars = pairs.map((p, i) => {
+            const yTop = yOfW(Math.max(p.from, p.to));
+            const yBot = yOfW(Math.min(p.from, p.to));
+            const x = padL + slotW * i + barPad / 2;
+            const color = p.isTotal ? total : p.value >= 0 ? positive : negative;
+            return {
+                x: round(x), y: yTop, w: round(barW), h: Math.max(1, yBot - yTop),
+                color, label: spec.categories[i] ?? String(i), series: src.label, value: p.value,
+            };
+        });
+        // Thin connector lines between bar tops -> running total reads cleanly.
+        const connectors = [{
+                path: pairs
+                    .map((p, i) => {
+                    const x0 = padL + slotW * i + barPad / 2 + barW;
+                    const y = yOfW(p.to);
+                    const x1 = padL + slotW * (i + 1) + barPad / 2;
+                    // Skip the final connector beyond the last bar.
+                    return i < pairs.length - 1 ? `M${x0},${y} L${x1},${y}` : '';
+                })
+                    .filter(Boolean)
+                    .join(' '),
+                areaPath: '',
+                color: 'var(--sg-muted, #94a3b8)',
+                label: '',
+                points: [],
+            }];
+        const xTicks = spec.categories.map((label, i) => ({
+            label,
+            x: round(padL + slotW * i + slotW / 2),
+        }));
+        const yTicks = dom.ticks.map((value) => ({
+            value, y: yOfW(value), label: fmtTick(value),
+        }));
+        return {
+            ...empty,
+            plot,
+            bars,
+            lines: connectors,
+            yTicks,
+            xTicks,
+            xLabelRotated,
+        };
+    }
+    // ---- Funnel -------------------------------------------------------
+    // One series of strictly-decreasing values gets rendered as a stack
+    // of horizontal trapezoids: each level's width is proportional to its
+    // value relative to the largest, slope automatically links level N+1
+    // narrower than level N. Labels show value, conversion vs. top, and
+    // step drop-off.
+    if (spec.type === 'funnel') {
+        const src = series[0];
+        if (!src || !src.values.length)
+            return { ...empty };
+        const padL = 20, padR = 20, padT = 16, padB = 16;
+        const plotW = Math.max(1, width - padL - padR);
+        const plotH = Math.max(1, height - padT - padB);
+        const plot = { x: padL, y: padT, w: plotW, h: plotH };
+        const n = src.values.length;
+        const stepH = plotH / n;
+        const valMax = Math.max(...src.values.map((v) => (Number.isFinite(v) ? v : 0)));
+        const top = src.values[0] ?? 0;
+        const widthAt = (v) => (valMax > 0 ? (v / valMax) * plotW : 0);
+        const cx = padL + plotW / 2;
+        const palette = spec.palette ?? DEFAULT_PALETTE;
+        const segments = src.values.map((v, i) => {
+            const next = src.values[i + 1] ?? v * 0.8; // taper to a point on the last level
+            const w0 = widthAt(v);
+            const w1 = widthAt(next);
+            const y0 = padT + stepH * i;
+            const y1 = y0 + stepH;
+            const path = `M${cx - w0 / 2},${y0} L${cx + w0 / 2},${y0} L${cx + w1 / 2},${y1} L${cx - w1 / 2},${y1} Z`;
+            const color = src.color ?? palette[i % palette.length];
+            return {
+                path, color,
+                label: spec.categories[i] ?? src.label,
+                value: v,
+                conversion: top > 0 ? v / top : 0,
+                dropoff: i === 0 ? 0 : (src.values[i - 1] ?? v) > 0 ? 1 - v / (src.values[i - 1] ?? v) : 0,
+                cx,
+                cy: (y0 + y1) / 2,
+                textColor: pickContrastText(color),
+            };
+        });
+        return {
+            ...empty,
+            plot,
+            funnelSegments: segments,
+        };
+    }
+    // ---- Radar --------------------------------------------------------
+    // Polar coordinates: each `category` is a spoke (axis); each `series`
+    // contributes a polygon connecting its values across the spokes. All
+    // series share the same scale (max across every value). Concentric
+    // ring count derived from data, capped at 5 for legibility.
+    if (spec.type === 'radar') {
+        if (!series.length || !spec.categories.length)
+            return { ...empty };
+        const padL = 30, padR = 30, padT = 24, padB = 24;
+        const plotW = Math.max(1, width - padL - padR);
+        const plotH = Math.max(1, height - padT - padB);
+        const plot = { x: padL, y: padT, w: plotW, h: plotH };
+        const cx = padL + plotW / 2;
+        const cy = padT + plotH / 2;
+        const r = Math.max(20, Math.min(plotW, plotH) / 2 - 20);
+        const axes = spec.categories;
+        const k = axes.length;
+        let vMax = 0;
+        for (const s of series)
+            for (const v of s.values) {
+                if (Number.isFinite(v) && v > vMax)
+                    vMax = v;
+            }
+        if (vMax === 0)
+            vMax = 1;
+        const ringCount = 5;
+        const ringValues = Array.from({ length: ringCount }, (_, i) => ((i + 1) / ringCount) * vMax);
+        /** Convert (axis index, value) to (x, y). Angles start at 12 o'clock,
+         *  proceed clockwise so axes lay out left-to-right when k <= 4. */
+        const angleAt = (i) => -Math.PI / 2 + (i / k) * Math.PI * 2;
+        const pointAt = (i, v) => {
+            const t = v / vMax;
+            const a = angleAt(i);
+            return { x: round(cx + r * t * Math.cos(a)), y: round(cy + r * t * Math.sin(a)) };
+        };
+        const radarAxes = axes.map((label, i) => {
+            const p = pointAt(i, vMax);
+            return { label, x: p.x, y: p.y };
+        });
+        const radarSeriesGeo = series.map((s, si) => {
+            const pts = s.values.map((v, i) => {
+                const safe = Number.isFinite(v) ? v : 0;
+                const p = pointAt(i, safe);
+                return { x: p.x, y: p.y, value: v, axis: axes[i] ?? '' };
+            });
+            const path = pts.length
+                ? pts.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ') + ' Z'
+                : '';
+            const palette = spec.palette ?? DEFAULT_PALETTE;
+            return { label: s.label, color: s.color ?? palette[si % palette.length], path, points: pts };
+        });
+        return {
+            ...empty,
+            plot,
+            radarRings: ringValues,
+            radarAxes,
+            radarSeries: radarSeriesGeo,
+            radarCenter: { cx, cy, r },
+        };
+    }
+    // ---- Calendar heatmap --------------------------------------------
+    // GitHub-style year-of-days view: 7 rows (Sun..Sat) x N weeks. Each
+    // cell is a small square shaded by `calendarValues[i].value` via the
+    // sequential color scale. Days with no value render blank (border only)
+    // so missing data is visually obvious.
+    if (spec.type === 'calendar') {
+        const values = spec.calendarValues ?? [];
+        if (!values.length && !spec.calendarStart)
+            return { ...empty };
+        // Build a value lookup + figure out the date range.
+        const valueByDate = new Map();
+        let vMin = Infinity, vMax = -Infinity;
+        for (const v of values) {
+            valueByDate.set(v.date, v.value);
+            if (Number.isFinite(v.value)) {
+                if (v.value < vMin)
+                    vMin = v.value;
+                if (v.value > vMax)
+                    vMax = v.value;
+            }
+        }
+        if (vMin === Infinity) {
+            vMin = 0;
+            vMax = 1;
+        }
+        if (vMin === vMax)
+            vMax = vMin + 1;
+        const stops = resolveColorScale(spec.colorScale, vMin, vMax, theme);
+        const colorAt = (v) => sampleGradient(stops, (v - vMin) / (vMax - vMin));
+        // Determine date range. If calendarStart/End set, use them, otherwise
+        // span the data + round to whole weeks (Sun..Sat).
+        const sorted = values.map((v) => v.date).sort();
+        const startStr = spec.calendarStart ?? sorted[0] ?? '2026-01-01';
+        const endStr = spec.calendarEnd ?? sorted[sorted.length - 1] ?? startStr;
+        const start = new Date(startStr + 'T00:00:00Z');
+        const end = new Date(endStr + 'T00:00:00Z');
+        // Roll start back to its Sunday, end forward to its Saturday.
+        start.setUTCDate(start.getUTCDate() - start.getUTCDay());
+        end.setUTCDate(end.getUTCDate() + (6 - end.getUTCDay()));
+        const totalDays = Math.round((end.getTime() - start.getTime()) / 86400000) + 1;
+        const weeks = Math.ceil(totalDays / 7);
+        const padL = 36, padR = 80, padT = 26, padB = 16;
+        const plotW = Math.max(1, width - padL - padR);
+        const plotH = Math.max(1, height - padT - padB);
+        // Cell size: fit weeks across width, 7 rows down height.
+        const cellW = Math.floor(plotW / weeks);
+        const cellH = Math.floor(plotH / 7);
+        const cellSize = Math.max(6, Math.min(cellW, cellH));
+        const plot = { x: padL, y: padT, w: cellSize * weeks, h: cellSize * 7 };
+        const cells = [];
+        let lastMonth = -1;
+        const monthTicks = [];
+        for (let i = 0; i < totalDays; i += 1) {
+            const day = new Date(start.getTime() + i * 86400000);
+            const col = Math.floor(i / 7);
+            const row = i % 7;
+            const date = day.toISOString().slice(0, 10);
+            const has = valueByDate.has(date);
+            const v = valueByDate.get(date) ?? 0;
+            cells.push({
+                x: padL + col * cellSize,
+                y: padT + row * cellSize,
+                size: cellSize,
+                date, value: v,
+                defined: has,
+                color: has ? colorAt(v) : 'transparent',
+            });
+            if (day.getUTCDate() === 1 && day.getUTCMonth() !== lastMonth) {
+                lastMonth = day.getUTCMonth();
+                monthTicks.push({
+                    label: day.toLocaleDateString(undefined, { month: 'short' }),
+                    x: padL + col * cellSize,
+                });
+            }
+        }
+        const legend = Array.from({ length: 5 }, (_, i) => {
+            const t = i / 4;
+            const value = vMin + (vMax - vMin) * t;
+            return { value, color: colorAt(value), label: fmtTick(value) };
+        });
+        return {
+            ...empty,
+            plot,
+            calendarCells: cells,
+            calendarMonthTicks: monthTicks,
+            calendarLegend: legend,
+        };
+    }
+    // ---- Gauge --------------------------------------------------------
+    // Semicircle dial: track arc + value arc + optional colored range bands
+    // + optional target tick. Reads spec.gaugeValue / gaugeMin / gaugeMax.
+    if (spec.type === 'gauge') {
+        const min = spec.gaugeMin ?? 0;
+        const max = spec.gaugeMax ?? 100;
+        const value = Math.max(min, Math.min(max, spec.gaugeValue ?? 0));
+        const target = spec.gaugeTarget;
+        const cx = width / 2;
+        const cy = height * 0.78;
+        const r = Math.min(width * 0.42, height * 0.65);
+        // Start angle 180deg, end 360deg (drawn clockwise from 9 o'clock to 3).
+        const A0 = Math.PI;
+        const A1 = 2 * Math.PI;
+        const angleAt = (v) => A0 + ((v - min) / (max - min || 1)) * (A1 - A0);
+        const arc = (a0, a1, radius) => {
+            const x1 = cx + radius * Math.cos(a0);
+            const y1 = cy + radius * Math.sin(a0);
+            const x2 = cx + radius * Math.cos(a1);
+            const y2 = cy + radius * Math.sin(a1);
+            const large = a1 - a0 > Math.PI ? 1 : 0;
+            return `M${x1},${y1} A${radius},${radius} 0 ${large} 1 ${x2},${y2}`;
+        };
+        const trackPath = arc(A0, A1, r);
+        const valuePath = arc(A0, angleAt(value), r);
+        const rangePaths = (spec.gaugeRanges ?? []).map((band) => ({
+            path: arc(angleAt(band.from), angleAt(band.to), r - 9),
+            color: band.color, from: band.from, to: band.to,
+        }));
+        let targetPx = null;
+        if (target != null && Number.isFinite(target)) {
+            const a = angleAt(Math.max(min, Math.min(max, target)));
+            const inner = r - 12;
+            const outer = r + 4;
+            targetPx = {
+                x1: cx + inner * Math.cos(a), y1: cy + inner * Math.sin(a),
+                x2: cx + outer * Math.cos(a), y2: cy + outer * Math.sin(a),
+            };
+        }
+        // Tick marks just outside the track: a major tick every 1/4 of the scale,
+        // with 4 minor ticks between each. Gives the dial a measured, instrument feel.
+        const ticks = [];
+        const TICK_MAJOR = 4, TICK_MINOR = 5, TICK_TOTAL = TICK_MAJOR * TICK_MINOR;
+        for (let i = 0; i <= TICK_TOTAL; i++) {
+            const a = A0 + (i / TICK_TOTAL) * (A1 - A0);
+            const major = i % TICK_MINOR === 0;
+            const inner = r + 9;
+            const outer = r + (major ? 17 : 13);
+            ticks.push({
+                x1: cx + inner * Math.cos(a), y1: cy + inner * Math.sin(a),
+                x2: cx + outer * Math.cos(a), y2: cy + outer * Math.sin(a),
+                major,
+            });
+        }
+        // Pointer needle: a kite (long tip toward the value, short counterweight
+        // tail) pivoting on a center hub.
+        const aV = angleAt(value);
+        const tipR = r - 16, tailR = 18, baseR = 6;
+        const aPerp = aV + Math.PI / 2;
+        const pt = (rad, ang) => `${round(cx + rad * Math.cos(ang))},${round(cy + rad * Math.sin(ang))}`;
+        const needlePath = `M${pt(baseR, aPerp)} L${pt(tipR, aV)} L${pt(baseR, aPerp + Math.PI)} L${pt(tailR, aV + Math.PI)} Z`;
+        // Color the value arc by the band the value currently sits in.
+        let valueColor = null;
+        for (const band of spec.gaugeRanges ?? []) {
+            if (value >= band.from && value <= band.to)
+                valueColor = band.color;
+        }
+        return {
+            ...empty,
+            plot: { x: 0, y: 0, w: width, h: height },
+            gauge: {
+                cx, cy, r, trackPath, valuePath, rangePaths, target: targetPx,
+                ticks, needle: { path: needlePath, hubR: 7 }, valueColor,
+                minLabel: { x: cx - r, y: cy + 20 },
+                maxLabel: { x: cx + r, y: cy + 20 },
+                value, min, max, unit: spec.gaugeUnit ?? '',
+            },
+        };
+    }
+    // ---- Tree-map -----------------------------------------------------
+    // Squarified tree-map (Bruls et al. 2000): each level recursively
+    // partitions its rectangle in proportion to its children, picking the
+    // split orientation that keeps aspect ratios closest to 1.
+    if (spec.type === 'treemap') {
+        const root = spec.treemap;
+        if (!root)
+            return { ...empty };
+        const padL = 4, padR = 4, padT = 4, padB = 4;
+        const plotW = Math.max(1, width - padL - padR);
+        const plotH = Math.max(1, height - padT - padB);
+        const plot = { x: padL, y: padT, w: plotW, h: plotH };
+        const palette = spec.palette ?? DEFAULT_PALETTE;
+        const cells = [];
+        function totalOf(n) {
+            if (n.children?.length)
+                return n.children.reduce((s, c) => s + totalOf(c), 0);
+            return Math.max(0, n.value ?? 0);
+        }
+        function squarify(items, x, y, w, h, depth) {
+            if (!items.length || w <= 0 || h <= 0)
+                return;
+            const totals = items.map(totalOf);
+            const sum = totals.reduce((a, b) => a + b, 0);
+            if (sum <= 0)
+                return;
+            // Process largest-first so big items dominate the first row.
+            const ordered = items
+                .map((n, i) => ({ node: n, value: totals[i] }))
+                .sort((a, b) => b.value - a.value);
+            let cx = x, cy = y, cw = w, ch = h, remaining = sum;
+            let row = [];
+            const worstRatio = (vals, shortSide, rowSum, scale) => {
+                if (rowSum <= 0)
+                    return Infinity;
+                const rowArea = rowSum * scale;
+                const rowSide = rowArea / shortSide;
+                let worst = 0;
+                for (const v of vals) {
+                    const cell = v * scale;
+                    const long = cell / rowSide;
+                    const r = Math.max(shortSide / long, long / shortSide);
+                    if (r > worst)
+                        worst = r;
+                }
+                return worst;
+            };
+            function flushRow() {
+                if (!row.length)
+                    return;
+                const rowSum = row.reduce((a, b) => a + b.value, 0);
+                const scale = (cw * ch) / remaining;
+                const horizontal = cw >= ch;
+                const shortSide = horizontal ? ch : cw;
+                const rowSide = (rowSum * scale) / shortSide;
+                let offset = 0;
+                for (const it of row) {
+                    const cellSize = (it.value * scale) / rowSide;
+                    const cx2 = horizontal ? cx : cx + offset;
+                    const cy2 = horizontal ? cy + offset : cy;
+                    const ww = horizontal ? rowSide : cellSize;
+                    const hh = horizontal ? cellSize : rowSide;
+                    const color = it.node.color ?? palette[(depth + cells.length) % palette.length];
+                    // Leaf: emit a cell. Branch: recurse into the rect minus a label gutter.
+                    if (it.node.children?.length) {
+                        cells.push({
+                            x: round(cx2), y: round(cy2), w: round(ww), h: round(hh),
+                            color, textColor: pickContrastText(color),
+                            name: it.node.name, value: it.value, depth,
+                        });
+                        const labelH = Math.min(18, hh * 0.25);
+                        squarify(it.node.children, cx2 + 1, cy2 + labelH, ww - 2, hh - labelH - 1, depth + 1);
+                    }
+                    else {
+                        cells.push({
+                            x: round(cx2), y: round(cy2), w: round(ww), h: round(hh),
+                            color, textColor: pickContrastText(color),
+                            name: it.node.name, value: it.value, depth,
+                        });
+                    }
+                    offset += cellSize;
+                }
+                // Shrink the remaining strip.
+                if (horizontal) {
+                    cx += rowSide;
+                    cw -= rowSide;
+                }
+                else {
+                    cy += rowSide;
+                    ch -= rowSide;
+                }
+                remaining -= rowSum;
+                row = [];
+            }
+            for (const it of ordered) {
+                const scale = (cw * ch) / remaining;
+                const shortSide = Math.min(cw, ch);
+                const rowSum = row.reduce((a, b) => a + b.value, 0);
+                const currWorst = worstRatio(row.map((r) => r.value), shortSide, rowSum, scale);
+                const nextWorst = worstRatio([...row.map((r) => r.value), it.value], shortSide, rowSum + it.value, scale);
+                if (row.length && nextWorst > currWorst) {
+                    flushRow();
+                }
+                row.push(it);
+            }
+            flushRow();
+        }
+        const seedItems = root.children ?? [root];
+        squarify(seedItems, padL, padT, plotW, plotH, 0);
+        return { ...empty, plot, treemapCells: cells };
+    }
+    // ---- Sankey -------------------------------------------------------
+    // Multi-column flow layout. Each node assigned to a column by longest
+    // path from any source. Within a column, nodes are stacked vertically;
+    // height proportional to max(totalIn, totalOut). Links render as
+    // bezier ribbons whose width is the link value (in pixels).
+    if (spec.type === 'sankey') {
+        const nodes = spec.sankeyNodes ?? [];
+        const links = spec.sankeyLinks ?? [];
+        if (!nodes.length || !links.length)
+            return { ...empty };
+        const padL = 10, padR = 10, padT = 14, padB = 14;
+        const plotW = Math.max(1, width - padL - padR);
+        const plotH = Math.max(1, height - padT - padB);
+        const plot = { x: padL, y: padT, w: plotW, h: plotH };
+        const palette = spec.palette ?? DEFAULT_PALETTE;
+        const nodeById = new Map(nodes.map((n) => [n.id, n]));
+        // Column = longest path from any node with no incoming edges.
+        const targets = new Set(links.map((l) => l.target));
+        const sources = nodes.filter((n) => !targets.has(n.id));
+        const column = new Map();
+        function visit(id, depth, seen) {
+            if (seen.has(id))
+                return;
+            seen.add(id);
+            const cur = column.get(id) ?? 0;
+            if (depth > cur || !column.has(id))
+                column.set(id, depth);
+            for (const l of links)
+                if (l.source === id)
+                    visit(l.target, depth + 1, seen);
+            seen.delete(id);
+        }
+        for (const s of sources)
+            visit(s.id, 0, new Set());
+        // Cover any nodes with no path from a source (orphan rings).
+        for (const n of nodes)
+            if (!column.has(n.id))
+                column.set(n.id, 0);
+        const maxCol = Math.max(...column.values());
+        const cols = maxCol + 1;
+        const nodeW = 14;
+        const gapBetweenColumns = cols > 1 ? (plotW - nodeW * cols) / (cols - 1) : 0;
+        // Totals per node.
+        const totalIn = new Map();
+        const totalOut = new Map();
+        for (const l of links) {
+            totalIn.set(l.target, (totalIn.get(l.target) ?? 0) + l.value);
+            totalOut.set(l.source, (totalOut.get(l.source) ?? 0) + l.value);
+        }
+        // Per-column groups + max total in that column.
+        const byCol = new Map();
+        for (const n of nodes) {
+            const c = column.get(n.id) ?? 0;
+            const arr = byCol.get(c) ?? [];
+            arr.push(n.id);
+            byCol.set(c, arr);
+        }
+        // Per-column total height + node height scale.
+        let maxColTotal = 0;
+        for (const ids of byCol.values()) {
+            const t = ids.reduce((s, id) => s + Math.max(totalIn.get(id) ?? 0, totalOut.get(id) ?? 0), 0);
+            if (t > maxColTotal)
+                maxColTotal = t;
+        }
+        if (maxColTotal === 0)
+            return { ...empty, plot };
+        const nodeGapPx = 8;
+        const heightScale = (plotH - nodeGapPx * 8) / maxColTotal; // leave gap room
+        const placed = [];
+        for (const [c, ids] of byCol) {
+            const heights = ids.map((id) => Math.max(8, Math.max(totalIn.get(id) ?? 0, totalOut.get(id) ?? 0) * heightScale));
+            const totalH = heights.reduce((s, h) => s + h, 0) + nodeGapPx * (ids.length - 1);
+            let yCursor = padT + (plotH - totalH) / 2;
+            const xCol = padL + c * (nodeW + gapBetweenColumns);
+            ids.forEach((id, idx) => {
+                const node = nodeById.get(id);
+                const h = heights[idx];
+                placed.push({
+                    id,
+                    label: node.label ?? id,
+                    color: node.color ?? palette[(placed.length) % palette.length],
+                    x: xCol, y: yCursor, w: nodeW, h,
+                    column: c,
+                    totalIn: totalIn.get(id) ?? 0,
+                    totalOut: totalOut.get(id) ?? 0,
+                });
+                yCursor += h + nodeGapPx;
+            });
+        }
+        const placedById = new Map(placed.map((n) => [n.id, n]));
+        // Per-node sub-cursor so multiple links from one node stack vertically.
+        const inCursor = new Map();
+        const outCursor = new Map();
+        const builtLinks = [];
+        // Sort links so wider ribbons render first (so thin ribbons stack on top).
+        const sortedLinks = links.slice().sort((a, b) => b.value - a.value);
+        for (const link of sortedLinks) {
+            const a = placedById.get(link.source);
+            const b = placedById.get(link.target);
+            if (!a || !b)
+                continue;
+            const linkH = Math.max(1, link.value * heightScale);
+            const aY = a.y + (outCursor.get(a.id) ?? 0) + linkH / 2;
+            const bY = b.y + (inCursor.get(b.id) ?? 0) + linkH / 2;
+            outCursor.set(a.id, (outCursor.get(a.id) ?? 0) + linkH);
+            inCursor.set(b.id, (inCursor.get(b.id) ?? 0) + linkH);
+            const x0 = a.x + a.w;
+            const x1 = b.x;
+            const mid = (x0 + x1) / 2;
+            const path = `M${x0},${aY} C${mid},${aY} ${mid},${bY} ${x1},${bY}`;
+            builtLinks.push({
+                path, color: link.color ?? a.color, width: linkH,
+                source: link.source, target: link.target, value: link.value,
+            });
+        }
+        return { ...empty, plot, sankeyNodes: placed, sankeyLinks: builtLinks };
+    }
+    // ---- Heatmap ------------------------------------------------------
+    // Each series is one row, series.values are the cells across categories.
+    // Color comes from a sequential/diverging/custom palette mapped to the
+    // global value range. Cell text contrasts black/white against the cell.
+    if (spec.type === 'heatmap') {
+        if (!series.length || !spec.categories.length)
+            return { ...empty, plot: { x: 0, y: 0, w: width, h: height } };
+        // Layout: left gutter for row labels, bottom for column labels.
+        const maxRowLabel = series.reduce((m, s) => Math.max(m, s.label.length), 0);
+        const padL = 12 + Math.min(180, Math.max(60, maxRowLabel * 7));
+        const padR = 64; // room for the right-side legend bar
+        const padT = 12;
+        const padB = 32;
+        const plotW = Math.max(1, width - padL - padR);
+        const plotH = Math.max(1, height - padT - padB);
+        const plot = { x: padL, y: padT, w: plotW, h: plotH };
+        const cellW = plotW / spec.categories.length;
+        const cellH = plotH / series.length;
+        // Resolve value range across the whole matrix.
+        let vMin = Infinity, vMax = -Infinity;
+        for (const s of series)
+            for (const v of s.values) {
+                if (!Number.isFinite(v))
+                    continue;
+                if (v < vMin)
+                    vMin = v;
+                if (v > vMax)
+                    vMax = v;
+            }
+        if (vMin === Infinity) {
+            vMin = 0;
+            vMax = 1;
+        }
+        if (vMin === vMax)
+            vMax = vMin + 1;
+        // Pick the palette stops.
+        const stops = resolveColorScale(spec.colorScale, vMin, vMax, theme);
+        const colorAt = (v) => sampleGradient(stops, (v - vMin) / (vMax - vMin));
+        const heatmapCells = [];
+        series.forEach((s, ri) => {
+            s.values.forEach((v, ci) => {
+                if (!Number.isFinite(v))
+                    return;
+                const color = colorAt(v);
+                heatmapCells.push({
+                    x: round(padL + cellW * ci),
+                    y: round(padT + cellH * ri),
+                    w: round(cellW),
+                    h: round(cellH),
+                    color,
+                    textColor: pickContrastText(color),
+                    value: v,
+                    rowLabel: s.label,
+                    colLabel: spec.categories[ci] ?? '',
+                });
+            });
+        });
+        const heatmapRowTicks = series.map((s, i) => ({
+            value: i,
+            y: round(padT + cellH * i + cellH / 2),
+            label: s.label,
+        }));
+        const heatmapColTicks = spec.categories.map((label, i) => ({
+            label,
+            x: round(padL + cellW * i + cellW / 2),
+        }));
+        // Legend: sample 5 stops across the range.
+        const heatmapLegend = Array.from({ length: 5 }, (_, i) => {
+            const t = i / 4;
+            const value = vMin + (vMax - vMin) * t;
+            return { value, color: colorAt(value), label: fmtTick(value) };
+        });
+        return {
+            ...empty,
+            plot,
+            heatmapCells,
+            heatmapRowTicks,
+            heatmapColTicks,
+            heatmapLegend,
+        };
+    }
     if (spec.type === 'pie') {
         const s = series[0];
         if (!s)
@@ -410,18 +1371,28 @@ export function buildChart(spec) {
     const plot = { x: padL, y: padT, w: plotW, h: plotH };
     const refsLeft = (spec.referenceLines ?? []).filter((r) => r.axis !== 'right').map((r) => r.value);
     const refsRight = (spec.referenceLines ?? []).filter((r) => r.axis === 'right').map((r) => r.value);
+    const leftLog = spec.yScale === 'log';
+    const rightLog = spec.y2Scale === 'log';
     const leftDom = spec.stacked100
         ? niceScale(0, 100)
-        : axisDomain(leftSeries, spec.categories, stacked, refsLeft);
+        : axisDomain(leftSeries, spec.categories, stacked, refsLeft, leftLog);
     const rightDom = hasRightAxis
         ? spec.stacked100
             ? niceScale(0, 100)
-            : axisDomain(rightSeries, spec.categories, stacked, refsRight)
+            : axisDomain(rightSeries, spec.categories, stacked, refsRight, rightLog)
         : null;
-    const yOf = (dom, v) => round(padT + plotH - ((v - dom.min) / (dom.max - dom.min || 1)) * plotH);
-    const yLeft = (v) => yOf(leftDom, v);
-    const yRight = (v) => yOf(rightDom ?? leftDom, v);
+    /** Map a data value to a y pixel. Returns NaN for non-positive values on
+     *  a log axis so callers can drop the point (line gap / missing bar). */
+    const yOf = (dom, v, isLog = false) => {
+        const t = project(v, dom.min, dom.max, isLog);
+        if (t === null)
+            return NaN;
+        return round(padT + plotH - t * plotH);
+    };
+    const yLeft = (v) => yOf(leftDom, v, leftLog);
+    const yRight = (v) => yOf(rightDom ?? leftDom, v, rightLog);
     const domOf = (s) => (s.axis === 'right' ? rightDom ?? leftDom : leftDom);
+    const isLogOf = (s) => (s.axis === 'right' ? rightLog : leftLog);
     const n = spec.categories.length;
     const slot = plotW / Math.max(1, n);
     // X positions. A time axis spaces points by actual time (irregular gaps);
@@ -494,12 +1465,17 @@ export function buildChart(spec) {
             const barW = inner / barSeries.length;
             barSeries.forEach((s, bi) => {
                 const dom = domOf(s);
-                const base = yOf(dom, Math.min(Math.max(0, dom.min), dom.max));
+                const log = isLogOf(s);
+                // Log axis: bars grow from the axis floor (dom.min) up to v rather
+                // than from 0, since 0 is invalid in log space.
+                const base = log ? yOf(dom, dom.min, log) : yOf(dom, Math.min(Math.max(0, dom.min), dom.max), log);
                 s.values.forEach((v, i) => {
                     if (!Number.isFinite(v))
                         return;
+                    if (log && v <= 0)
+                        return;
                     const x = padL + slot * i + groupPad / 2 + barW * bi;
-                    const yV = yOf(dom, v);
+                    const yV = yOf(dom, v, log);
                     bars.push({
                         x: round(x),
                         y: Math.min(yV, base),
@@ -534,7 +1510,8 @@ export function buildChart(spec) {
         if (s.kind === 'bar')
             continue;
         const dom = domOf(s);
-        const yA = (v) => yOf(dom, v);
+        const log = isLogOf(s);
+        const yA = (v) => yOf(dom, v, log);
         const isStackedArea = stacked && s.kind === 'area';
         const px = (i) => xCenter(i);
         let pts;
@@ -560,23 +1537,20 @@ export function buildChart(spec) {
                 return { x: px(i), y: ok ? yA(v) : NaN, label: spec.categories[i] ?? String(i), value: v, defined: ok };
             });
         }
-        // Build the line in segments, breaking at gaps (undefined points).
-        let path = '';
-        let pen = false;
-        for (const p of pts) {
-            if (!p.defined) {
-                pen = false;
-                continue;
-            }
-            path += `${pen ? 'L' : 'M'}${p.x},${p.y} `;
-            pen = true;
-        }
-        path = path.trim();
+        // Build the line - smoothed via monotone cubic when requested, else
+        // straight polylines. Either way, gaps break the path cleanly.
+        const smooth = !!s.smooth;
+        const path = buildLinePath(pts, smooth);
         let areaPath = '';
         if (s.kind === 'area' && pts.length) {
             if (baselinePts) {
-                const top = pts.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ');
-                const back = baselinePts.slice().reverse().map((p) => `L${p.x},${p.y}`).join(' ');
+                const top = smooth
+                    ? monotoneCubicPath(pts.map((p) => ({ x: p.x, y: p.y })))
+                    : pts.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ');
+                const back = smooth
+                    ? `L${baselinePts[baselinePts.length - 1].x},${baselinePts[baselinePts.length - 1].y} ` +
+                        monotoneCubicPath(baselinePts.slice().reverse()).replace(/^M[^ ]+ /, '')
+                    : baselinePts.slice().reverse().map((p) => `L${p.x},${p.y}`).join(' ');
                 areaPath = `${top} ${back} Z`;
             }
             else {
@@ -596,35 +1570,139 @@ export function buildChart(spec) {
                     runs.push(cur);
                 areaPath = runs
                     .map((run) => {
-                    const top = run.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ');
+                    const top = smooth
+                        ? monotoneCubicPath(run.map((p) => ({ x: p.x, y: p.y })))
+                        : run.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ');
                     return `${top} L${run[run.length - 1].x},${baseY} L${run[0].x},${baseY} Z`;
                 })
                     .join(' ');
             }
         }
-        lines.push({ path, areaPath, color: s.color, label: s.label, points: pts });
+        // Confidence band: shaded envelope between upperValues / lowerValues.
+        // Both arrays must be present and aligned to the value array.
+        let bandPath = '';
+        if (s.upperValues?.length === s.values.length && s.lowerValues?.length === s.values.length) {
+            const upperPts = [];
+            const lowerPts = [];
+            for (let i = 0; i < s.values.length; i += 1) {
+                const u = s.upperValues[i];
+                const lo = s.lowerValues[i];
+                if (!Number.isFinite(u) || !Number.isFinite(lo))
+                    continue;
+                if (log && (u <= 0 || lo <= 0))
+                    continue;
+                upperPts.push({ x: px(i), y: yA(u) });
+                lowerPts.push({ x: px(i), y: yA(lo) });
+            }
+            if (upperPts.length >= 2) {
+                const top = smooth
+                    ? monotoneCubicPath(upperPts)
+                    : upperPts.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ');
+                const back = smooth
+                    ? `L${lowerPts[lowerPts.length - 1].x},${lowerPts[lowerPts.length - 1].y} ` +
+                        monotoneCubicPath(lowerPts.slice().reverse()).replace(/^M[^ ]+ /, '')
+                    : lowerPts.slice().reverse().map((p) => `L${p.x},${p.y}`).join(' ');
+                bandPath = `${top} ${back} Z`;
+            }
+        }
+        lines.push({ path, areaPath, color: s.color, label: s.label, points: pts, bandPath });
     }
-    const tickFor = (dom) => dom.ticks.map((value) => ({ value, y: yOf(dom, value), label: fmtTick(value) }));
+    const tickFor = (dom, log) => dom.ticks.map((value) => ({ value, y: yOf(dom, value, log), label: fmtTick(value) }));
     const referenceLines = (spec.referenceLines ?? []).map((ref) => {
-        const dom = ref.axis === 'right' ? (rightDom ?? leftDom) : leftDom;
+        const onRight = ref.axis === 'right';
+        const dom = onRight ? (rightDom ?? leftDom) : leftDom;
+        const log = onRight ? rightLog : leftLog;
         return {
-            y: yOf(dom, ref.value),
+            y: yOf(dom, ref.value, log),
             label: ref.label ?? fmtTick(ref.value),
             color: ref.color ?? '#ef4444',
             dashed: ref.dashed !== false,
         };
     });
+    // ---- Overlays: trendline / moving average ------------------------
+    // For every series with an `overlay`, compute the smoothed values and
+    // render as a dashed line in the source series' color (or overlayColor).
+    const overlays = [];
+    for (const s of series) {
+        if (!s.overlay)
+            continue;
+        const dom = domOf(s);
+        const log = isLogOf(s);
+        const overlayVals = computeOverlay(s.values, s.overlay);
+        const color = s.overlayColor ?? s.color;
+        const pts = overlayVals.map((v, i) => {
+            const ok = Number.isFinite(v) && (!log || v > 0);
+            return {
+                x: xCenter(i),
+                y: ok ? yOf(dom, v, log) : NaN,
+                label: spec.categories[i] ?? String(i),
+                value: v,
+                defined: ok,
+            };
+        });
+        const path = buildLinePath(pts, !!s.smooth);
+        overlays.push({
+            path,
+            areaPath: '',
+            color,
+            label: `${s.label} (${s.overlay})`,
+            points: pts,
+        });
+    }
+    // ---- Annotations: resolve data-space anchors to pixel coords ------
+    const annotations = [];
+    for (const a of (spec.annotations ?? [])) {
+        let ax = null;
+        let ay = null;
+        if ('category' in a.at) {
+            const ci = spec.categories.indexOf(a.at.category);
+            if (ci < 0)
+                continue;
+            ax = xCenter(ci);
+            // Anchor to the named series' value at that category, else just
+            // mid-plot. Picks the first matching series if `series` is set.
+            const seriesName = a.at.series;
+            const s = seriesName ? series.find((x) => x.label === seriesName) : series[0];
+            if (s) {
+                const v = s.values[ci];
+                if (Number.isFinite(v))
+                    ay = yOf(domOf(s), v, isLogOf(s));
+            }
+            if (ay == null)
+                ay = padT + plotH / 2;
+        }
+        else {
+            // Raw x/y in data space (x ignored for category x-axis; takes the
+            // mid-plot in that case). y projects through the left axis.
+            ax = padL + plotW / 2;
+            if (Number.isFinite(a.at.y))
+                ay = yOf(leftDom, a.at.y, leftLog);
+            else
+                ay = padT + plotH / 2;
+        }
+        if (ax != null && ay != null && Number.isFinite(ay)) {
+            annotations.push({
+                x: ax,
+                y: ay,
+                label: a.label,
+                color: a.color ?? '#0f172a',
+                placement: a.placement ?? 'top',
+            });
+        }
+    }
     return {
         ...empty,
         plot,
         bars,
         lines,
-        yTicks: tickFor(leftDom),
-        y2Ticks: rightDom ? tickFor(rightDom) : [],
+        yTicks: tickFor(leftDom, leftLog),
+        y2Ticks: rightDom ? tickFor(rightDom, rightLog) : [],
         hasRightAxis,
         xTicks,
         xLabelRotated: timeOk ? false : xLabelRotated,
         referenceLines,
+        overlays,
+        annotations,
     };
 }
 /**
@@ -650,7 +1728,6 @@ export function rowsToChartSpec(rows, opts) {
         }
         return idx;
     };
-    // Series keyed by name -> per-category {sum,count}.
     const seriesMap = new Map();
     const ensureSeries = (name) => {
         let arr = seriesMap.get(name);
@@ -660,27 +1737,33 @@ export function rowsToChartSpec(rows, opts) {
         }
         return arr;
     };
+    const trackIds = opts.idField !== undefined;
     for (const row of rows) {
         const cat = String(row[opts.category] ?? '');
         const ci = ensureCat(cat);
+        const rowId = trackIds ? row[opts.idField] : undefined;
         if (opts.series) {
             const sName = String(row[opts.series] ?? '');
             const arr = ensureSeries(sName);
             const num = Number(row[valueFields[0]]);
-            const cell = (arr[ci] ?? (arr[ci] = { sum: 0, count: 0 }));
+            const cell = (arr[ci] ?? (arr[ci] = { sum: 0, count: 0, rowIds: [] }));
             if (Number.isFinite(num)) {
                 cell.sum += num;
                 cell.count += 1;
+                if (rowId !== undefined)
+                    cell.rowIds.push(rowId);
             }
         }
         else {
             for (const vf of valueFields) {
                 const arr = ensureSeries(vf);
                 const num = Number(row[vf]);
-                const cell = (arr[ci] ?? (arr[ci] = { sum: 0, count: 0 }));
+                const cell = (arr[ci] ?? (arr[ci] = { sum: 0, count: 0, rowIds: [] }));
                 if (Number.isFinite(num)) {
                     cell.sum += num;
                     cell.count += 1;
+                    if (rowId !== undefined)
+                        cell.rowIds.push(rowId);
                 }
             }
         }
@@ -688,9 +1771,12 @@ export function rowsToChartSpec(rows, opts) {
     const entries = [...seriesMap.entries()].map(([name, arr]) => ({
         label: opts.series ? name : opts.seriesLabel && valueFields.length === 1 ? opts.seriesLabel : name,
         values: categories.map((_, i) => {
-            const cell = arr[i] ?? { sum: 0, count: 0 };
+            const cell = arr[i] ?? { sum: 0, count: 0, rowIds: [] };
             return reduceCell(cell.sum, cell.count);
         }),
+        rowIds: trackIds
+            ? categories.map((_, i) => (arr[i]?.rowIds ?? []).slice())
+            : undefined,
     }));
     // ---- Sort + top-N -----------------------------------------------------
     const totals = categories.map((_, i) => entries.reduce((sum, e) => sum + (Number.isFinite(e.values[i]) ? e.values[i] : 0), 0));
@@ -713,11 +1799,18 @@ export function rowsToChartSpec(rows, opts) {
             values: keep
                 .map((i) => e.values[i])
                 .concat(rest.reduce((sum, i) => sum + (Number.isFinite(e.values[i]) ? e.values[i] : 0), 0)),
+            rowIds: e.rowIds
+                ? keep.map((i) => e.rowIds[i]).concat([rest.flatMap((i) => e.rowIds[i] ?? [])])
+                : undefined,
         }));
     }
     else {
         finalCategories = order.map((i) => categories[i]);
-        finalSeries = entries.map((e) => ({ label: e.label, values: order.map((i) => e.values[i]) }));
+        finalSeries = entries.map((e) => ({
+            label: e.label,
+            values: order.map((i) => e.values[i]),
+            rowIds: e.rowIds ? order.map((i) => e.rowIds[i]) : undefined,
+        }));
     }
     return {
         type: opts.type,