@aeriz/chart 1.0.0

package/src/charts.js

@@ -0,0 +1,1365 @@
+// charts.js — Concrete chart implementations.
+// Each subclass implements _render(). All share Chart's lifecycle, hit
+// testing, tooltip, theme, and animation infrastructure.
+
+import { Chart, scheduler } from './base.js';
+import * as M from './math.js';
+import { TAU } from './math.js';
+
+// ─────────────────────────────────────────────────────────
+// 1. BAR (vertical)
+// ─────────────────────────────────────────────────────────
+export class BarChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (data.length === 0) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const labelOf = this.options.label || (d => d.label);
+    const valueOf = this.options.value || (d => d.value);
+
+    const values = data.map((d, i) => valueOf(d, i));
+    const yMin = Math.min(0, ...values);
+    const yMax = Math.max(...values);
+    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
+
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLabels: data.map(labelOf),
+      yTickFormat: this.options.yTickFormat,
+      xTickFormat: this.options.xTickFormat,
+    });
+
+    const slot = ax.pw / data.length;
+    const barW = Math.max(2, Math.min(60, slot - 8));
+    const prog = this._anim.progress;
+    const radius = t.barRadius;
+
+    // Group by color for batching.
+    const groups = new Map();
+    const fmt = this.options.dataLabels;
+
+    for (let i = 0; i < data.length; i++) {
+      const v = values[i];
+      const x = ax.px + (i + 0.5) * slot - barW / 2;
+      const y0 = ax.yToPx(0);
+      const y1 = ax.yToPx(v);
+      const top = Math.min(y0, y1);
+      const h = Math.abs(y1 - y0) * prog;
+      const animTop = v >= 0 ? y0 - h : y0;
+      const color = this._colorOf(i, data[i]);
+      if (!groups.has(color)) groups.set(color, []);
+      groups.get(color).push({ x, y: animTop, w: barW, h, radius });
+
+      this.hits.add({
+        _id: i, x, y: Math.min(animTop, animTop + h), w: barW,
+        h: Math.abs(h),
+        tipX: x + barW / 2, tipY: animTop,
+        tooltip: `${labelOf(data[i], i)}: ${v}`,
+      });
+
+      if (fmt && prog > 0.95) {
+        const txt = typeof fmt === 'function' ? fmt(data[i], i) : String(v);
+        e.text(txt, x + barW / 2, animTop - 4, {
+          fill: t.text, font: `${t.fontSize}px ${t.font}`,
+          align: 'center', baseline: 'bottom',
+        });
+      }
+    }
+
+    for (const [color, items] of groups) e.rects(items, color);
+
+    if (this._hover) {
+      const r = this._hover;
+      e.rect(r.x, r.y, r.w, r.h, { stroke: t.text, lineWidth: 1.5 });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 2. HORIZONTAL BAR
+// ─────────────────────────────────────────────────────────
+export class HBarChart extends Chart {
+  _axisPad() {
+    return { l: 80, r: 16, t: 16, b: 32 };
+  }
+  _render() {
+    const data = this.options.data || [];
+    if (data.length === 0) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const labelOf = this.options.label || (d => d.label);
+    const valueOf = this.options.value || (d => d.value);
+    const values = data.map((d, i) => valueOf(d, i));
+    const xMin = Math.min(0, ...values);
+    const xMax = Math.max(...values);
+    const [xLo, xHi] = M.niceDomain(xMin, xMax, 5);
+
+    const pad = this._axisPad();
+    const px = pad.l, py = pad.t;
+    const pw = e.w - pad.l - pad.r;
+    const ph = e.h - pad.t - pad.b;
+    const font = `${t.fontSize}px ${t.font}`;
+
+    // X grid + labels
+    const xTicks = M.niceTicks(xLo, xHi, 5);
+    const xToPx = v => px + pw * (v - xLo) / (xHi - xLo);
+    e.ctx.strokeStyle = t.grid;
+    e.ctx.lineWidth = 1;
+    e.ctx.beginPath();
+    for (const v of xTicks) {
+      const x = Math.round(xToPx(v)) + 0.5;
+      e.ctx.moveTo(x, py); e.ctx.lineTo(x, py + ph);
+    }
+    e.ctx.stroke();
+    for (const v of xTicks) {
+      e.text(String(v), xToPx(v), py + ph + 6, {
+        fill: t.muted, font, align: 'center', baseline: 'top',
+      });
+    }
+    e.poly([{x: px, y: py + ph}, {x: px + pw, y: py + ph}], { stroke: t.axis, lineWidth: 1 });
+
+    const slot = ph / data.length;
+    const barH = Math.max(2, Math.min(40, slot - 6));
+    const prog = this._anim.progress;
+    const groups = new Map();
+
+    for (let i = 0; i < data.length; i++) {
+      const v = values[i];
+      const yMid = py + (i + 0.5) * slot;
+      const y = yMid - barH / 2;
+      const x0 = xToPx(0);
+      const x1 = xToPx(v);
+      const start = Math.min(x0, x1);
+      const w = Math.abs(x1 - x0) * prog;
+      const animLeft = v >= 0 ? x0 : x0 - w;
+      const color = this._colorOf(i, data[i]);
+      if (!groups.has(color)) groups.set(color, []);
+      groups.get(color).push({ x: animLeft, y, w, h: barH, radius: t.barRadius });
+
+      this.hits.add({
+        _id: i, x: animLeft, y, w, h: barH,
+        tipX: animLeft + w / 2, tipY: y,
+        tooltip: `${labelOf(data[i], i)}: ${v}`,
+      });
+      // Y label
+      e.text(labelOf(data[i], i), px - 6, yMid, {
+        fill: t.muted, font, align: 'right', baseline: 'middle',
+      });
+    }
+
+    for (const [color, items] of groups) e.rects(items, color);
+    if (this._hover) {
+      const r = this._hover;
+      e.rect(r.x, r.y, r.w, r.h, { stroke: t.text, lineWidth: 1.5 });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 3. LINE
+// ─────────────────────────────────────────────────────────
+export class LineChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (data.length === 0) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const labelOf = this.options.label || (d => d.label);
+    const valueOf = this.options.value || (d => d.value);
+    const values = data.map((d, i) => valueOf(d, i));
+    const yMin = Math.min(0, ...values);
+    const yMax = Math.max(...values);
+    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
+    const useTime = this.options.xScale === 'time';
+    let spec = {
+      yMin: yLo, yMax: yHi,
+      yScale: this.options.yScale,
+      yTickFormat: this.options.yTickFormat,
+      xTickFormat: this.options.xTickFormat,
+    };
+    if (useTime) {
+      const xs = data.map((d, i) => +labelOf(d, i));
+      spec.xTime = { min: xs[0], max: xs[xs.length - 1] };
+    } else {
+      spec.xLabels = data.map(labelOf);
+    }
+    const ax = this._drawCartesian(spec);
+
+    const color = this.options.color || this.palette[0];
+    const interp = this.options.interpolation || 'smooth';
+    const lineW = t.lineWidth;
+    const prog = this._anim.progress;
+
+    // Decimation
+    let renderData = data;
+    if (M.shouldDecimate(data.length, ax.pw)) {
+      renderData = M.minMaxDecimate(data, Math.floor(ax.pw), valueOf);
+    }
+
+    const points = renderData.map((d, i) => {
+      const xv = useTime ? +labelOf(d, i) : i;
+      const idx = useTime ? null : i;
+      // For category x scale, map by index in renderData.
+      const x = useTime
+        ? ax.xToPx(xv)
+        : ax.px + ((idx + 0.5) / renderData.length) * ax.pw;
+      const y = ax.yToPx(valueOf(d, i));
+      return { x, y, d, i };
+    });
+
+    // Reveal: clip horizontally based on progress.
+    e.clip(ax.px, ax.py, ax.pw * prog, ax.ph);
+
+    // Area fill (smooth + linear)
+    if (interp === 'smooth' || interp === 'linear') {
+      const cps = interp === 'smooth' ? M.bezierControlPoints(points) : null;
+      const grad = e.vGradient(`area-${color}`, ax.px, ax.py, ax.py + ax.ph, [
+        [0, M.colorAlpha(color, 0.25)],
+        [1, M.colorAlpha(color, 0)],
+      ]);
+      if (cps) e.smoothArea(points, cps, ax.py + ax.ph, grad);
+      else {
+        const areaPts = points.concat([
+          { x: points[points.length - 1].x, y: ax.py + ax.ph },
+          { x: points[0].x, y: ax.py + ax.ph },
+        ]);
+        e.poly(areaPts, { fill: grad });
+      }
+      if (cps) e.smooth(points, cps, { stroke: color, lineWidth: lineW });
+      else e.poly(points, { stroke: color, lineWidth: lineW, cap: 'round', join: 'round' });
+    } else if (interp === 'step' || interp.startsWith('step-')) {
+      const mode = interp === 'step' ? 'before' : interp.split('-')[1];
+      e.step(points, mode, { stroke: color, lineWidth: lineW });
+    }
+
+    e.unclip();
+
+    // Points + hit regions (only when not decimated)
+    if (renderData === data && data.length <= 50) {
+      const pr = t.pointRadius;
+      e.circles(points, color, pr);
+      for (const p of points) {
+        this.hits.add({
+          _id: p.i, x: p.x - 8, y: p.y - 8, w: 16, h: 16,
+          tipX: p.x, tipY: p.y - pr,
+          tooltip: `${labelOf(p.d, p.i)}: ${valueOf(p.d, p.i)}`,
+        });
+      }
+    } else {
+      // Add invisible hit columns for decimated data.
+      const colW = ax.pw / renderData.length;
+      for (let i = 0; i < renderData.length; i++) {
+        const p = points[i];
+        this.hits.add({
+          _id: p.i, x: p.x - colW / 2, y: ax.py, w: colW, h: ax.ph,
+          tipX: p.x, tipY: p.y - 8,
+          tooltip: `${labelOf(p.d, p.i)}: ${valueOf(p.d, p.i)}`,
+        });
+      }
+    }
+
+    if (this._hover) {
+      const p = points.find(pp => pp.i === this._hover._id);
+      if (p) e.circle(p.x, p.y, t.pointRadius + 3, {
+        stroke: color, lineWidth: 2, fill: t.bg,
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 4. AREA  (line with always-filled area, supports stacked)
+// ─────────────────────────────────────────────────────────
+export class AreaChart extends Chart {
+  _render() {
+    const series = this.options.series || [];
+    const cats = this.options.categories || [];
+    if (!series.length || !cats.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const stacked = this.options.stacked === true;
+
+    // Compute y domain.
+    let yMax;
+    if (stacked) {
+      yMax = 0;
+      for (let i = 0; i < cats.length; i++) {
+        let sum = 0;
+        for (const s of series) sum += +s.values[i] || 0;
+        if (sum > yMax) yMax = sum;
+      }
+    } else {
+      yMax = -Infinity;
+      for (const s of series) for (const v of s.values) if (+v > yMax) yMax = +v;
+    }
+    const [yLo, yHi] = M.niceDomain(0, yMax, 5);
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLabels: cats,
+      yTickFormat: this.options.yTickFormat,
+    });
+    const lineW = t.lineWidth;
+    const prog = this._anim.progress;
+
+    e.clip(ax.px, ax.py, ax.pw * prog, ax.ph);
+
+    if (stacked) {
+      // Build cumulative bands bottom-up.
+      const cum = new Array(cats.length).fill(0);
+      const seriesPts = [];
+      for (let s = 0; s < series.length; s++) {
+        const ser = series[s];
+        const ptsTop = [], ptsBot = [];
+        for (let i = 0; i < cats.length; i++) {
+          const v = +ser.values[i] || 0;
+          const x = ax.px + ((i + 0.5) / cats.length) * ax.pw;
+          const yBot = ax.yToPx(cum[i]);
+          const yTop = ax.yToPx(cum[i] + v);
+          ptsTop.push({ x, y: yTop });
+          ptsBot.push({ x, y: yBot });
+          cum[i] += v;
+        }
+        const color = this._colorOf(s, ser);
+        const cps = M.bezierControlPoints(ptsTop);
+        // Area: bezier top + linear bottom (reversed)
+        const ctx = e.ctx;
+        ctx.beginPath();
+        ctx.moveTo(ptsTop[0].x, ptsTop[0].y);
+        for (let i = 0; i < cps.length; i++) {
+          ctx.bezierCurveTo(cps[i].c1x, cps[i].c1y, cps[i].c2x, cps[i].c2y, ptsTop[i+1].x, ptsTop[i+1].y);
+        }
+        for (let i = ptsBot.length - 1; i >= 0; i--) ctx.lineTo(ptsBot[i].x, ptsBot[i].y);
+        ctx.closePath();
+        ctx.fillStyle = M.colorAlpha(color, 0.7);
+        ctx.fill();
+        ctx.strokeStyle = color;
+        ctx.lineWidth = lineW;
+        ctx.stroke();
+        seriesPts.push({ ser, color, ptsTop });
+      }
+    } else {
+      for (let s = 0; s < series.length; s++) {
+        const ser = series[s];
+        const pts = [];
+        for (let i = 0; i < cats.length; i++) {
+          pts.push({
+            x: ax.px + ((i + 0.5) / cats.length) * ax.pw,
+            y: ax.yToPx(+ser.values[i] || 0),
+          });
+        }
+        const color = this._colorOf(s, ser);
+        const cps = M.bezierControlPoints(pts);
+        const grad = e.vGradient(`area-${s}-${color}`, ax.px, ax.py, ax.py + ax.ph, [
+          [0, M.colorAlpha(color, 0.4)],
+          [1, M.colorAlpha(color, 0)],
+        ]);
+        e.smoothArea(pts, cps, ax.py + ax.ph, grad);
+        e.smooth(pts, cps, { stroke: color, lineWidth: lineW });
+      }
+    }
+
+    e.unclip();
+    this._drawLegend(series.map((s, i) => ({
+      label: s.name || 'Series ' + (i + 1),
+      color: this._colorOf(i, s), idx: i, hidden: false,
+    })), ax.pw);
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 5. STACKED BAR
+// ─────────────────────────────────────────────────────────
+export class StackedBarChart extends Chart {
+  _render() {
+    const series = this.options.series || [];
+    const cats = this.options.categories || [];
+    if (!series.length || !cats.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+
+    const totals = cats.map((_, i) => series.reduce((a, s) => a + (+s.values[i] || 0), 0));
+    const [yLo, yHi] = M.niceDomain(0, Math.max(...totals), 5);
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLabels: cats,
+      yTickFormat: this.options.yTickFormat,
+    });
+
+    const slot = ax.pw / cats.length;
+    const barW = Math.max(2, Math.min(50, slot - 10));
+    const prog = this._anim.progress;
+    const groups = new Map();
+
+    for (let i = 0; i < cats.length; i++) {
+      let cum = 0;
+      const x = ax.px + (i + 0.5) * slot - barW / 2;
+      for (let s = 0; s < series.length; s++) {
+        const v = +series[s].values[i] || 0;
+        if (v <= 0) continue;
+        const segH = ((v / yHi) * ax.ph) * prog;
+        const y = ax.yToPx(cum + v);
+        cum += v;
+        const color = this._colorOf(s, series[s]);
+        if (!groups.has(color)) groups.set(color, []);
+        const isTop = s === series.length - 1;
+        groups.get(color).push({
+          x, y, w: barW, h: segH,
+          radius: isTop ? t.barRadius : 0,
+        });
+        this.hits.add({
+          _id: `${i}-${s}`, x, y, w: barW, h: segH,
+          tipX: x + barW / 2, tipY: y,
+          tooltip: {
+            title: cats[i],
+            rows: [{
+              color, name: series[s].name || 'Series ' + (s + 1), value: v,
+            }],
+          },
+        });
+      }
+    }
+    for (const [color, items] of groups) e.rects(items, color);
+
+    this._drawLegend(series.map((s, i) => ({
+      label: s.name || 'Series ' + (i + 1),
+      color: this._colorOf(i, s), idx: i, hidden: false,
+    })), ax.pw);
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 6. GROUPED BAR  (clustered)
+// ─────────────────────────────────────────────────────────
+export class GroupedBarChart extends Chart {
+  _render() {
+    const series = this.options.series || [];
+    const cats = this.options.categories || [];
+    if (!series.length || !cats.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+
+    let yMax = -Infinity;
+    for (const s of series) for (const v of s.values) if (+v > yMax) yMax = +v;
+    const [yLo, yHi] = M.niceDomain(0, yMax, 5);
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLabels: cats,
+      yTickFormat: this.options.yTickFormat,
+    });
+
+    const slot = ax.pw / cats.length;
+    const inner = slot * 0.8;
+    const barW = Math.max(2, inner / series.length);
+    const prog = this._anim.progress;
+    const groups = new Map();
+
+    for (let i = 0; i < cats.length; i++) {
+      const xCenter = ax.px + (i + 0.5) * slot;
+      const left = xCenter - inner / 2;
+      for (let s = 0; s < series.length; s++) {
+        const v = +series[s].values[i] || 0;
+        const x = left + s * barW;
+        const h = ((v / yHi) * ax.ph) * prog;
+        const y = ax.yToPx(v);
+        const color = this._colorOf(s, series[s]);
+        if (!groups.has(color)) groups.set(color, []);
+        groups.get(color).push({ x, y, w: barW - 1, h, radius: t.barRadius });
+        this.hits.add({
+          _id: `${i}-${s}`, x, y, w: barW - 1, h,
+          tipX: x + barW / 2, tipY: y,
+          tooltip: `${cats[i]} · ${series[s].name || s}: ${v}`,
+        });
+      }
+    }
+    for (const [color, items] of groups) e.rects(items, color);
+
+    this._drawLegend(series.map((s, i) => ({
+      label: s.name || 'Series ' + (i + 1),
+      color: this._colorOf(i, s), idx: i, hidden: false,
+    })), ax.pw);
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 7. MULTI-LINE  (multiple series, shared x)
+// ─────────────────────────────────────────────────────────
+export class MultiLineChart extends Chart {
+  _render() {
+    const series = this.options.series || [];
+    const cats = this.options.categories || [];
+    if (!series.length || !cats.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const interp = this.options.interpolation || 'smooth';
+
+    let yMax = -Infinity, yMin = Infinity;
+    for (const s of series) for (const v of s.values) {
+      if (+v > yMax) yMax = +v;
+      if (+v < yMin) yMin = +v;
+    }
+    const [yLo, yHi] = M.niceDomain(Math.min(0, yMin), yMax, 5);
+    const useTime = this.options.xScale === 'time';
+    let spec = {
+      yMin: yLo, yMax: yHi,
+      yTickFormat: this.options.yTickFormat,
+      xTickFormat: this.options.xTickFormat,
+    };
+    if (useTime) {
+      spec.xTime = { min: +cats[0], max: +cats[cats.length - 1] };
+    } else {
+      spec.xLabels = cats;
+    }
+    const ax = this._drawCartesian(spec);
+    const lineW = t.lineWidth;
+    const prog = this._anim.progress;
+
+    e.clip(ax.px, ax.py, ax.pw * prog, ax.ph);
+    const allPts = [];
+    for (let s = 0; s < series.length; s++) {
+      const ser = series[s];
+      if (ser.hidden) continue;
+      const color = this._colorOf(s, ser);
+      const pts = ser.values.map((v, i) => ({
+        x: useTime ? ax.xToPx(+cats[i]) : ax.px + ((i + 0.5) / cats.length) * ax.pw,
+        y: ax.yToPx(+v),
+        i, s, v,
+      }));
+      allPts.push({ pts, color, s, ser });
+      if (interp === 'smooth') {
+        const cps = M.bezierControlPoints(pts);
+        e.smooth(pts, cps, { stroke: color, lineWidth: lineW });
+      } else if (interp === 'linear') {
+        e.poly(pts, { stroke: color, lineWidth: lineW, cap: 'round', join: 'round' });
+      } else {
+        const mode = interp === 'step' ? 'before' : interp.split('-')[1];
+        e.step(pts, mode, { stroke: color, lineWidth: lineW });
+      }
+      if (ser.values.length <= 50) e.circles(pts, color, t.pointRadius);
+    }
+    e.unclip();
+
+    // Shared crosshair tooltip
+    if (this._cursor && allPts.length) {
+      const cx = this._cursor.x;
+      if (cx >= ax.px && cx <= ax.px + ax.pw) {
+        // Find nearest category
+        const i = useTime
+          ? Math.round(((cx - ax.px) / ax.pw) * (cats.length - 1))
+          : Math.floor((cx - ax.px) / (ax.pw / cats.length));
+        const idx = Math.max(0, Math.min(cats.length - 1, i));
+        const xPx = useTime
+          ? ax.xToPx(+cats[idx])
+          : ax.px + (idx + 0.5) * (ax.pw / cats.length);
+        // Crosshair line
+        e.poly([{x: xPx, y: ax.py}, {x: xPx, y: ax.py + ax.ph}], {
+          stroke: t.muted, lineWidth: 1, dash: [3, 3],
+        });
+        // Snap markers
+        const rows = [];
+        for (const sp of allPts) {
+          const p = sp.pts[idx];
+          if (!p) continue;
+          e.circle(p.x, p.y, t.pointRadius + 2, {
+            fill: t.bg, stroke: sp.color, lineWidth: 2,
+          });
+          rows.push({
+            color: sp.color,
+            name: sp.ser.name || 'Series ' + (sp.s + 1),
+            value: sp.ser.values[idx],
+          });
+        }
+        const title = useTime
+          ? new Date(+cats[idx]).toISOString().slice(0, 19).replace('T', ' ')
+          : String(cats[idx]);
+        this.tooltip.show(xPx, ax.py + 8, { title, rows }, t);
+        this._sharedTooltip = true;
+      }
+    }
+
+    this._drawLegend(series.map((s, i) => ({
+      label: s.name || 'Series ' + (i + 1),
+      color: this._colorOf(i, s), idx: i, hidden: !!s.hidden,
+    })), ax.pw);
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 8. SCATTER
+// ─────────────────────────────────────────────────────────
+export class ScatterChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    let xMin = Infinity, xMax = -Infinity, yMin = Infinity, yMax = -Infinity;
+    for (const d of data) {
+      if (d.x < xMin) xMin = d.x; if (d.x > xMax) xMax = d.x;
+      if (d.y < yMin) yMin = d.y; if (d.y > yMax) yMax = d.y;
+    }
+    const [xLo, xHi] = M.niceDomain(xMin, xMax, 6);
+    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLinear: { min: xLo, max: xHi },
+    });
+    const prog = this._anim.progress;
+    const groups = new Map();
+    const defaultR = t.pointRadius + 1;
+
+    for (let i = 0; i < data.length; i++) {
+      const d = data[i];
+      const cx = ax.xToPx(d.x);
+      const cy = ax.yToPx(d.y);
+      const r = (d.r || defaultR) * prog;
+      const g = d.group != null ? d.group : 0;
+      const color = this._colorOf(g, { color: d.color });
+      const key = color + ':' + r.toFixed(1);
+      if (!groups.has(key)) groups.set(key, { color, r, items: [] });
+      groups.get(key).items.push({ x: cx, y: cy });
+      this.hits.add({
+        _id: i, x: cx - r - 2, y: cy - r - 2, w: r * 2 + 4, h: r * 2 + 4,
+        tipX: cx, tipY: cy - r,
+        tooltip: `(${d.x}, ${d.y})${d.label ? ` · ${d.label}` : ''}`,
+      });
+    }
+    e.withAlpha(0.7, () => {
+      for (const { color, r, items } of groups.values()) e.circles(items, color, r);
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 9. BUBBLE  (scatter with explicit z radius)
+// ─────────────────────────────────────────────────────────
+export class BubbleChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    let xMin = Infinity, xMax = -Infinity, yMin = Infinity, yMax = -Infinity, zMax = 0;
+    for (const d of data) {
+      if (d.x < xMin) xMin = d.x; if (d.x > xMax) xMax = d.x;
+      if (d.y < yMin) yMin = d.y; if (d.y > yMax) yMax = d.y;
+      if ((d.z || 0) > zMax) zMax = d.z;
+    }
+    const [xLo, xHi] = M.niceDomain(xMin, xMax, 6);
+    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLinear: { min: xLo, max: xHi },
+    });
+    const prog = this._anim.progress;
+    const maxR = 32, minR = 4;
+
+    for (let i = 0; i < data.length; i++) {
+      const d = data[i];
+      const cx = ax.xToPx(d.x);
+      const cy = ax.yToPx(d.y);
+      const r = (minR + (Math.sqrt((d.z || 0) / Math.max(1, zMax))) * (maxR - minR)) * prog;
+      const color = d.color || this._colorOf(d.group != null ? d.group : i);
+      e.circle(cx, cy, r, {
+        fill: M.colorAlpha(color, 0.5),
+        stroke: color, lineWidth: 1.5,
+      });
+      this.hits.add({
+        _id: i, x: cx - r, y: cy - r, w: r * 2, h: r * 2,
+        tipX: cx, tipY: cy - r,
+        tooltip: `${d.label || ''} (${d.x}, ${d.y}) · z=${d.z}`,
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 10. PIE / DONUT
+// ─────────────────────────────────────────────────────────
+export class PieChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const labelOf = this.options.label || (d => d.label);
+    const valueOf = this.options.value || (d => d.value);
+    const total = data.reduce((a, d, i) => a + valueOf(d, i), 0);
+    if (total <= 0) { this.setEmpty('No data'); return; }
+
+    const cx = e.w / 2, cy = e.h / 2 + 4;
+    const R = Math.min(e.w, e.h) / 2 - 24;
+    const innerR = this.options.innerRadius != null
+      ? (typeof this.options.innerRadius === 'number'
+         ? this.options.innerRadius
+         : R * 0.55)
+      : 0;
+    const prog = this._anim.progress;
+    let a0 = -Math.PI / 2;
+    for (let i = 0; i < data.length; i++) {
+      const v = valueOf(data[i], i);
+      const sweep = (v / total) * TAU * prog;
+      const a1 = a0 + sweep;
+      const color = this._colorOf(i, data[i]);
+      const isHover = this._hover && this._hover._id === i;
+      const offset = isHover ? 6 : 0;
+      const mid = (a0 + a1) / 2;
+      const ox = Math.cos(mid) * offset, oy = Math.sin(mid) * offset;
+      e.arc(cx + ox, cy + oy, innerR, R, a0, a1, { fill: color });
+      // Hit region: approximate with bounding box around sector midpoint
+      const midR = (innerR + R) / 2;
+      const hx = cx + Math.cos(mid) * midR;
+      const hy = cy + Math.sin(mid) * midR;
+      this.hits.add({
+        _id: i, x: hx - 12, y: hy - 12, w: 24, h: 24,
+        tipX: hx, tipY: hy - 8,
+        tooltip: `${labelOf(data[i], i)}: ${v} (${(v / total * 100).toFixed(1)}%)`,
+      });
+      a0 = a1;
+    }
+    // Center label for donut
+    if (innerR > 0 && this.options.centerLabel !== false) {
+      const center = this._hover
+        ? `${(valueOf(data[this._hover._id], this._hover._id) / total * 100).toFixed(0)}%`
+        : (this.options.totalLabel || total.toLocaleString());
+      e.text(center, cx, cy, {
+        fill: t.text, font: `600 ${t.fontSize * 1.6}px ${t.font}`,
+        align: 'center', baseline: 'middle',
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 11. RADAR
+// ─────────────────────────────────────────────────────────
+export class RadarChart extends Chart {
+  _render() {
+    const series = this.options.series || [];
+    const axes = this.options.axes || [];
+    if (!series.length || !axes.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const cx = e.w / 2;
+    const cy = e.h / 2 + 4;
+    const R = Math.min(e.w, e.h) / 2 - 32;
+    const N = axes.length;
+    const angle = i => -Math.PI / 2 + (i / N) * TAU;
+
+    let max = -Infinity;
+    for (const s of series) for (const v of s.values) if (+v > max) max = +v;
+    const yLo = 0;
+    const niceMax = M.niceDomain(0, max, 5)[1];
+
+    // Concentric rings
+    const rings = M.niceTicks(0, niceMax, 4).filter(v => v > 0);
+    e.ctx.strokeStyle = t.grid;
+    e.ctx.lineWidth = 1;
+    for (const v of rings) {
+      const r = (v / niceMax) * R;
+      e.ctx.beginPath();
+      for (let i = 0; i <= N; i++) {
+        const a = angle(i % N);
+        const x = cx + Math.cos(a) * r;
+        const y = cy + Math.sin(a) * r;
+        if (i === 0) e.ctx.moveTo(x, y); else e.ctx.lineTo(x, y);
+      }
+      e.ctx.stroke();
+    }
+    // Spokes
+    e.ctx.strokeStyle = t.grid;
+    for (let i = 0; i < N; i++) {
+      const a = angle(i);
+      e.ctx.beginPath();
+      e.ctx.moveTo(cx, cy);
+      e.ctx.lineTo(cx + Math.cos(a) * R, cy + Math.sin(a) * R);
+      e.ctx.stroke();
+    }
+    // Axis labels
+    const font = `${t.fontSize}px ${t.font}`;
+    for (let i = 0; i < N; i++) {
+      const a = angle(i);
+      const lx = cx + Math.cos(a) * (R + 14);
+      const ly = cy + Math.sin(a) * (R + 14);
+      e.text(axes[i], lx, ly, {
+        fill: t.muted, font,
+        align: Math.cos(a) > 0.3 ? 'left' : Math.cos(a) < -0.3 ? 'right' : 'center',
+        baseline: Math.sin(a) > 0.3 ? 'top' : Math.sin(a) < -0.3 ? 'bottom' : 'middle',
+      });
+    }
+    const prog = this._anim.progress;
+    for (let s = 0; s < series.length; s++) {
+      const ser = series[s];
+      const color = this._colorOf(s, ser);
+      const pts = [];
+      for (let i = 0; i < N; i++) {
+        const v = (+ser.values[i] || 0) * prog;
+        const r = (v / niceMax) * R;
+        const a = angle(i);
+        pts.push({ x: cx + Math.cos(a) * r, y: cy + Math.sin(a) * r });
+      }
+      e.poly(pts, {
+        fill: M.colorAlpha(color, 0.25),
+        stroke: color, lineWidth: 2, close: true,
+      });
+      e.circles(pts, color, t.pointRadius);
+    }
+    this._drawLegend(series.map((s, i) => ({
+      label: s.name || 'Series ' + (i + 1),
+      color: this._colorOf(i, s), idx: i, hidden: false,
+    })), e.w - 16);
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 12. POLAR  (radial bars)
+// ─────────────────────────────────────────────────────────
+export class PolarChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const labelOf = this.options.label || (d => d.label);
+    const valueOf = this.options.value || (d => d.value);
+    const N = data.length;
+    const cx = e.w / 2, cy = e.h / 2 + 4;
+    const R = Math.min(e.w, e.h) / 2 - 24;
+    const max = Math.max(...data.map((d, i) => valueOf(d, i)));
+    const prog = this._anim.progress;
+
+    for (let i = 0; i < N; i++) {
+      const v = valueOf(data[i], i);
+      const a0 = -Math.PI / 2 + (i / N) * TAU;
+      const a1 = a0 + (TAU / N) * 0.92;
+      const r = (v / max) * R * prog;
+      const color = this._colorOf(i, data[i]);
+      e.arc(cx, cy, 0, r, a0, a1, { fill: color });
+      // Label
+      const mid = (a0 + a1) / 2;
+      const lx = cx + Math.cos(mid) * (R + 12);
+      const ly = cy + Math.sin(mid) * (R + 12);
+      e.text(labelOf(data[i], i), lx, ly, {
+        fill: t.muted, font: `${t.fontSize}px ${t.font}`,
+        align: 'center', baseline: 'middle',
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 13. GAUGE
+// ─────────────────────────────────────────────────────────
+export class GaugeChart extends Chart {
+  setValue(v) {
+    this.options.value = v;
+    this._anim.start = performance.now();
+    this._anim.progress = 0;
+    this._dirty = true;
+    scheduler.schedule(this);
+    return this;
+  }
+  _render() {
+    const e = this.engine;
+    const t = this.theme;
+    const val = this.options.value || 0;
+    const max = this.options.max || 100;
+    const cx = e.w / 2;
+    const cy = e.h * 0.7;
+    const R = Math.min(e.w / 2, e.h * 0.7) - 12;
+    const r = R - 18;
+    const a0 = Math.PI * 1.1;
+    const a1 = Math.PI * 1.9;
+    const span = a1 - a0;
+    const prog = this._anim.progress;
+    const color = this.options.color || this.palette[0];
+    // Track
+    e.arc(cx, cy, r, R, a0, a1, { fill: t.grid });
+    // Filled
+    const aEnd = a0 + span * (val / max) * prog;
+    if (aEnd > a0) e.arc(cx, cy, r, R, a0, aEnd, { fill: color });
+    // Number
+    const num = Math.round(val);
+    const unit = this.options.unit || '';
+    e.text(`${num}${unit}`, cx, cy, {
+      fill: t.text, font: `700 ${R / 2.5}px ${t.font}`,
+      align: 'center', baseline: 'middle',
+    });
+    if (this.options.label) {
+      e.text(this.options.label, cx, cy + R / 2.5, {
+        fill: t.muted, font: `${t.fontSize}px ${t.font}`,
+        align: 'center', baseline: 'top',
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 14. HEATMAP
+// ─────────────────────────────────────────────────────────
+export class HeatmapChart extends Chart {
+  _axisPad() { return { l: 60, r: 16, t: 16, b: 40 }; }
+  _render() {
+    const data = this.options.data || []; // [{ x, y, value }]
+    const xLabels = this.options.xLabels || [];
+    const yLabels = this.options.yLabels || [];
+    if (!data.length || !xLabels.length || !yLabels.length) {
+      this.setEmpty('No data'); return;
+    }
+    const e = this.engine;
+    const t = this.theme;
+    const pad = this._axisPad();
+    const px = pad.l, py = pad.t;
+    const pw = e.w - pad.l - pad.r;
+    const ph = e.h - pad.t - pad.b;
+    const font = `${t.fontSize}px ${t.font}`;
+
+    let vMax = -Infinity, vMin = Infinity;
+    for (const d of data) {
+      if (d.value > vMax) vMax = d.value;
+      if (d.value < vMin) vMin = d.value;
+    }
+    const cellW = pw / xLabels.length;
+    const cellH = ph / yLabels.length;
+    const lo = this.options.colorLow || M.colorAlpha(this.palette[0], 0.1);
+    const hi = this.options.colorHigh || this.palette[0];
+    const gap = 1;
+    const prog = this._anim.progress;
+
+    for (const d of data) {
+      const xi = typeof d.x === 'number' ? d.x : xLabels.indexOf(d.x);
+      const yi = typeof d.y === 'number' ? d.y : yLabels.indexOf(d.y);
+      if (xi < 0 || yi < 0) continue;
+      const x = px + xi * cellW;
+      const y = py + yi * cellH;
+      const tNorm = vMax > vMin ? (d.value - vMin) / (vMax - vMin) : 0.5;
+      const fill = M.colorMix(lo, hi, tNorm * prog);
+      e.rect(x + gap, y + gap, cellW - gap * 2, cellH - gap * 2, { fill, radius: 2 });
+      this.hits.add({
+        _id: `${xi}-${yi}`, x, y, w: cellW, h: cellH,
+        tipX: x + cellW / 2, tipY: y,
+        tooltip: `${xLabels[xi]} · ${yLabels[yi]}: ${d.value}`,
+      });
+    }
+    // X labels
+    for (let i = 0; i < xLabels.length; i++) {
+      e.text(xLabels[i], px + (i + 0.5) * cellW, py + ph + 4, {
+        fill: t.muted, font, align: 'center', baseline: 'top',
+      });
+    }
+    // Y labels
+    for (let i = 0; i < yLabels.length; i++) {
+      e.text(yLabels[i], px - 6, py + (i + 0.5) * cellH, {
+        fill: t.muted, font, align: 'right', baseline: 'middle',
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 15. BOXPLOT
+// ─────────────────────────────────────────────────────────
+export class BoxplotChart extends Chart {
+  _render() {
+    const data = this.options.data || []; // [{ label, q1, median, q3, min, max, outliers? }]
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    let yMax = -Infinity, yMin = Infinity;
+    for (const d of data) {
+      if (d.max > yMax) yMax = d.max; if (d.min < yMin) yMin = d.min;
+      if (d.outliers) for (const o of d.outliers) {
+        if (o > yMax) yMax = o; if (o < yMin) yMin = o;
+      }
+    }
+    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLabels: data.map(d => d.label),
+    });
+    const slot = ax.pw / data.length;
+    const boxW = Math.min(40, slot * 0.5);
+
+    for (let i = 0; i < data.length; i++) {
+      const d = data[i];
+      const cx = ax.px + (i + 0.5) * slot;
+      const yMin = ax.yToPx(d.min);
+      const yMax = ax.yToPx(d.max);
+      const yQ1 = ax.yToPx(d.q1);
+      const yQ3 = ax.yToPx(d.q3);
+      const yMed = ax.yToPx(d.median);
+      const color = this._colorOf(i, d);
+      // Whiskers
+      e.poly([{x: cx, y: yMax}, {x: cx, y: yMin}], { stroke: color, lineWidth: 1 });
+      e.poly([{x: cx - boxW / 3, y: yMax}, {x: cx + boxW / 3, y: yMax}], { stroke: color, lineWidth: 1 });
+      e.poly([{x: cx - boxW / 3, y: yMin}, {x: cx + boxW / 3, y: yMin}], { stroke: color, lineWidth: 1 });
+      // Box
+      e.rect(cx - boxW / 2, yQ3, boxW, yQ1 - yQ3, {
+        fill: M.colorAlpha(color, 0.4),
+        stroke: color, lineWidth: 1.5,
+      });
+      // Median line
+      e.poly([{x: cx - boxW / 2, y: yMed}, {x: cx + boxW / 2, y: yMed}], {
+        stroke: color, lineWidth: 2,
+      });
+      // Outliers
+      if (d.outliers) {
+        e.circles(d.outliers.map(v => ({ x: cx, y: ax.yToPx(v) })), color, 2);
+      }
+      this.hits.add({
+        _id: i, x: cx - boxW / 2, y: yQ3, w: boxW, h: yQ1 - yQ3,
+        tipX: cx, tipY: yQ3,
+        tooltip: {
+          title: d.label,
+          rows: [
+            { name: 'min', value: d.min },
+            { name: 'Q1', value: d.q1 },
+            { name: 'med', value: d.median },
+            { name: 'Q3', value: d.q3 },
+            { name: 'max', value: d.max },
+          ],
+        },
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 16. FUNNEL
+// ─────────────────────────────────────────────────────────
+export class FunnelChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const labelOf = this.options.label || (d => d.label);
+    const valueOf = this.options.value || (d => d.value);
+    const N = data.length;
+    const max = Math.max(...data.map((d, i) => valueOf(d, i)));
+    const pad = 24;
+    const w = e.w - pad * 2;
+    const segH = (e.h - pad * 2) / N;
+    const cx = e.w / 2;
+    const prog = this._anim.progress;
+    const font = `${t.fontSize}px ${t.font}`;
+
+    for (let i = 0; i < N; i++) {
+      const v = valueOf(data[i], i);
+      const wTop = (v / max) * w * prog;
+      const wBot = i + 1 < N
+        ? (valueOf(data[i + 1], i + 1) / max) * w * prog
+        : wTop * 0.85;
+      const yTop = pad + i * segH;
+      const yBot = yTop + segH - 2;
+      const color = this._colorOf(i, data[i]);
+      const trap = [
+        { x: cx - wTop / 2, y: yTop },
+        { x: cx + wTop / 2, y: yTop },
+        { x: cx + wBot / 2, y: yBot },
+        { x: cx - wBot / 2, y: yBot },
+      ];
+      e.poly(trap, { fill: color, close: true });
+      // Label
+      e.text(`${labelOf(data[i], i)}  ${v}`, cx, yTop + segH / 2, {
+        fill: '#fff', font: `600 ${t.fontSize}px ${t.font}`,
+        align: 'center', baseline: 'middle',
+      });
+      this.hits.add({
+        _id: i, x: cx - wTop / 2, y: yTop, w: wTop, h: segH,
+        tipX: cx, tipY: yTop,
+        tooltip: `${labelOf(data[i], i)}: ${v} (${(v / max * 100).toFixed(1)}%)`,
+      });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 17. TREEMAP
+// ─────────────────────────────────────────────────────────
+export class TreemapChart extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    const labelOf = this.options.label || (d => d.label);
+    const valueOf = this.options.value || (d => d.value);
+    const items = data.map((d, i) => ({
+      label: labelOf(d, i), value: valueOf(d, i), color: this._colorOf(i, d), data: d, _id: i,
+    })).sort((a, b) => b.value - a.value);
+    const total = items.reduce((a, x) => a + x.value, 0);
+    const rect = { x: 4, y: 4, w: e.w - 8, h: e.h - 8 };
+    const prog = this._anim.progress;
+    squarify(items, total, rect, (it, r) => {
+      const padIn = 2;
+      const x = r.x + padIn, y = r.y + padIn;
+      const w = (r.w - padIn * 2) * prog;
+      const h = (r.h - padIn * 2) * prog;
+      if (w < 1 || h < 1) return;
+      e.rect(x, y, w, h, { fill: it.color, radius: 2 });
+      // Text only if box is big enough.
+      if (w > 60 && h > 30) {
+        e.text(it.label, x + 6, y + 6, {
+          fill: '#fff', font: `600 ${t.fontSize}px ${t.font}`,
+          align: 'left', baseline: 'top',
+        });
+        e.text(String(it.value), x + 6, y + 6 + t.fontSize + 2, {
+          fill: 'rgba(255,255,255,0.85)', font: `${t.fontSize}px ${t.font}`,
+          align: 'left', baseline: 'top',
+        });
+      }
+      this.hits.add({
+        _id: it._id, x, y, w, h,
+        tipX: x + w / 2, tipY: y,
+        tooltip: `${it.label}: ${it.value}`,
+      });
+    });
+  }
+}
+
+// Squarified treemap layout (Bruls et al.)
+function squarify(items, total, rect, draw) {
+  if (!items.length) return;
+  const area = rect.w * rect.h;
+  let i = 0;
+  while (i < items.length) {
+    const remaining = items.slice(i);
+    const remTotal = remaining.reduce((a, x) => a + x.value, 0);
+    if (remTotal <= 0) break;
+    const remArea = (remTotal / total) * area;
+    // Place first row.
+    const w = Math.min(rect.w, rect.h);
+    let row = [], rowSum = 0;
+    let bestRatio = Infinity;
+    for (let j = 0; j < remaining.length; j++) {
+      const next = remaining[j];
+      const trialSum = rowSum + next.value;
+      const trialAreaPx = (trialSum / remTotal) * remArea;
+      const trialW = trialAreaPx / w;
+      let worst = 0;
+      for (const r of [...row, next]) {
+        const a = (r.value / trialSum) * trialAreaPx;
+        const ratio = Math.max(trialW / (a / trialW), (a / trialW) / trialW);
+        if (ratio > worst) worst = ratio;
+      }
+      if (worst > bestRatio) break;
+      bestRatio = worst;
+      row.push(next);
+      rowSum = trialSum;
+    }
+    if (!row.length) row = [remaining[0]], rowSum = remaining[0].value;
+    const isHoriz = rect.w >= rect.h;
+    const rowAreaPx = (rowSum / remTotal) * remArea;
+    const stripT = rowAreaPx / w;
+    let cursor = isHoriz ? rect.y : rect.x;
+    for (const it of row) {
+      const itLen = ((it.value / rowSum) * rowAreaPx) / stripT;
+      const r = isHoriz
+        ? { x: rect.x, y: cursor, w: stripT, h: itLen }
+        : { x: cursor, y: rect.y, w: itLen, h: stripT };
+      // Re-orient: row strip is along the *short* side
+      const r2 = isHoriz
+        ? { x: rect.x, y: cursor, w: stripT, h: itLen }
+        : { x: cursor, y: rect.y, w: itLen, h: stripT };
+      // Actually a simpler placement: put strip on the short edge
+      const placedRect = isHoriz
+        ? { x: rect.x, y: cursor, w: stripT, h: itLen }
+        : { x: cursor, y: rect.y, w: itLen, h: stripT };
+      draw(it, placedRect);
+      cursor += itLen;
+    }
+    if (isHoriz) {
+      rect.x += stripT;
+      rect.w -= stripT;
+    } else {
+      rect.y += stripT;
+      rect.h -= stripT;
+    }
+    i += row.length;
+    if (rect.w < 1 || rect.h < 1) break;
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 18. SPARKLINE  (mini line, no axes)
+// ─────────────────────────────────────────────────────────
+export class Sparkline extends Chart {
+  _render() {
+    const data = this.options.data || [];
+    if (!data.length) return;
+    const e = this.engine;
+    const t = this.theme;
+    const valueOf = this.options.value || (v => +v);
+    const values = data.map(valueOf);
+    const yMin = Math.min(...values), yMax = Math.max(...values);
+    const yRange = yMax - yMin || 1;
+    const pad = 2;
+    const w = e.w - pad * 2;
+    const h = e.h - pad * 2;
+    const points = values.map((v, i) => ({
+      x: pad + (i / (values.length - 1 || 1)) * w,
+      y: pad + h - ((v - yMin) / yRange) * h,
+    }));
+    const color = this.options.color || this.palette[0];
+    const cps = M.bezierControlPoints(points);
+    if (this.options.fill !== false) {
+      const grad = e.vGradient(`spark-${color}`, 0, pad, pad + h, [
+        [0, M.colorAlpha(color, 0.3)],
+        [1, M.colorAlpha(color, 0)],
+      ]);
+      e.smoothArea(points, cps, pad + h, grad);
+    }
+    e.smooth(points, cps, { stroke: color, lineWidth: t.lineWidth });
+    if (this.options.lastDot !== false) {
+      const last = points[points.length - 1];
+      e.circle(last.x, last.y, t.pointRadius + 1, { fill: color });
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 19. REALTIME (streaming line, ring buffer)
+// ─────────────────────────────────────────────────────────
+export class RealtimeChart extends Chart {
+  constructor(container, options = {}) {
+    super(container, options);
+    this.options.windowSize = options.windowSize || 200;
+    this._series = (options.series || []).map(s => ({
+      name: s.name || 'Series', color: s.color, values: [], hidden: false,
+    }));
+    this._streaming = true;
+  }
+  push(values) {
+    const arr = Array.isArray(values) ? values : [values];
+    for (let i = 0; i < this._series.length; i++) {
+      const s = this._series[i];
+      s.values.push(arr[i] != null ? arr[i] : 0);
+      if (s.values.length > this.options.windowSize) s.values.shift();
+    }
+    // Clear any auto-set empty state from a prior render.
+    if (this._state === 'empty') this._state = null;
+    this._dirty = true;
+    scheduler.schedule(this);
+  }
+  clear() {
+    for (const s of this._series) s.values.length = 0;
+    this._dirty = true;
+    scheduler.schedule(this);
+  }
+  _render() {
+    const e = this.engine;
+    const t = this.theme;
+    const hasData = this._series.some(s => s.values.length > 0);
+
+    // No data yet: draw an empty axis grid and an inline hint, but do NOT
+    // call setEmpty() — that would lock us into the overlay state and stop
+    // future _render calls from running.
+    if (!hasData) {
+      const ax = this._drawCartesian({
+        yMin: 0, yMax: 100,
+        yTickFormat: this.options.yTickFormat,
+      });
+      e.text('streaming…', ax.px + ax.pw / 2, ax.py + ax.ph / 2, {
+        fill: t.muted, font: `${t.fontSize}px ${t.font}`,
+        align: 'center', baseline: 'middle',
+      });
+      return;
+    }
+
+    let yMin = Infinity, yMax = -Infinity;
+    for (const s of this._series) for (const v of s.values) {
+      if (v < yMin) yMin = v;
+      if (v > yMax) yMax = v;
+    }
+    const [yLo, yHi] = M.niceDomain(Math.min(0, yMin), yMax, 5);
+    const N = this.options.windowSize;
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      yTickFormat: this.options.yTickFormat,
+    });
+    for (let s = 0; s < this._series.length; s++) {
+      const ser = this._series[s];
+      if (ser.hidden) continue;
+      const color = this._colorOf(s, ser);
+      const pts = ser.values.map((v, i) => ({
+        x: ax.px + (i / (N - 1)) * ax.pw,
+        y: ax.yToPx(v),
+      }));
+      if (pts.length < 2) {
+        if (pts.length === 1) e.circle(pts[0].x, pts[0].y, t.pointRadius + 2, { fill: color });
+        continue;
+      }
+      const cps = M.bezierControlPoints(pts);
+      e.smooth(pts, cps, { stroke: color, lineWidth: t.lineWidth });
+      // Pulse the latest point
+      const last = pts[pts.length - 1];
+      e.circle(last.x, last.y, t.pointRadius + 2, { fill: color });
+    }
+    this._drawLegend(this._series.map((s, i) => ({
+      label: s.name, color: this._colorOf(i, s), idx: i, hidden: s.hidden,
+    })), ax.pw);
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// 20. WATERFALL
+// ─────────────────────────────────────────────────────────
+export class WaterfallChart extends Chart {
+  _render() {
+    const data = this.options.data || []; // [{label, value, isTotal?}]
+    if (!data.length) { this.setEmpty('No data'); return; }
+    const e = this.engine;
+    const t = this.theme;
+    let cum = 0;
+    const segs = data.map(d => {
+      if (d.isTotal) {
+        const seg = { from: 0, to: d.value, value: d.value, isTotal: true, label: d.label };
+        cum = d.value;
+        return seg;
+      } else {
+        const seg = { from: cum, to: cum + d.value, value: d.value, label: d.label };
+        cum += d.value;
+        return seg;
+      }
+    });
+    const allVals = segs.flatMap(s => [s.from, s.to]);
+    const [yLo, yHi] = M.niceDomain(Math.min(...allVals, 0), Math.max(...allVals), 5);
+    const ax = this._drawCartesian({
+      yMin: yLo, yMax: yHi,
+      xLabels: data.map(d => d.label),
+    });
+    const slot = ax.pw / segs.length;
+    const barW = Math.max(2, Math.min(60, slot - 12));
+    const prog = this._anim.progress;
+    const upColor = this.options.colorUp || '#10b981';
+    const dnColor = this.options.colorDown || '#ef4444';
+    const totalColor = this.options.colorTotal || '#6366f1';
+
+    for (let i = 0; i < segs.length; i++) {
+      const s = segs[i];
+      const x = ax.px + (i + 0.5) * slot - barW / 2;
+      const y0 = ax.yToPx(s.from);
+      const y1 = ax.yToPx(s.to);
+      const top = Math.min(y0, y1);
+      const fullH = Math.abs(y1 - y0);
+      const h = fullH * prog;
+      const animTop = s.to >= s.from ? y0 - h : y0;
+      const color = s.isTotal ? totalColor : (s.value >= 0 ? upColor : dnColor);
+      e.rect(x, animTop, barW, h, { fill: color, radius: t.barRadius });
+      // Connecting line to next
+      if (i < segs.length - 1 && !segs[i + 1].isTotal) {
+        const nextX = ax.px + (i + 1.5) * slot - barW / 2;
+        const yEnd = ax.yToPx(s.to);
+        e.poly([{x: x + barW, y: yEnd}, {x: nextX, y: yEnd}], {
+          stroke: t.muted, lineWidth: 1, dash: [3, 3],
+        });
+      }
+      this.hits.add({
+        _id: i, x, y: animTop, w: barW, h,
+        tipX: x + barW / 2, tipY: animTop,
+        tooltip: `${s.label}: ${s.value > 0 && !s.isTotal ? '+' : ''}${s.value}`,
+      });
+    }
+  }
+}