@aeriz/chart 1.1.0 → 2.0.0

package/dist/aeriz.esm.js

@@ -1,4 +1,4 @@
-/*! @aeriz/chart v1.1.0 | Apache-2.0 | https://aeriz.dev/chart/ */
+/*! @aeriz/chart v2.0.0 | Apache-2.0 | https://aeriz.dev/chart/ */
 // ── src/math.js
 // math.js — Pure math: scales, ticks, color ops, smoothing, decimation, formatting.
 // No DOM, no canvas, no side effects.
@@ -541,17 +541,8 @@ const M = { TAU, clamp, lerp, extent, niceTicks, niceDomain, timeNiceTicks, time
 // while some chart is animating or has something to redraw.
 const charts = new Set();
 let rafId = null;
-let fps = 60;
-let frames = 0;
-let fpsT = 0;
 
 function tick(now) {
-  if (now - fpsT > 500) {
-    fps = Math.round((1000 * frames) / (now - fpsT));
-    frames = 0;
-    fpsT = now;
-  }
-  frames++;
   let active = false;
   for (const c of charts) {
     try {
@@ -564,22 +555,15 @@ function tick(now) {
 function schedule(chart) {
   if (chart._destroyed) return;
   charts.add(chart);
-  if (rafId === null) {
-    fpsT = performance.now();
-    rafId = requestAnimationFrame(tick);
-  }
+  if (rafId === null) rafId = requestAnimationFrame(tick);
 }
 
-const scheduler = { schedule, fps: () => fps, count: () => charts.size };
-function getFPS() { return fps; }
-function getActiveCount() { return charts.size; }
-
 // Media queries are shared by every chart (one listener each, not per chart).
 const mq = (q) => (typeof matchMedia === 'function' ? matchMedia(q) : null);
 const reducedMotion = mq('(prefers-reduced-motion: reduce)');
 const darkScheme = mq('(prefers-color-scheme: dark)');
 // OS light/dark switch → every chart re-reads its theme.
-darkScheme?.addEventListener?.('change', () => { for (const c of charts) c.invalidate(); });
+darkScheme?.addEventListener?.('change', () => { for (const c of charts) { c._theme(); schedule(c); } });
 
 // ─── Theme resolution ───────────────────────────────────────
 // Theme key → CSS variable: fontSize → --aeriz-font-size, tooltipBg → --aeriz-tooltip-bg …
@@ -731,28 +715,163 @@ class HitIndex {
   }
 }
 
-// Plain arrays and objects work wherever `{ label, value }` rows are expected:
-//   [3, 7, 4]            → labels 1, 2, 3
-//   { Jan: 3, Feb: 7 }   → labels Jan, Feb
-//   [['Jan', 3], …]      → labels Jan, …
+// ─── Data: one accepted shape per kind ──────────────────────
+// Single-series rows. All three give the same [{ label, value }] rows:
+//   [3, 7, 4]                        → labels 1, 2, 3
+//   { Jan: 3, Feb: 7 }               → labels Jan, Feb
+//   [{ label: 'Jan', value: 3 }, …]  (other fields: use the label/value options)
+const isList = (d) => Array.isArray(d) || ArrayBuffer.isView(d);
+const isObj = (d) => d != null && typeof d === 'object' && !isList(d);
+
 function toRows(data) {
-  if (!data) return [];
-  if (!Array.isArray(data)) {
-    return typeof data === 'object' ? Object.keys(data).map((k) => ({ label: k, value: +data[k] })) : [];
-  }
-  const first = data[0];
-  if (typeof first === 'number') return data.map((v, i) => ({ label: String(i + 1), value: v }));
-  if (Array.isArray(first)) return data.map((d) => ({ label: d[0], value: +d[1] }));
-  return data;
+  if (isList(data)) {
+    if (!data.length || Array.isArray(data[0])) return [];
+    return typeof data[0] === 'number' ? Array.from(data, (v, i) => ({ label: String(i + 1), value: v })) : data;
+  }
+  return isObj(data) ? Object.keys(data).map((k) => ({ label: k, value: +data[k] })) : [];
+}
+
+// ─── Developer warnings ─────────────────────────────────────
+// Mistakes don't fail silently: the console says what is wrong and how to fix
+// it, once per message.
+const said = new Set();
+function warn(msg) {
+  if (said.has(msg)) return;
+  said.add(msg);
+  console.warn('[aeriz] ' + msg);
+}
+
+// Options every chart takes.
+const COMMON = ['data', 'title', 'colors', 'format', 'legend', 'animate', 'emptyText', 'onClick', 'onLegend'];
+
+const SHAPES = {
+  rows: 'an array of numbers, an object like { Jan: 64 }, or rows like [{ label, value }]',
+  series: '{ categories: [...], series: [{ name, values: [...] }] }',
+  stream: '{ series: [{ name }] } (values arrive with chart.push())',
+  points: 'points like [{ x, y }]',
+  matrix: '{ x: [...], y: [...], values: [[...], ...] } with values[y][x]',
+  boxes: 'rows like [{ label, min, q1, median, q3, max }]',
+  steps: 'rows like [{ label, value }] (add total: true for a total bar)',
+  number: 'a number',
+};
+
+// 1.x option names → what to write in 2.0.
+const DATA = 'data: { categories, series }';
+const RENAMED = {
+  ariaLabel: 'title', palette: 'colors', color: 'colors',
+  xTickFormat: 'labelFormat (category axis) or format (value axis)', yTickFormat: 'format',
+  yLeftTickFormat: 'format on the series', yRightTickFormat: 'format on the series',
+  categories: DATA, series: DATA, layers: DATA, axes: DATA,
+  xLabels: 'data: { x, y, values }', yLabels: 'data: { x, y, values }',
+  interpolation: 'curve', windowSize: 'window', yMin: 'min', yMax: 'max', waitingText: 'emptyText',
+  colorLow: 'colors: { low, high }', colorHigh: 'colors: { low, high }',
+  colorUp: 'colors: { up, down, total }', colorDown: 'colors: { up, down, total }', colorTotal: 'colors: { up, down, total }',
+  minRadius: 'radius: [min, max]', maxRadius: 'radius: [min, max]',
+  centerLabel: 'center', totalLabel: 'center', type: 'the chart class itself',
+};
+const FUNCS = ['label', 'value', 'labelFormat', 'onClick', 'onLegend'];
+
+function distance(a, b) {
+  const d = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let p = d[0];
+    d[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const t = d[j];
+      d[j] = Math.min(d[j] + 1, d[j - 1] + 1, p + (a[i - 1] === b[j - 1] ? 0 : 1));
+      p = t;
+    }
+  }
+  return d[b.length];
+}
+
+function checkOptions(meta, o) {
+  const name = meta.name;
+  const allowed = [...COMMON, ...meta.options];
+  for (const k of Object.keys(o)) {
+    const v = o[k];
+    if (!allowed.includes(k)) {
+      const hint = meta.renamed?.[k] || RENAMED[k];
+      if (hint) { warn(`${name}: "${k}" is a 1.x option. In 2.0 use ${hint}.`); continue; }
+      let best = null, bd = 3;
+      for (const a of allowed) {
+        const dd = a.toLowerCase() === k.toLowerCase() ? 0 : distance(k, a);
+        if (dd < bd) { bd = dd; best = a; }
+      }
+      warn(`${name}: unknown option "${k}"${best ? ` — did you mean "${best}"?` : `. Options: ${allowed.join(', ')}`}`);
+      continue;
+    }
+    if (v == null) continue;
+    if (FUNCS.includes(k) && typeof v !== 'function') warn(`${name}: "${k}" must be a function${k === 'label' || k === 'value' ? `, like ${k}: (row) => row.${k === 'label' ? 'name' : 'amount'}` : ''}.`);
+    const en = meta.enums?.[k];
+    if (en && !en.includes(v)) warn(`${name}: ${k} must be ${en.map((x) => `'${x}'`).join(' | ')}, got ${JSON.stringify(v)}.`);
+    if (k === 'format' && typeof v !== 'function' && !isObj(v)) warn(`${name}: format must be Intl.NumberFormat options like { style: 'percent' } or a function (v) => string.`);
+    if (k === 'colors' && (meta.colors ? !isObj(v) : !Array.isArray(v))) warn(`${name}: colors must be ${meta.colors || 'an array like [\'#64c8ff\', \'#10b981\']'}.`);
+  }
+  if ('data' in o) checkData(meta, o.data, o);
+}
+
+function checkData(meta, d, o) {
+  if (d == null) return;
+  const kind = meta.data;
+  const bad = (why) => warn(`${meta.name}: data must be ${SHAPES[kind]}${why ? ` — ${why}` : ''}.`);
+  const first = isList(d) ? d[0] : undefined;
+  switch (kind) {
+    case 'rows':
+      if (isList(d)) {
+        if (Array.isArray(first)) return bad(`pairs like ['Jan', 64] were removed in 2.0`);
+        if (first != null && typeof first !== 'number' && !isObj(first)) return bad(`got ${typeof first} items`);
+        if (isObj(first) && !o.value && !('value' in first)) warn(`${meta.name}: rows need a "value" field, or pass value: (row) => row.amount.`);
+        if (isObj(first) && !o.label && !('label' in first)) warn(`${meta.name}: rows need a "label" field, or pass label: (row) => row.name.`);
+      } else if (!isObj(d)) bad(`got ${typeof d}`);
+      return;
+    case 'series':
+    case 'stream': {
+      if (!isObj(d) || !Array.isArray(d.series) || (kind === 'series' && !isList(d.categories))) return bad(isList(d) ? 'got an array' : '');
+      const n = kind === 'series' ? d.categories.length : 0;
+      d.series.forEach((s, i) => {
+        const who = `series[${i}]${s?.name ? ` "${s.name}"` : ''}`;
+        if (kind === 'stream') return;
+        if (!s || !isList(s.values)) return warn(`${meta.name}: ${who} needs values: [...].`);
+        if (s.values.length !== n) warn(`${meta.name}: ${who} has ${s.values.length} values but there are ${n} categories.`);
+      });
+      return;
+    }
+    case 'matrix':
+      if (!isObj(d) || !isList(d.x) || !isList(d.y) || !Array.isArray(d.values)) return bad(isList(d) ? 'got an array' : '');
+      if (d.values.length !== d.y.length) warn(`${meta.name}: values has ${d.values.length} rows but y has ${d.y.length} labels.`);
+      return;
+    case 'number':
+      if (typeof d !== 'number') bad(`got ${typeof d}`);
+      return;
+    default: {
+      // points · boxes · steps: arrays of objects with known fields
+      if (!Array.isArray(d)) return bad(`got ${isObj(d) ? 'an object' : typeof d}`);
+      if (!first) return;
+      const need = { points: ['x', 'y'], boxes: ['q1', 'median', 'q3'], steps: ['value'] }[kind];
+      const miss = need.filter((k) => !(k in first));
+      if (miss.length) bad(`the first item has no ${miss.join(', ')}`);
+      if (kind === 'steps' && 'isTotal' in first) warn(`${meta.name}: "isTotal" is 1.x. In 2.0 use total: true.`);
+      if (kind === 'points' && ('r' in first || 'z' in first)) warn(`${meta.name}: point "${'r' in first ? 'r' : 'z'}" is 1.x. In 2.0 use size.`);
+    }
+  }
 }
 
 // ─── Chart base ─────────────────────────────────────────────
+const STATES = ['loading', 'empty', 'error'];
+
 class Chart {
+  // Each chart type describes itself: name for messages, aria for the default
+  // accessible name, data shape, and the options it takes beyond COMMON.
+  static get meta() { return null; }
+
   constructor(container, options = {}) {
+    const meta = this.constructor.meta;
     const el = typeof container === 'string' ? document.querySelector(container) : container;
-    if (!el) throw new Error(`aeriz: container not found${typeof container === 'string' ? ': ' + container : ''}`);
+    if (!el) throw new Error(`aeriz: ${meta ? meta.name + ': ' : ''}container not found${typeof container === 'string' ? ': ' + container : ''}`);
     this.container = el;
-    this.options = options;
+    this.options = { ...options };
+    if (meta) checkOptions(meta, this.options);
 
     // Remember what we touch on the container so destroy() can undo it.
     this._restore = { position: el.style.position, height: el.style.height };
@@ -780,8 +899,6 @@ class Chart {
     this.overlay = new Overlay(this.plot);
     this.hits = new HitIndex();
 
-    this.theme = resolveTheme(el);
-    this.palette = options.palette || readPalette(el);
     this._off = new Set();     // legend-hidden series / item indices
     this._legendKey = '';
     this._cursor = null;
@@ -794,6 +911,7 @@ class Chart {
     this._anim = { progress: 0, start: 0, duration: 600 };
     this._state = null;        // 'loading' | 'empty' | 'error' | null
     this._auto = false;        // _state was set automatically by "No data"
+    this._theme();
     this._label();
 
     this._setupEvents();
@@ -804,34 +922,44 @@ class Chart {
     schedule(this);
   }
 
-  // ─── Public API ──────────────────────────────────────────
-  // Re-read theme + palette (after changing CSS variables) and redraw.
-  invalidate() {
-    this.theme = resolveTheme(this.container);
-    this.palette = this.options.palette || readPalette(this.container);
-    this.engine._gradCache.clear();
-    this._legendKey = '';
-    this._dirty = true;
-    schedule(this);
-  }
-
-  // Merge new options (any option, including data) and redraw with animation.
+  // ─── Public API: update · setState · render · destroy ────
+  // Change any options (data included). Changed values animate in.
   update(patch = {}) {
+    const meta = this.constructor.meta;
+    if (meta) checkOptions(meta, patch);
     Object.assign(this.options, patch);
     this._cache = null; // charts may cache work per data array; data can be mutated in place
-    if ('palette' in patch) this.palette = patch.palette || readPalette(this.container);
+    if ('colors' in patch) this._theme();
     if (this._auto) { this._state = null; this._auto = false; }
     this._label();
     this._restart();
     return this;
   }
 
-  setData(data) { return this.update({ data }); }
+  // Show a loading / empty / error overlay, or remove it with null.
+  setState(state, text) {
+    if (state != null && !STATES.includes(state)) {
+      throw new Error(`aeriz: setState() takes 'loading', 'empty', 'error' or null — got ${JSON.stringify(state)}`);
+    }
+    this._state = state || null;
+    this._stateMsg = text ?? (state === 'empty' ? this.options.emptyText || 'No data' : state === 'error' ? 'Error' : '');
+    this._auto = false;
+    this._dirty = true;
+    schedule(this);
+    return this;
+  }
 
-  setLoading(msg) { return this._setState('loading', msg || ''); }
-  setEmpty(msg) { return this._setState('empty', msg || 'No data'); }
-  setError(msg) { return this._setState('error', msg || 'Error'); }
-  clearState() { return this._setState(null); }
+  // Re-read CSS variables / theme and draw the final frame right now — also
+  // when the chart is off-screen (printing, export, measuring).
+  render() {
+    if (this._destroyed) return this;
+    this._theme();
+    this._anim.progress = 1;
+    this._resize();
+    this._dirty = false;
+    this._draw();
+    return this;
+  }
 
   destroy() {
     if (this._destroyed) return;
@@ -848,17 +976,17 @@ class Chart {
   }
 
   // ─── Internals ───────────────────────────────────────────
-  _setState(kind, msg) {
-    this._state = kind;
-    this._stateMsg = msg;
-    this._auto = false;
+  _theme() {
+    const o = this.options;
+    this.theme = resolveTheme(this.container);
+    this.palette = Array.isArray(o.colors) && o.colors.length ? o.colors : readPalette(this.container);
+    this.engine._gradCache.clear();
+    this._legendKey = '';
     this._dirty = true;
-    schedule(this);
-    return this;
   }
 
-  // Charts call this when they find nothing to draw. Unlike setEmpty() it
-  // clears itself on the next update()/setData().
+  // Charts call this when they find nothing to draw. Unlike setState('empty')
+  // it clears itself on the next update().
   _empty(msg = this.options.emptyText || 'No data') {
     this._state = 'empty';
     this._stateMsg = msg;
@@ -875,13 +1003,41 @@ class Chart {
   }
 
   _label() {
-    const o = this.options;
-    this.canvas.setAttribute('aria-label', o.ariaLabel || o.title || this._kind || 'Chart');
+    this.canvas.setAttribute('aria-label', this.options.title || this.constructor.meta?.aria || 'Chart');
   }
 
   _fmt(v) { return M.formatNumber(v, this.options.format); }
   _tickFmt(v) { return M.formatNumber(v, this.options.format, true); }
+  // Category / time label as text (labelFormat wins).
+  _lab(l, time) {
+    const f = this._fn('labelFormat');
+    return f ? String(f(l)) : time ? new Date(+l).toLocaleString() : String(l);
+  }
+  // Numeric x value (scatter, bubble) as text.
+  _xFmt(v) {
+    const f = this._fn('labelFormat');
+    return f ? String(f(v)) : this._fmt(v);
+  }
   _isOff(i) { return this._off.has(i); }
+  // label / value accessor, when it is a function (otherwise warned about).
+  _fn(k) {
+    const f = this.options[k];
+    return typeof f === 'function' ? f : null;
+  }
+
+  // What onClick receives: the clicked item, without drawing internals.
+  _hit(h) {
+    if (!h) return null;
+    const out = { index: h.index, label: h.label };
+    if ('value' in h) out.value = h.value;
+    if ('series' in h) out.series = h.series;
+    if ('row' in h) out.row = h.row;
+    return out;
+  }
+  _click(h) {
+    const hit = this._hit(h);
+    if (hit) this.options.onClick?.(hit, this);
+  }
 
   _resize() {
     const w = this.plot.clientWidth;
@@ -981,8 +1137,7 @@ class Chart {
 
   _onClick(e) {
     const p = this._ptr(e);
-    const hit = this.hits.find(p.x, p.y) || (this._follow ? this._hover : null);
-    this.options.onClick?.(hit, p, this);
+    this._click(this.hits.find(p.x, p.y) || (this._follow ? this._hover : null));
   }
 
   // ← → (↑ ↓) walk through the data points, Home/End jump, Enter clicks,
@@ -992,7 +1147,7 @@ class Chart {
     const fwd = k === 'ArrowRight' || k === 'ArrowDown';
     const back = k === 'ArrowLeft' || k === 'ArrowUp';
     if (k === 'Escape') return this._onLeave();
-    if (k === 'Enter' && this._hover) return this.options.onClick?.(this._hover, this._cursor, this);
+    if (k === 'Enter' && this._hover) return this._click(this._hover);
     if (!fwd && !back && k !== 'Home' && k !== 'End') return;
     const steps = this._steps?.length
       ? this._steps.map((x) => ({ x, y: this.engine.h / 2 }))
@@ -1099,6 +1254,15 @@ class Chart {
   }
 }
 
+// Removed in 2.0 — fail loudly with the replacement instead of "is not a function".
+const GONE = {
+  setData: 'update({ data })', setLoading: "setState('loading', text)", setEmpty: "setState('empty', text)",
+  setError: "setState('error', text)", clearState: 'setState(null)', invalidate: 'render()', setValue: 'update({ data: value })',
+};
+for (const k in GONE) {
+  Chart.prototype[k] = function () { throw new Error(`aeriz 2.0: chart.${k}() was removed. Use chart.${GONE[k]}.`); };
+}
+
 // ── src/cartesian.js
 // cartesian.js — Axes + grid for x/y charts. Only charts with axes import it.
 
@@ -1123,9 +1287,10 @@ function localTimeFormat(step) {
 
 // Draw grid, y axis (left, optional right) and x axis. Returns plot geometry.
 //
-// spec: { yMin, yMax, yScale?: 'linear'|'log', yTickFormat?,
-//         xLabels?: string[] | xTime?: {min,max} | xLinear?: {min,max}, xTickFormat?,
-//         right?: { yMin, yMax, yTickFormat? }, pad?: {l,r,t,b} }
+// spec: { yMin, yMax, yScale?: 'linear'|'log', yFormat?,
+//         xLabels?: any[] | xTime?: {min,max} | xLinear?: {min,max},
+//         right?: { yMin, yMax, yFormat? }, pad?: {l,r,t,b} }
+// The value axis uses the chart's `format`; x labels use its `labelFormat`.
 function drawCartesian(chart, spec) {
   const e = chart.engine;
   const t = chart.theme;
@@ -1149,7 +1314,7 @@ function drawCartesian(chart, spec) {
     yTicks = M.niceTicks(yMin, yMax, 5);
     yNorm = (v) => (v - yMin) / (yMax - yMin || 1);
   }
-  const yFmt = spec.yTickFormat || ((v) => chart._tickFmt(v));
+  const yFmt = spec.yFormat ? (v) => M.formatNumber(v, spec.yFormat, true) : (v) => chart._tickFmt(v);
   const yText = yTicks.map((v) => yFmt(v));
   let maxW = 0;
   for (const s of yText) maxW = Math.max(maxW, e.measure(s, font));
@@ -1159,7 +1324,7 @@ function drawCartesian(chart, spec) {
   if (right) {
     rTicks = M.niceTicks(right.yMin, right.yMax, 5);
     rNorm = (v) => (v - right.yMin) / (right.yMax - right.yMin || 1);
-    const rf = right.yTickFormat || ((v) => chart._tickFmt(v));
+    const rf = right.yFormat ? (v) => M.formatNumber(v, right.yFormat, true) : (v) => chart._tickFmt(v);
     rText = rTicks.map((v) => rf(v));
     for (const s of rText) rMaxW = Math.max(rMaxW, e.measure(s, font));
   }
@@ -1194,23 +1359,24 @@ function drawCartesian(chart, spec) {
 
   // X axis: categorical labels, time, or linear.
   let xToPx, xTicks, xFmt;
+  const lf = chart._fn('labelFormat');
   if (spec.xTime) {
     const { min, max } = spec.xTime;
     xToPx = (v) => px + (pw * (v - min)) / (max - min || 1);
     xTicks = M.timeNiceTicks(min, max, Math.max(2, Math.floor(pw / 90)));
     const step = xTicks.length > 1 ? xTicks[1] - xTicks[0] : max - min;
-    xFmt = spec.xTickFormat || localTimeFormat(step);
+    xFmt = lf ? (v) => String(lf(v)) : localTimeFormat(step);
   } else if (spec.xLinear) {
     const { min, max } = spec.xLinear;
     xToPx = (v) => px + (pw * (v - min)) / (max - min || 1);
     xTicks = M.niceTicks(min, max, 6);
-    xFmt = spec.xTickFormat || ((v) => chart._tickFmt(v));
+    xFmt = lf ? (v) => String(lf(v)) : (v) => chart._tickFmt(v);
   } else if (spec.xLabels) {
     const n = spec.xLabels.length || 1;
     xToPx = (i) => px + (i + 0.5) * (pw / n);
-    xFmt = spec.xTickFormat || ((i) => String(spec.xLabels[i]));
+    xFmt = (i) => chart._lab(spec.xLabels[i]);
     // Only look at every k-th label: with 1M categories we can't measure them all.
-    const guess = Math.max(e.measure(xFmt(0, 0), font), e.measure(xFmt(n - 1, n - 1), font)) + 6;
+    const guess = Math.max(e.measure(xFmt(0), font), e.measure(xFmt(n - 1), font)) + 6;
     const k = Math.max(1, Math.ceil((n * guess) / pw));
     xTicks = [];
     for (let i = 0; i < n; i += k) xTicks.push(i);
@@ -1219,7 +1385,7 @@ function drawCartesian(chart, spec) {
     // Skip labels that would collide; keep the outer ones inside the canvas.
     let lastEnd = -Infinity;
     for (const v of xTicks) {
-      const txt = xFmt(v, v);
+      const txt = xFmt(v);
       const w = e.measure(txt, font);
       const x = Math.max(w / 2, Math.min(e.w - w / 2, xToPx(v)));
       if (x - w / 2 < lastEnd + 6) continue;
@@ -1247,13 +1413,24 @@ function range(arrays, lo = Infinity, hi = -Infinity) {
   return [lo, hi];
 }
 
+// Value-axis domain from the data range, with the chart's min / max options
+// taking precedence over the nice rounding.
+function valueDomain(o, lo, hi) {
+  const [a, b] = M.niceDomain(o.min ?? lo, o.max ?? hi, 5);
+  return [o.min ?? a, o.max ?? b];
+}
+
+// Option names shared by charts with x/y axes.
+const AXIS = ['labelFormat', 'min', 'max'];
+
 // ── src/charts/bar.js
 // BarChart — vertical bars, negative values grow downward from zero.
 
 
-
 class BarChart extends Chart {
-  get _kind() { return 'Bar chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'bar', name: 'BarChart', aria: 'Bar chart', data: 'rows', options: ['label', 'value', 'labelFormat', 'min', 'max', 'dataLabels'] };
+  }
 
   _render() {
     const data = toRows(this.options.data);
@@ -1261,25 +1438,24 @@ class BarChart extends Chart {
     const e = this.engine;
     const t = this.theme;
     const o = this.options;
-    const labelOf = o.label || ((d) => d.label);
-    const valueOf = o.value || ((d) => d.value);
+    const labelOf = this._fn('label') || ((d) => d.label);
+    const valueOf = this._fn('value') || ((d) => d.value);
     const values = data.map((d, i) => +valueOf(d, i) || 0);
+    const labels = data.map((d, i) => labelOf(d, i));
     const [lo, hi] = range([values], 0, 0);
-    const [yLo, yHi] = M.niceDomain(lo, hi, 5);
+    const [yLo, yHi] = valueDomain(o, lo, hi);
+    const dl = o.dataLabels;
     const ax = drawCartesian(this, {
       yMin: yLo, yMax: yHi,
-      xLabels: data.map((d, i) => labelOf(d, i)),
-      yTickFormat: o.yTickFormat,
-      xTickFormat: o.xTickFormat,
-      pad: o.dataLabels ? { t: t.fontSize + 10 } : undefined,
+      xLabels: labels,
+      pad: dl ? { t: t.fontSize + 10 } : undefined,
     });
 
     const slot = ax.pw / data.length;
     const barW = Math.max(1, Math.min(60, slot * 0.8, slot - 2));
     const prog = this._anim.progress;
-    const y0 = ax.yToPx(0);
+    const y0 = ax.yToPx(Math.max(yLo, 0));
     const groups = new Map();
-    const dl = o.dataLabels;
     const font = `${t.fontSize}px ${t.font}`;
 
     for (let i = 0; i < data.length; i++) {
@@ -1287,17 +1463,18 @@ class BarChart extends Chart {
       const x = ax.px + (i + 0.5) * slot - barW / 2;
       const h = Math.abs(ax.yToPx(v) - y0) * prog;
       const top = v >= 0 ? y0 - h : y0;
-      const color = this._colorOf(o.color ? 0 : i, data[i].color ? data[i] : { color: o.color });
+      const color = this._colorOf(i, data[i]);
       if (!groups.has(color)) groups.set(color, []);
       groups.get(color).push({ x, y: top, w: barW, h, radius: t.barRadius });
+      const label = this._lab(labels[i]);
       this.hits.add({
         _id: i, x, y: Math.min(top, y0 - 2), w: barW, h: Math.max(h, 4),
         tipX: x + barW / 2, tipY: top,
-        tooltip: `${labelOf(data[i], i)}: ${this._fmt(v)}`,
-        data: data[i], index: i, value: v,
+        tooltip: `${label}: ${this._fmt(v)}`,
+        index: i, label: labels[i], value: v, row: data[i],
       });
       if (dl && prog > 0.95) {
-        const txt = typeof dl === 'function' ? dl(data[i], i) : this._fmt(v);
+        const txt = typeof dl === 'function' ? dl(v, data[i], i) : this._fmt(v);
         e.text(txt, x + barW / 2, v >= 0 ? top - 4 : top + h + 4, {
           fill: t.text, font, align: 'center', baseline: v >= 0 ? 'bottom' : 'top',
         });
@@ -1318,7 +1495,9 @@ class BarChart extends Chart {
 
 
 class HBarChart extends Chart {
-  get _kind() { return 'Horizontal bar chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'hbar', name: 'HBarChart', aria: 'Horizontal bar chart', data: 'rows', options: ['label', 'value', 'labelFormat', 'min', 'max'] };
+  }
 
   _render() {
     const data = toRows(this.options.data);
@@ -1326,12 +1505,13 @@ class HBarChart extends Chart {
     const e = this.engine;
     const t = this.theme;
     const o = this.options;
-    const labelOf = o.label || ((d) => d.label);
-    const valueOf = o.value || ((d) => d.value);
+    const labelOf = this._fn('label') || ((d) => d.label);
+    const valueOf = this._fn('value') || ((d) => d.value);
     const values = data.map((d, i) => +valueOf(d, i) || 0);
-    const labels = data.map((d, i) => String(labelOf(d, i)));
+    const raw = data.map((d, i) => labelOf(d, i));
+    const labels = raw.map((l) => this._lab(l));
     const [lo, hi] = range([values], 0, 0);
-    const [xLo, xHi] = M.niceDomain(lo, hi, 5);
+    const [xLo, xHi] = valueDomain(o, lo, hi);
     const font = `${t.fontSize}px ${t.font}`;
 
     let labelW = 0;
@@ -1342,7 +1522,6 @@ class HBarChart extends Chart {
 
     const xTicks = M.niceTicks(xLo, xHi, Math.max(2, Math.min(6, Math.floor(pw / 70))));
     const xToPx = (v) => px + (pw * (v - xLo)) / (xHi - xLo || 1);
-    const xFmt = o.xTickFormat || ((v) => this._tickFmt(v));
     e.ctx.strokeStyle = t.grid;
     e.ctx.lineWidth = 1;
     e.ctx.beginPath();
@@ -1353,14 +1532,14 @@ class HBarChart extends Chart {
     }
     e.ctx.stroke();
     for (const v of xTicks) {
-      e.text(xFmt(v), xToPx(v), py + ph + 6, { fill: t.muted, font, align: 'center', baseline: 'top' });
+      e.text(this._tickFmt(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(1, Math.min(40, slot * 0.75, slot - 2));
     const prog = this._anim.progress;
-    const x0 = xToPx(0);
+    const x0 = xToPx(Math.max(xLo, 0));
     const groups = new Map();
 
     for (let i = 0; i < data.length; i++) {
@@ -1369,14 +1548,14 @@ class HBarChart extends Chart {
       const y = yMid - barH / 2;
       const w = Math.abs(xToPx(v) - x0) * prog;
       const left = v >= 0 ? x0 : x0 - w;
-      const color = this._colorOf(o.color ? 0 : i, data[i].color ? data[i] : { color: o.color });
+      const color = this._colorOf(i, data[i]);
       if (!groups.has(color)) groups.set(color, []);
       groups.get(color).push({ x: left, y, w, h: barH, radius: t.barRadius });
       this.hits.add({
         _id: i, x: Math.min(left, x0 - 2), y, w: Math.max(w, 4), h: barH,
         tipX: left + w / 2, tipY: y,
         tooltip: `${labels[i]}: ${this._fmt(v)}`,
-        data: data[i], index: i, value: v,
+        index: i, label: raw[i], value: v, row: data[i],
       });
       e.text(labels[i], px - 6, yMid, { fill: t.muted, font, align: 'right', baseline: 'middle' });
     }
@@ -1398,42 +1577,50 @@ const LABEL = (d) => d.label;
 const VALUE = (d) => d.value;
 
 class LineChart extends Chart {
-  get _kind() { return 'Line chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return {
+      id: 'line', name: 'LineChart', aria: 'Line chart', data: 'rows',
+      options: ['label', 'value', 'labelFormat', 'min', 'max', 'curve', 'fill', 'points', 'xScale', 'yScale'],
+      enums: { curve: ['smooth', 'linear', 'step'], xScale: ['category', 'time'], yScale: ['linear', 'log'] },
+    };
+  }
 
   _render() {
-    const data = toRows(this.options.data);
-    if (!data.length) return this._empty();
-    const e = this.engine;
-    const t = this.theme;
     const o = this.options;
-    const labelOf = o.label || LABEL;
-    const valueOf = o.value || VALUE;
-    const n = data.length;
+    const labelOf = this._fn('label') || LABEL;
+    const valueOf = this._fn('value') || VALUE;
 
-    // Values are cached per data array so hover redraws don't re-map 1M rows.
+    // Rows and values are cached per data array so hover redraws don't
+    // re-map 1M rows.
     let c = this._cache;
     if (!c || c.data !== o.data || c.valueOf !== valueOf || c.labelOf !== labelOf) {
-      const values = new Float64Array(n);
-      for (let i = 0; i < n; i++) values[i] = +valueOf(data[i], i);
-      c = this._cache = { data: o.data, valueOf, labelOf, values, idx: null, idxW: 0, xs: null, labels: null, range: null };
-    }
+      const d = o.data;
+      // Plain numbers (incl. typed arrays): skip building a row object per point.
+      const nums = d && typeof d[0] === 'number' && (Array.isArray(d) || ArrayBuffer.isView(d)) && !this._fn('value') && !this._fn('label');
+      const rows = nums ? d : toRows(d);
+      const values = nums ? Float64Array.from(d) : new Float64Array(rows.length);
+      if (!nums) for (let i = 0; i < rows.length; i++) values[i] = +valueOf(rows[i], i);
+      const labels = nums ? Array.from({ length: d.length }, (_, i) => i + 1) : null;
+      c = this._cache = { data: o.data, rows, valueOf, labelOf, values, idx: null, idxW: 0, xs: null, labels, range: null };
+    }
+    const data = c.rows;
+    if (!data.length) return this._empty();
+    const e = this.engine;
+    const t = this.theme;
+    const n = data.length;
     const values = c.values;
-    const [lo, hi] = (c.range ||= range([values], o.yScale === 'log' ? Infinity : 0));
-    const [yLo, yHi] = o.yScale === 'log' ? [lo, hi] : M.niceDomain(lo, hi, 5);
+    const log = o.yScale === 'log';
+    const [lo, hi] = (c.range ||= range([values], log ? Infinity : 0));
+    const [yLo, yHi] = log ? [o.min ?? lo, o.max ?? hi] : valueDomain(o, lo, hi);
     const useTime = o.xScale === 'time';
-    const spec = {
-      yMin: yLo, yMax: yHi,
-      yScale: o.yScale,
-      yTickFormat: o.yTickFormat,
-      xTickFormat: o.xTickFormat,
-    };
-    const xs = useTime ? (c.xs ||= data.map((d, i) => +labelOf(d, i))) : null;
+    const spec = { yMin: yLo, yMax: yHi, yScale: o.yScale };
+    const xs = useTime ? (c.xs ||= Array.from(data, (d, i) => +labelOf(d, i))) : null;
     if (useTime) spec.xTime = { min: xs[0], max: xs[n - 1] };
-    else spec.xLabels = c.labels ||= data.map((d, i) => labelOf(d, i));
+    else spec.xLabels = c.labels ||= Array.from(data, (d, i) => labelOf(d, i));
     const ax = drawCartesian(this, spec);
 
-    const color = o.color || this.palette[0];
-    const interp = o.interpolation || 'smooth';
+    const color = this.palette[0];
+    const interp = o.curve || 'smooth';
     const lineW = t.lineWidth;
     const prog = this._anim.progress;
     const xAt = useTime ? (i) => ax.xToPx(xs[i]) : (i) => ax.px + ((i + 0.5) / n) * ax.pw;
@@ -1468,19 +1655,20 @@ class LineChart extends Chart {
       }
       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.startsWith('step')) {
-      e.step(points, interp === 'step' ? 'before' : interp.split('-')[1], { stroke: color, lineWidth: lineW });
+    } else {
+      e.step(points, 'before', { stroke: color, lineWidth: lineW });
     }
     e.unclip();
 
-    const tip = (i) => `${useTime ? new Date(xs[i]).toLocaleString() : labelOf(data[i], i)}: ${this._fmt(values[i])}`;
+    const labelAt = (i) => (useTime ? xs[i] : c.labels[i]);
+    const tip = (i) => `${this._lab(labelAt(i), useTime)}: ${this._fmt(values[i])}`;
     if (!decimated && n <= 50) {
       if (o.points !== false) e.circles(points, color, t.pointRadius);
       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 - t.pointRadius,
-          tooltip: tip(p.i), data: data[p.i], index: p.i, value: values[p.i],
+          tooltip: tip(p.i), index: p.i, label: labelAt(p.i), value: values[p.i], row: data[p.i],
         });
       }
     } else {
@@ -1493,7 +1681,7 @@ class LineChart extends Chart {
         this.hits.add({
           _id: p.i, x: l, y: ax.py, w: Math.max(1, r - l), h: ax.ph,
           tipX: p.x, tipY: p.y - 8,
-          tooltip: tip(p.i), data: data[p.i], index: p.i, value: values[p.i],
+          tooltip: tip(p.i), index: p.i, label: labelAt(p.i), value: values[p.i], row: data[p.i],
         });
       }
     }
@@ -1511,13 +1699,14 @@ class LineChart extends Chart {
 
 
 class AreaChart extends Chart {
-  get _kind() { return 'Area chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'area', name: 'AreaChart', aria: 'Area chart', data: 'series', options: ['labelFormat', 'min', 'max', 'stacked'] };
+  }
 
-  _legend() { return this._seriesLegend(this.options.series || []); }
+  _legend() { return this._seriesLegend(this.options.data?.series || []); }
   _render() {
     const o = this.options;
-    const series = o.series || [];
-    const cats = o.categories || [];
+    const { categories: cats = [], series = [] } = o.data || {};
     if (!series.length || !cats.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
@@ -1535,8 +1724,8 @@ class AreaChart extends Chart {
     } else {
       [yMin, yMax] = range(on.map((s) => series[s].values), 0, 0);
     }
-    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
-    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: cats, yTickFormat: o.yTickFormat, xTickFormat: o.xTickFormat });
+    const [yLo, yHi] = valueDomain(o, yMin, yMax);
+    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: cats });
     const lineW = t.lineWidth;
     const prog = this._anim.progress;
     const xAt = (i) => ax.px + ((i + 0.5) / cats.length) * ax.pw;
@@ -1575,9 +1764,9 @@ class AreaChart extends Chart {
     for (let i = 0; i < cats.length; i++) {
       this.hits.add({
         _id: i, x: ax.px + i * slot, y: ax.py, w: slot, h: ax.ph,
-        tipX: xAt(i), tipY: ax.py + 8, index: i,
+        tipX: xAt(i), tipY: ax.py + 8, index: i, label: cats[i],
         tooltip: {
-          title: String(cats[i]),
+          title: this._lab(cats[i]),
           rows: on.map((s) => ({ color: this._colorOf(s, series[s]), name: series[s].name || 'Series ' + (s + 1), value: this._fmt(+series[s].values[i]) })),
         },
       });
@@ -1593,15 +1782,15 @@ class AreaChart extends Chart {
 // StackedBarChart — positive values stack up from zero, negative values down.
 
 
-
 class StackedBarChart extends Chart {
-  get _kind() { return 'Stacked bar chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'stacked-bar', name: 'StackedBarChart', aria: 'Stacked bar chart', data: 'series', options: ['labelFormat', 'min', 'max'] };
+  }
 
-  _legend() { return this._seriesLegend(this.options.series || []); }
+  _legend() { return this._seriesLegend(this.options.data?.series || []); }
   _render() {
     const o = this.options;
-    const series = o.series || [];
-    const cats = o.categories || [];
+    const { categories: cats = [], series = [] } = o.data || {};
     if (!series.length || !cats.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
@@ -1617,8 +1806,8 @@ class StackedBarChart extends Chart {
       if (pos > hi) hi = pos;
       if (neg < lo) lo = neg;
     }
-    const [yLo, yHi] = M.niceDomain(lo, hi, 5);
-    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: cats, yTickFormat: o.yTickFormat, xTickFormat: o.xTickFormat });
+    const [yLo, yHi] = valueDomain(o, lo, hi);
+    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: cats });
 
     const slot = ax.pw / cats.length;
     const barW = Math.max(1, Math.min(50, slot * 0.8, slot - 2));
@@ -1647,8 +1836,8 @@ class StackedBarChart extends Chart {
         (v > 0 ? lastPos : lastNeg)[i] = item;
         this.hits.add({
           _id: `${i}-${s}`, x, y, w: barW, h,
-          tipX: x + barW / 2, tipY: y, index: i, series: s, value: v,
-          tooltip: { title: String(cats[i]), rows: [{ color, name: series[s].name || 'Series ' + (s + 1), value: this._fmt(v) }] },
+          tipX: x + barW / 2, tipY: y, index: i, label: cats[i], series: s, value: v, row: series[s],
+          tooltip: { title: this._lab(cats[i]), rows: [{ color, name: series[s].name || 'Series ' + (s + 1), value: this._fmt(v) }] },
         });
       }
     }
@@ -1667,23 +1856,23 @@ class StackedBarChart extends Chart {
 // GroupedBarChart — series side by side in each category.
 
 
-
 class GroupedBarChart extends Chart {
-  get _kind() { return 'Grouped bar chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'grouped-bar', name: 'GroupedBarChart', aria: 'Grouped bar chart', data: 'series', options: ['labelFormat', 'min', 'max'] };
+  }
 
-  _legend() { return this._seriesLegend(this.options.series || []); }
+  _legend() { return this._seriesLegend(this.options.data?.series || []); }
   _render() {
     const o = this.options;
-    const series = o.series || [];
-    const cats = o.categories || [];
+    const { categories: cats = [], series = [] } = o.data || {};
     if (!series.length || !cats.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
     const on = series.map((s, i) => i).filter((i) => !this._isOff(i));
 
     const [lo, hi] = range(on.map((s) => series[s].values), 0, 0);
-    const [yLo, yHi] = M.niceDomain(lo, hi, 5);
-    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: cats, yTickFormat: o.yTickFormat, xTickFormat: o.xTickFormat });
+    const [yLo, yHi] = valueDomain(o, lo, hi);
+    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: cats });
 
     const slot = ax.pw / cats.length;
     const inner = slot * 0.8;
@@ -1705,8 +1894,8 @@ class GroupedBarChart extends Chart {
         groups.get(color).push({ x, y, w, h, radius: t.barRadius });
         this.hits.add({
           _id: `${i}-${s}`, x, y: Math.min(y, y0 - 2), w, h: Math.max(h, 4),
-          tipX: x + barW / 2, tipY: y, index: i, series: s, value: v,
-          tooltip: { title: String(cats[i]), rows: [{ color, name: series[s].name || 'Series ' + (s + 1), value: this._fmt(v) }] },
+          tipX: x + barW / 2, tipY: y, index: i, label: cats[i], series: s, value: v, row: series[s],
+          tooltip: { title: this._lab(cats[i]), rows: [{ color, name: series[s].name || 'Series ' + (s + 1), value: this._fmt(v) }] },
         });
       });
     }
@@ -1725,26 +1914,27 @@ class GroupedBarChart extends Chart {
 
 
 class MultiLineChart extends Chart {
-  get _kind() { return 'Multi line chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'multi-line', name: 'MultiLineChart', aria: 'Multi line chart', data: 'series', options: ['labelFormat', 'min', 'max', 'curve', 'xScale'], enums: { curve: ['smooth', 'linear', 'step'], xScale: ['category', 'time'] } };
+  }
   constructor(container, options) {
     super(container, options);
     this._follow = true;
   }
-  _legend() { return this._seriesLegend(this.options.series || []); }
+  _legend() { return this._seriesLegend(this.options.data?.series || []); }
   _render() {
     const o = this.options;
-    const series = o.series || [];
-    const cats = o.categories || [];
+    const { categories: cats = [], series = [] } = o.data || {};
     if (!series.length || !cats.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
-    const interp = o.interpolation || 'smooth';
-    const on = series.map((s, i) => i).filter((i) => !this._isOff(i) && !series[i].hidden);
+    const interp = o.curve || 'smooth';
+    const on = series.map((s, i) => i).filter((i) => !this._isOff(i));
 
     const [lo, hi] = range(on.map((s) => series[s].values), 0);
-    const [yLo, yHi] = M.niceDomain(lo, hi, 5);
+    const [yLo, yHi] = valueDomain(o, lo, hi);
     const useTime = o.xScale === 'time';
-    const spec = { yMin: yLo, yMax: yHi, yTickFormat: o.yTickFormat, xTickFormat: o.xTickFormat };
+    const spec = { yMin: yLo, yMax: yHi };
     if (useTime) spec.xTime = { min: +cats[0], max: +cats[cats.length - 1] };
     else spec.xLabels = cats;
     const ax = drawCartesian(this, spec);
@@ -1762,7 +1952,7 @@ class MultiLineChart extends Chart {
       all.push({ pts, color, s, ser });
       if (interp === 'smooth') e.smooth(pts, M.bezierControlPoints(pts), { stroke: color, lineWidth: lineW });
       else if (interp === 'linear') e.poly(pts, { stroke: color, lineWidth: lineW, cap: 'round', join: 'round' });
-      else e.step(pts, interp === 'step' ? 'before' : interp.split('-')[1], { stroke: color, lineWidth: lineW });
+      else e.step(pts, 'before', { stroke: color, lineWidth: lineW });
       if (pts.length <= 50) e.circles(pts, color, t.pointRadius);
     }
     e.unclip();
@@ -1785,9 +1975,9 @@ class MultiLineChart extends Chart {
         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: this._fmt(+sp.ser.values[idx]) });
       }
-      const title = useTime ? new Date(+cats[idx]).toLocaleString() : String(cats[idx]);
+      const title = this._lab(cats[idx], useTime);
       this._tipNow = { title, rows };
-      this._hover = { _id: idx, index: idx };
+      this._hover = { _id: idx, index: idx, label: cats[idx] };
       this.tooltip.show(xPx, ax.py + 8, this._tipNow, t);
     } else if (this._cursor) {
       this.tooltip.hide();
@@ -1796,7 +1986,8 @@ class MultiLineChart extends Chart {
 }
 
 // ── src/charts/scatter.js
-// ScatterChart — points batched per color/radius; `group` picks the color.
+// ScatterChart — points [{ x, y, size?, group?, label?, color? }], batched per
+// color/radius; `group` picks the color, `size` is the radius in px.
 
 
 
@@ -1812,7 +2003,9 @@ function xyExtent(data) {
 }
 
 class ScatterChart extends Chart {
-  get _kind() { return 'Scatter chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'scatter', name: 'ScatterChart', aria: 'Scatter chart', data: 'points', options: ['labelFormat', 'min', 'max'] };
+  }
 
   _render() {
     const o = this.options;
@@ -1822,10 +2015,9 @@ class ScatterChart extends Chart {
     const t = this.theme;
     const [xMin, xMax, yMin, yMax] = xyExtent(data);
     const [xLo, xHi] = M.niceDomain(xMin, xMax, 6);
-    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
+    const [yLo, yHi] = valueDomain(o, yMin, yMax);
     const ax = drawCartesian(this, {
       yMin: yLo, yMax: yHi, xLinear: { min: xLo, max: xHi },
-      yTickFormat: o.yTickFormat, xTickFormat: o.xTickFormat,
     });
     const prog = this._anim.progress;
     const groups = new Map();
@@ -1837,7 +2029,7 @@ class ScatterChart extends Chart {
       const d = data[i];
       const cx = ax.xToPx(d.x);
       const cy = ax.yToPx(d.y);
-      const r = (d.r || defaultR) * prog;
+      const r = (d.size || defaultR) * prog;
       const color = d.color || this._colorOf(d.group != null ? d.group : 0);
       const key = color + ':' + r.toFixed(1);
       if (!groups.has(key)) groups.set(key, { color, r, items: [] });
@@ -1845,8 +2037,8 @@ class ScatterChart extends Chart {
       if (hitsOn) {
         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, data: d, index: i,
-          tooltip: `(${this._fmt(d.x)}, ${this._fmt(d.y)})${d.label ? ` · ${d.label}` : ''}`,
+          tipX: cx, tipY: cy - r, index: i, label: d.label, value: d.y, row: d,
+          tooltip: `${d.label ? d.label + ' ' : ''}(${this._xFmt(d.x)}, ${this._fmt(d.y)})`,
         });
       }
     }
@@ -1861,13 +2053,16 @@ class ScatterChart extends Chart {
 }
 
 // ── src/charts/bubble.js
-// BubbleChart — scatter where `z` sets the bubble area.
+// BubbleChart — scatter where `size` (a data value) sets the bubble area,
+// scaled into the `radius: [min, max]` range in px.
 
 
 
 
 class BubbleChart extends Chart {
-  get _kind() { return 'Bubble chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'bubble', name: 'BubbleChart', aria: 'Bubble chart', data: 'points', options: ['labelFormat', 'min', 'max', 'radius'] };
+  }
 
   _render() {
     const o = this.options;
@@ -1877,38 +2072,38 @@ class BubbleChart extends Chart {
     const t = this.theme;
     const [xMin, xMax, yMin, yMax] = xyExtent(data);
     let zMax = 0;
-    for (const d of data) if ((d.z || 0) > zMax) zMax = d.z;
+    for (const d of data) if ((d.size || 0) > zMax) zMax = d.size;
     // Pad the domain so the biggest bubbles stay inside the plot.
     const px = (xMax - xMin || 1) * 0.08, py = (yMax - yMin || 1) * 0.1;
     const [xLo, xHi] = M.niceDomain(xMin - px, xMax + px, 6);
-    const [yLo, yHi] = M.niceDomain(yMin - py, yMax + py, 5);
+    const [yLo, yHi] = valueDomain(o, yMin - py, yMax + py);
     const ax = drawCartesian(this, {
       yMin: yLo, yMax: yHi, xLinear: { min: xLo, max: xHi },
-      yTickFormat: o.yTickFormat, xTickFormat: o.xTickFormat,
     });
     const prog = this._anim.progress;
-    const maxR = o.maxRadius || 32, minR = o.minRadius || 4;
+    const [minR, maxR] = Array.isArray(o.radius) ? o.radius : [4, 32];
 
     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(1e-9, zMax)) * (maxR - minR)) * prog;
+      const r = (minR + Math.sqrt((d.size || 0) / Math.max(1e-9, zMax)) * (maxR - minR)) * prog;
       const color = d.color || this._colorOf(d.group != null ? d.group : i);
       const hover = this._hover && this._hover._id === i;
       e.circle(cx, cy, r, { fill: M.colorAlpha(color, hover ? 0.75 : 0.5), stroke: color, lineWidth: 1.5 });
       this.hits.add({
         _id: i, x: cx - r, y: cy - r, w: r * 2, h: r * 2,
         test: (x, y) => (x - cx) ** 2 + (y - cy) ** 2 <= r * r,
-        tipX: cx, tipY: cy - r, data: d, index: i,
-        tooltip: `${d.label ? d.label + ' ' : ''}(${this._fmt(d.x)}, ${this._fmt(d.y)}) · z=${this._fmt(d.z)}`,
+        tipX: cx, tipY: cy - r, index: i, label: d.label, value: d.y, row: d,
+        tooltip: `${d.label ? d.label + ' ' : ''}(${this._xFmt(d.x)}, ${this._fmt(d.y)}) · ${this._fmt(d.size)}`,
       });
     }
   }
 }
 
 // ── src/charts/pie.js
-// PieChart — `innerRadius` turns it into a donut with a center label.
+// PieChart — `innerRadius` (0–0.9 of the radius) turns it into a donut with
+// a center label (`center`: text, or false for none).
 // Slices are hit-tested by angle and radius, and toggle from the legend.
 
 
@@ -1925,11 +2120,13 @@ function inSector(cx, cy, rIn, rOut, a0, a1) {
 }
 
 class PieChart extends Chart {
-  get _kind() { return 'Pie chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'pie', name: 'PieChart', aria: 'Pie chart', data: 'rows', options: ['label', 'value', 'innerRadius', 'center'] };
+  }
 
   _legend() {
     const o = this.options;
-    const labelOf = o.label || ((d) => d.label);
+    const labelOf = this._fn('label') || ((d) => d.label);
     return toRows(o.data).map((d, i) => ({ label: String(labelOf(d, i)), color: this._colorOf(i, d) }));
   }
   _render() {
@@ -1938,16 +2135,20 @@ class PieChart extends Chart {
     if (!data.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
-    const labelOf = o.label || ((d) => d.label);
-    const valueOf = o.value || ((d) => d.value);
-    const vals = data.map((d, i) => (this._isOff(i) ? 0 : Math.max(0, +valueOf(d, i) || 0)));
+    const labelOf = this._fn('label') || ((d) => d.label);
+    const valueOf = this._fn('value') || ((d) => d.value);
+    const raw = data.map((d, i) => +valueOf(d, i) || 0);
+    const neg = raw.findIndex((v) => v < 0);
+    if (neg >= 0) warn(`PieChart: values can't be negative — "${labelOf(data[neg], neg)}" is ${raw[neg]}. It is drawn as 0.`);
+    const vals = raw.map((v, i) => (this._isOff(i) ? 0 : Math.max(0, v)));
     const total = vals.reduce((a, v) => a + v, 0);
     if (total <= 0) return this._empty();
 
     const cx = e.w / 2, cy = e.h / 2;
     const R = Math.max(4, Math.min(e.w, e.h) / 2 - 12);
-    const ir = o.innerRadius;
-    const innerR = ir == null || ir === false ? 0 : typeof ir === 'number' ? (ir <= 1 ? R * ir : ir) : R * 0.55;
+    const ir = +o.innerRadius || 0;
+    if (ir > 0.9) warn(`PieChart: innerRadius is a ratio from 0 to 0.9 (0.6 = donut) — got ${ir}.`);
+    const innerR = R * Math.min(0.9, Math.max(0, ir));
     const prog = this._anim.progress;
     let a0 = -Math.PI / 2;
     for (let i = 0; i < data.length; i++) {
@@ -1967,14 +2168,14 @@ class PieChart extends Chart {
         _id: i, x: cx - R, y: cy - R, w: R * 2, h: R * 2,
         test: inSector(cx, cy, innerR, R + off, a0, a1),
         tipX: cx + Math.cos(mid) * midR, tipY: cy + Math.sin(mid) * midR - 8,
-        data: data[i], index: i, value: v,
-        tooltip: `${labelOf(data[i], i)}: ${this._fmt(v)} (${((v / total) * 100).toFixed(1)}%)`,
+        index: i, label: labelOf(data[i], i), value: v, row: data[i],
+        tooltip: `${this._lab(labelOf(data[i], i))}: ${this._fmt(v)} (${((v / total) * 100).toFixed(1)}%)`,
       });
       a0 = a1;
     }
-    if (innerR > 0 && o.centerLabel !== false) {
+    if (innerR > 0 && o.center !== false) {
       const h = this._hover;
-      const center = h ? `${((vals[h._id] / total) * 100).toFixed(0)}%` : o.totalLabel || this._fmt(total);
+      const center = h ? `${((vals[h._id] / total) * 100).toFixed(0)}%` : o.center ?? this._fmt(total);
       e.text(center, cx, cy, {
         fill: t.text, font: `600 ${Math.max(12, Math.min(t.fontSize * 1.8, innerR / 2.2))}px ${t.font}`,
         align: 'center', baseline: 'middle',
@@ -1990,19 +2191,21 @@ class PieChart extends Chart {
 
 
 class RadarChart extends Chart {
-  get _kind() { return 'Radar chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'radar', name: 'RadarChart', aria: 'Radar chart', data: 'series', options: ['labelFormat', 'max'] };
+  }
 
-  _legend() { return this._seriesLegend(this.options.series || []); }
+  _legend() { return this._seriesLegend(this.options.data?.series || []); }
   _render() {
     const o = this.options;
-    const series = o.series || [];
-    const axes = o.axes || [];
+    const { categories: axes = [], series = [] } = o.data || {};
     if (!series.length || !axes.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
     const font = `${t.fontSize}px ${t.font}`;
     let labelW = 0;
-    for (const a of axes) labelW = Math.max(labelW, e.measure(String(a), font));
+    const names = axes.map((a) => this._lab(a));
+    for (const a of names) labelW = Math.max(labelW, e.measure(a, font));
     const cx = e.w / 2;
     const cy = e.h / 2;
     const R = Math.max(10, Math.min(e.w / 2 - labelW - 18, e.h / 2 - t.fontSize - 16));
@@ -2010,7 +2213,7 @@ class RadarChart extends Chart {
     const angle = (i) => -Math.PI / 2 + (i / N) * TAU;
     const on = series.map((s, i) => i).filter((i) => !this._isOff(i));
     const max = range(on.map((s) => series[s].values), 0)[1];
-    const niceMax = M.niceDomain(0, max, 5)[1] || 1;
+    const niceMax = o.max ?? (M.niceDomain(0, max, 5)[1] || 1);
 
     const ctx = e.ctx;
     ctx.strokeStyle = t.grid;
@@ -2035,7 +2238,7 @@ class RadarChart extends Chart {
     ctx.stroke();
     for (let i = 0; i < N; i++) {
       const a = angle(i);
-      e.text(String(axes[i]), cx + Math.cos(a) * (R + 10), cy + Math.sin(a) * (R + 10), {
+      e.text(names[i], cx + Math.cos(a) * (R + 10), cy + Math.sin(a) * (R + 10), {
         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',
@@ -2048,14 +2251,14 @@ class RadarChart extends Chart {
       const pts = [];
       for (let i = 0; i < N; i++) {
         const v = +ser.values[i] || 0;
-        const r = ((v * prog) / niceMax) * R;
+        const r = Math.min(1, (v * prog) / niceMax) * R;
         const a = angle(i);
         const p = { x: cx + Math.cos(a) * r, y: cy + Math.sin(a) * r };
         pts.push(p);
         this.hits.add({
           _id: `${s}-${i}`, x: p.x - 7, y: p.y - 7, w: 14, h: 14,
-          tipX: p.x, tipY: p.y - 4, index: i, series: s, value: v,
-          tooltip: { title: String(axes[i]), rows: [{ color, name: ser.name || 'Series ' + (s + 1), value: this._fmt(v) }] },
+          tipX: p.x, tipY: p.y - 4, index: i, label: axes[i], series: s, value: v, row: ser,
+          tooltip: { title: names[i], rows: [{ color, name: ser.name || 'Series ' + (s + 1), value: this._fmt(v) }] },
         });
       }
       e.poly(pts, { fill: M.colorAlpha(color, 0.2), stroke: color, lineWidth: 2, close: true, join: 'round' });
@@ -2074,7 +2277,9 @@ class RadarChart extends Chart {
 
 
 class PolarChart extends Chart {
-  get _kind() { return 'Polar chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'polar', name: 'PolarChart', aria: 'Polar chart', data: 'rows', options: ['label', 'value', 'scale'], enums: { scale: ['sqrt', 'linear'] } };
+  }
 
   _render() {
     const o = this.options;
@@ -2082,8 +2287,8 @@ class PolarChart extends Chart {
     if (!data.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
-    const labelOf = o.label || ((d) => d.label);
-    const valueOf = o.value || ((d) => d.value);
+    const labelOf = this._fn('label') || ((d) => d.label);
+    const valueOf = this._fn('value') || ((d) => d.value);
     const N = data.length;
     const font = `${t.fontSize}px ${t.font}`;
     const cx = e.w / 2, cy = e.h / 2;
@@ -2114,7 +2319,7 @@ class PolarChart extends Chart {
         _id: i, x: cx - R, y: cy - R, w: R * 2, h: R * 2,
         test: inSector(cx, cy, 0, Math.max(r, 12), a0, a1),
         tipX: cx + c * r * 0.7, tipY: cy + s * r * 0.7 - 6,
-        data: data[i], index: i, value: v,
+        index: i, label: labelOf(data[i], i), value: v, row: data[i],
         tooltip: `${labelOf(data[i], i)}: ${this._fmt(v)}`,
       });
     }
@@ -2122,21 +2327,26 @@ class PolarChart extends Chart {
 }
 
 // ── src/charts/gauge.js
-// GaugeChart — animated arc; setValue(v) tweens from the current value.
+// GaugeChart — animated arc; update({ data }) tweens from the shown value.
 
 class GaugeChart extends Chart {
-  get _kind() { return 'Gauge chart'; } // aria-label default (bundlers minify class names)
-  setValue(v) {
-    this._from = this._shown ?? 0;
-    return this.update({ value: v });
+  static get meta() {
+    return {
+      id: 'gauge', name: 'GaugeChart', aria: 'Gauge', data: 'number', options: ['min', 'max', 'unit'],
+      renamed: { value: 'data', label: 'title' },
+    };
+  }
+  update(patch = {}) {
+    if ('data' in patch) this._from = this._shown;
+    return super.update(patch);
   }
   _render() {
     const e = this.engine;
     const t = this.theme;
     const o = this.options;
-    const min = o.min || 0;
-    const max = o.max != null ? o.max : 100;
-    const target = Math.max(min, Math.min(max, +o.value || 0));
+    const min = o.min ?? 0;
+    const max = o.max ?? 100;
+    const target = Math.max(min, Math.min(max, +o.data || 0));
     const from = this._from ?? min;
     const val = from + (target - from) * this._anim.progress;
     this._shown = val;
@@ -2146,7 +2356,7 @@ class GaugeChart extends Chart {
     const r = R * 0.8;
     const a0 = Math.PI * 1.1;
     const a1 = Math.PI * 1.9;
-    const color = o.color || this.palette[0];
+    const color = this.palette[0];
     e.arc(cx, cy, r, R, a0, a1, { fill: t.grid });
     const aEnd = a0 + ((a1 - a0) * (val - min)) / (max - min || 1);
     if (aEnd > a0) e.arc(cx, cy, r, R, a0, aEnd, { fill: color });
@@ -2154,66 +2364,70 @@ class GaugeChart extends Chart {
     e.text(txt, cx, cy - R * 0.08, {
       fill: t.text, font: `700 ${Math.max(12, R / 2.6)}px ${t.font}`, align: 'center', baseline: 'middle',
     });
-    if (o.label) {
-      e.text(o.label, cx, cy + R * 0.22, { fill: t.muted, font: `${t.fontSize}px ${t.font}`, align: 'center', baseline: 'top' });
+    if (o.title) {
+      e.text(o.title, cx, cy + R * 0.22, { fill: t.muted, font: `${t.fontSize}px ${t.font}`, align: 'center', baseline: 'top' });
     }
-    this.canvas.setAttribute('aria-label', `${o.ariaLabel || o.label || o.title || 'Gauge'}: ${txt}`);
+    this.canvas.setAttribute('aria-label', `${o.title || 'Gauge'}: ${txt}`);
   }
 }
 
 // ── src/charts/heatmap.js
-// HeatmapChart — cells colored between colorLow and colorHigh.
+// HeatmapChart — data { x: [...], y: [...], values: [[...]] } (values[y][x]),
+// cells colored between colors.low and colors.high.
 
 
 class HeatmapChart extends Chart {
-  get _kind() { return 'Heatmap chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'heatmap', name: 'HeatmapChart', aria: 'Heatmap', data: 'matrix', options: ['labelFormat'], colors: 'an object like { low: \'#eef\', high: \'#36c\' }' };
+  }
 
   _render() {
     const o = this.options;
-    const data = o.data || []; // [{ x, y, value }]
-    const xLabels = o.xLabels || [];
-    const yLabels = o.yLabels || [];
-    if (!data.length || !xLabels.length || !yLabels.length) return this._empty();
+    const { x: xLabels = [], y: yLabels = [], values = [] } = o.data || {};
+    if (!values.length || !xLabels.length || !yLabels.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
     const font = `${t.fontSize}px ${t.font}`;
     let labelW = 0;
-    for (const s of yLabels) labelW = Math.max(labelW, e.measure(String(s), font));
+    const yText = Array.from(yLabels, (l) => this._lab(l));
+    for (const s of yText) labelW = Math.max(labelW, e.measure(s, font));
     const px = Math.ceil(labelW) + 12, py = 8;
     const pw = Math.max(1, e.w - px - 8);
     const ph = Math.max(1, e.h - py - t.fontSize - 14);
 
     let vMax = -Infinity, vMin = Infinity;
-    for (const d of data) {
-      if (d.value > vMax) vMax = d.value;
-      if (d.value < vMin) vMin = d.value;
+    for (const row of values) {
+      for (const v of row || []) {
+        if (v > vMax) vMax = v;
+        if (v < vMin) vMin = v;
+      }
     }
     const cellW = pw / xLabels.length;
     const cellH = ph / yLabels.length;
-    const lo = o.colorLow || M.colorAlpha(this.palette[0], 0.08);
-    const hi = o.colorHigh || this.palette[0];
+    const c = o.colors || {};
+    const hi = c.high || this.palette[0];
+    const lo = c.low || M.colorAlpha(hi, 0.08);
     const gap = cellW > 6 && cellH > 6 ? 1 : 0;
     const prog = this._anim.progress;
-    const xi = new Map(xLabels.map((l, i) => [l, i]));
-    const yi = new Map(yLabels.map((l, i) => [l, i]));
-
-    for (let k = 0; k < data.length; k++) {
-      const d = data[k];
-      const cx = typeof d.x === 'number' ? d.x : xi.get(d.x) ?? -1;
-      const cy = typeof d.y === 'number' ? d.y : yi.get(d.y) ?? -1;
-      if (cx < 0 || cy < 0) continue;
-      const x = px + cx * cellW;
-      const y = py + cy * cellH;
-      const n = vMax > vMin ? (d.value - vMin) / (vMax - vMin) : 0.5;
-      e.rect(x + gap, y + gap, cellW - gap * 2, cellH - gap * 2, { fill: M.colorMix(lo, hi, n * prog), radius: gap ? 2 : 0 });
-      this.hits.add({
-        _id: k, x, y, w: cellW, h: cellH, tipX: x + cellW / 2, tipY: y, data: d, index: k, value: d.value,
-        tooltip: `${xLabels[cx]} · ${yLabels[cy]}: ${this._fmt(d.value)}`,
-      });
+    for (let cy = 0; cy < yLabels.length; cy++) {
+      const row = values[cy] || [];
+      for (let cx = 0; cx < xLabels.length; cx++) {
+        const v = row[cx];
+        if (v == null || v !== v) continue;
+        const x = px + cx * cellW;
+        const y = py + cy * cellH;
+        const n = vMax > vMin ? (v - vMin) / (vMax - vMin) : 0.5;
+        e.rect(x + gap, y + gap, cellW - gap * 2, cellH - gap * 2, { fill: M.colorMix(lo, hi, n * prog), radius: gap ? 2 : 0 });
+        this.hits.add({
+          _id: cy * xLabels.length + cx, x, y, w: cellW, h: cellH, tipX: x + cellW / 2, tipY: y,
+          index: cx, series: cy, label: xLabels[cx], value: v, row: { x: xLabels[cx], y: yLabels[cy], value: v },
+          tooltip: `${this._lab(xLabels[cx])} · ${yText[cy]}: ${this._fmt(v)}`,
+        });
+      }
     }
     let lastEnd = -Infinity;
     for (let i = 0; i < xLabels.length; i++) {
-      const txt = String(xLabels[i]);
+      const txt = this._lab(xLabels[i]);
       const w = e.measure(txt, font);
       const x = px + (i + 0.5) * cellW;
       if (x - w / 2 < lastEnd + 4) continue;
@@ -2222,7 +2436,7 @@ class HeatmapChart extends Chart {
     }
     const step = Math.ceil((t.fontSize + 2) / cellH);
     for (let i = 0; i < yLabels.length; i += step) {
-      e.text(String(yLabels[i]), px - 6, py + (i + 0.5) * cellH, { fill: t.muted, font, align: 'right', baseline: 'middle' });
+      e.text(yText[i], px - 6, py + (i + 0.5) * cellH, { fill: t.muted, font, align: 'right', baseline: 'middle' });
     }
     if (this._hover) {
       const r = this._hover;
@@ -2237,7 +2451,9 @@ class HeatmapChart extends Chart {
 
 
 class BoxplotChart extends Chart {
-  get _kind() { return 'Boxplot chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'boxplot', name: 'BoxplotChart', aria: 'Box plot', data: 'boxes', options: ['labelFormat', 'min', 'max'] };
+  }
 
   _render() {
     const o = this.options;
@@ -2253,8 +2469,8 @@ class BoxplotChart extends Chart {
         if (v < yMin) yMin = v;
       }
     }
-    const [yLo, yHi] = M.niceDomain(yMin, yMax, 5);
-    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: data.map((d) => d.label), yTickFormat: o.yTickFormat });
+    const [yLo, yHi] = valueDomain(o, yMin, yMax);
+    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: data.map((d) => d.label) });
     const slot = ax.pw / data.length;
     const boxW = Math.min(40, slot * 0.5);
     const prog = this._anim.progress;
@@ -2277,9 +2493,9 @@ class BoxplotChart extends Chart {
       const top = ax.yToPx(d.max), bot = ax.yToPx(d.min);
       this.hits.add({
         _id: i, x: cx - boxW / 2, y: top, w: boxW, h: Math.max(4, bot - top),
-        tipX: cx, tipY: ax.yToPx(d.q3), data: d, index: i,
+        tipX: cx, tipY: ax.yToPx(d.q3), index: i, label: d.label, value: d.median, row: d,
         tooltip: {
-          title: String(d.label),
+          title: this._lab(d.label),
           rows: [['max', d.max], ['Q3', d.q3], ['median', d.median], ['Q1', d.q1], ['min', d.min]]
             .map(([name, v]) => ({ name, value: this._fmt(v) })),
         },
@@ -2292,7 +2508,9 @@ class BoxplotChart extends Chart {
 // FunnelChart — conversion stages; each segment narrows to the next value.
 
 class FunnelChart extends Chart {
-  get _kind() { return 'Funnel chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'funnel', name: 'FunnelChart', aria: 'Funnel chart', data: 'rows', options: ['label', 'value', 'labelColor'] };
+  }
 
   _render() {
     const o = this.options;
@@ -2300,8 +2518,8 @@ class FunnelChart extends Chart {
     if (!data.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
-    const labelOf = o.label || ((d) => d.label);
-    const valueOf = o.value || ((d) => d.value);
+    const labelOf = this._fn('label') || ((d) => d.label);
+    const valueOf = this._fn('value') || ((d) => d.value);
     const N = data.length;
     const vals = data.map((d, i) => Math.max(0, +valueOf(d, i) || 0));
     const max = Math.max(1e-9, vals.reduce((a, v) => (v > a ? v : a), 0));
@@ -2334,7 +2552,7 @@ class FunnelChart extends Chart {
       });
       this.hits.add({
         _id: i, x: cx - Math.max(wTop, 8) / 2, y: yTop, w: Math.max(wTop, 8), h: segH,
-        tipX: cx, tipY: yTop, data: data[i], index: i, value: v,
+        tipX: cx, tipY: yTop, index: i, label: labelOf(data[i], i), value: v, row: data[i],
         tooltip: `${labelOf(data[i], i)}: ${this._fmt(v)} (${((v / first) * 100).toFixed(1)}%)`,
       });
     }
@@ -2381,7 +2599,9 @@ function squarify(items, rect, place) {
 }
 
 class TreemapChart extends Chart {
-  get _kind() { return 'Treemap chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'treemap', name: 'TreemapChart', aria: 'Treemap', data: 'rows', options: ['label', 'value', 'labelColor'] };
+  }
 
   _render() {
     const o = this.options;
@@ -2389,10 +2609,10 @@ class TreemapChart extends Chart {
     if (!data.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
-    const labelOf = o.label || ((d) => d.label);
-    const valueOf = o.value || ((d) => d.value);
+    const labelOf = this._fn('label') || ((d) => d.label);
+    const valueOf = this._fn('value') || ((d) => d.value);
     const items = data
-      .map((d, i) => ({ label: String(labelOf(d, i)), value: Math.max(0, +valueOf(d, i) || 0), color: this._colorOf(i, d), data: d, _id: i }))
+      .map((d, i) => ({ raw: labelOf(d, i), label: String(labelOf(d, i)), value: Math.max(0, +valueOf(d, i) || 0), color: this._colorOf(i, d), data: d, _id: i }))
       .filter((it) => it.value > 0)
       .sort((a, b) => b.value - a.value);
     if (!items.length) return this._empty();
@@ -2412,7 +2632,7 @@ class TreemapChart extends Chart {
         e.withAlpha(0.85, () => e.text(this._fmt(it.value), x + 6, y + 8 + t.fontSize, { fill: fg, 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, data: it.data, index: it._id, value: it.value,
+        _id: it._id, x, y, w, h, tipX: x + w / 2, tipY: y, index: it._id, label: it.raw, value: it.value, row: it.data,
         tooltip: `${it.label}: ${this._fmt(it.value)}`,
       });
     });
@@ -2420,22 +2640,26 @@ class TreemapChart extends Chart {
 }
 
 // ── src/charts/sparkline.js
-// Sparkline — tiny trend line, no axes. Accepts numbers or rows.
+// SparklineChart — tiny trend line, no axes. Same data as LineChart.
 
 
 
-class Sparkline extends Chart {
-  get _kind() { return 'Sparkline'; } // aria-label default (bundlers minify class names)
+class SparklineChart extends Chart {
+  static get meta() {
+    return { id: 'sparkline', name: 'SparklineChart', aria: 'Sparkline', data: 'rows', options: ['label', 'value', 'min', 'max', 'fill', 'lastDot'] };
+  }
 
   _render() {
     const o = this.options;
-    const data = o.data || [];
+    const data = toRows(o.data);
     if (!data.length) return;
     const e = this.engine;
     const t = this.theme;
-    const valueOf = o.value || ((v) => (typeof v === 'object' && v ? +v.value : +v));
-    const values = data.map((d, i) => valueOf(d, i));
-    const [yMin, yMax] = range([values]);
+    const valueOf = this._fn('value') || ((d) => d.value);
+    const labelOf = this._fn('label') || ((d) => d.label);
+    const values = data.map((d, i) => +valueOf(d, i));
+    const [lo, hi] = range([values]);
+    const yMin = o.min ?? lo, yMax = o.max ?? hi;
     const yRange = yMax - yMin || 1;
     const pad = Math.max(2, t.pointRadius + 1);
     const w = e.w - pad * 2;
@@ -2444,7 +2668,7 @@ class Sparkline extends Chart {
       x: pad + (i / (values.length - 1 || 1)) * w,
       y: pad + h - ((v - yMin) / yRange) * h,
     }));
-    const color = o.color || this.palette[0];
+    const color = this.palette[0];
     const cps = M.bezierControlPoints(points);
     e.clip(0, 0, e.w * this._anim.progress, e.h);
     if (o.fill !== false) {
@@ -2461,7 +2685,8 @@ class Sparkline extends Chart {
     points.forEach((p, i) => {
       const l = i ? (points[i - 1].x + p.x) / 2 : 0;
       const r = i < n - 1 ? (points[i + 1].x + p.x) / 2 : e.w;
-      this.hits.add({ _id: i, x: l, y: 0, w: r - l, h: e.h, tipX: p.x, tipY: p.y - 4, index: i, value: values[i], tooltip: this._fmt(values[i]) });
+      const label = labelOf(data[i], i);
+      this.hits.add({ _id: i, x: l, y: 0, w: r - l, h: e.h, tipX: p.x, tipY: p.y - 4, index: i, label, value: values[i], row: data[i], tooltip: `${label}: ${this._fmt(values[i])}` });
     });
     if (this._hover) {
       const p = points[this._hover._id];
@@ -2471,23 +2696,34 @@ class Sparkline extends Chart {
 }
 
 // ── src/charts/realtime.js
-// RealtimeChart — streaming lines over a rolling window: push() a sample.
-
+// RealtimeChart — streaming lines over a rolling window.
+//   data: { series: [{ name, color? }] }   then chart.push([v1, v2, …]) per sample
 
 
 class RealtimeChart extends Chart {
-  get _kind() { return 'Realtime chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'realtime', name: 'RealtimeChart', aria: 'Realtime chart', data: 'stream', options: ['min', 'max', 'window'] };
+  }
   constructor(container, options = {}) {
     super(container, options);
-    this.options.windowSize = options.windowSize || 200;
-    this._series = (options.series || [{ name: 'Series' }]).map((s) => ({ name: s.name || 'Series', color: s.color, values: [] }));
+    this._series = [];
+    this._sync();
     this._follow = true;
-    this._streaming = true;
+  }
+  // (Re)build the series from data, keeping samples already received.
+  _sync() {
+    const list = this.options.data?.series || [{ name: 'Series' }];
+    this._series = list.map((s, i) => ({ name: s.name || 'Series ' + (i + 1), color: s.color, values: this._series[i]?.values || [] }));
+  }
+  update(patch = {}) {
+    super.update(patch);
+    if ('data' in patch) this._sync();
+    return this;
   }
   _legend() { return this._series.length > 1 ? this._seriesLegend(this._series) : null; }
   push(values) {
     const arr = Array.isArray(values) ? values : [values];
-    const N = this.options.windowSize;
+    const N = this.options.window || 200;
     for (let i = 0; i < this._series.length; i++) {
       const v = this._series[i].values;
       v.push(arr[i] != null ? +arr[i] : NaN);
@@ -2496,13 +2732,13 @@ class RealtimeChart extends Chart {
     if (this._auto) { this._state = null; this._auto = false; }
     this._dirty = true;
     this._anim.progress = 1;
-    scheduler.schedule(this);
+    schedule(this);
     return this;
   }
   clear() {
     for (const s of this._series) s.values.length = 0;
     this._dirty = true;
-    scheduler.schedule(this);
+    schedule(this);
     return this;
   }
   _render() {
@@ -2512,16 +2748,16 @@ class RealtimeChart extends Chart {
     const on = this._series.map((s, i) => i).filter((i) => !this._isOff(i));
     const hasData = this._series.some((s) => s.values.length > 0);
     if (!hasData) {
-      const ax = drawCartesian(this, { yMin: 0, yMax: 100, yTickFormat: o.yTickFormat });
-      e.text(o.waitingText || 'streaming…', ax.px + ax.pw / 2, ax.py + ax.ph / 2, {
+      const ax = drawCartesian(this, { yMin: o.min ?? 0, yMax: o.max ?? 100 });
+      e.text(o.emptyText || 'Waiting for data…', ax.px + ax.pw / 2, ax.py + ax.ph / 2, {
         fill: t.muted, font: `${t.fontSize}px ${t.font}`, align: 'center', baseline: 'middle',
       });
       return;
     }
-    const [lo, hi] = range(on.map((s) => this._series[s].values.filter((v) => v === v)), o.yMin != null ? o.yMin : 0);
-    const [yLo, yHi] = o.yMax != null ? [o.yMin || 0, o.yMax] : M.niceDomain(lo, hi, 5);
-    const N = o.windowSize;
-    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, yTickFormat: o.yTickFormat });
+    const [lo, hi] = range(on.map((s) => this._series[s].values.filter((v) => v === v)), 0);
+    const [yLo, yHi] = valueDomain(o, lo, hi);
+    const N = o.window || 200;
+    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi });
     const xAt = (i, len) => ax.px + ((N - len + i) / (N - 1)) * ax.pw; // newest sample on the right edge
     const len = this._series[0].values.length;
     this._steps = [];
@@ -2554,41 +2790,45 @@ class RealtimeChart extends Chart {
       const x = this._steps[k];
       e.poly([{ x, y: ax.py }, { x, y: ax.py + ax.ph }], { stroke: t.muted, lineWidth: 1, dash: [3, 3] });
       this._tipNow = { title: `#${k + 1 - len}`, rows };
+      this._hover = { _id: k, index: k, label: k + 1 - len };
       this.tooltip.show(x, ax.py + 8, this._tipNow, t);
     }
   }
 }
 
 // ── src/charts/waterfall.js
-// WaterfallChart — running total; rows with isTotal reset the bar to zero.
-
+// WaterfallChart — running total. A row with total: true is drawn from zero to
+// its value (a subtotal or the end result). Colors: { up, down, total }.
 
 
 class WaterfallChart extends Chart {
-  get _kind() { return 'Waterfall chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'waterfall', name: 'WaterfallChart', aria: 'Waterfall chart', data: 'steps', options: ['labelFormat', 'min', 'max'], colors: 'an object like { up, down, total }' };
+  }
 
   _render() {
     const o = this.options;
-    const data = toRows(o.data);
+    const data = Array.isArray(o.data) ? o.data : [];
     if (!data.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
     let cum = 0;
     const segs = data.map((d) => {
       const v = +d.value || 0;
-      const seg = d.isTotal ? { from: 0, to: v } : { from: cum, to: cum + v };
+      const seg = d.total ? { from: 0, to: v } : { from: cum, to: cum + v };
       cum = seg.to;
-      return { ...seg, value: v, isTotal: !!d.isTotal, label: d.label };
+      return { ...seg, value: v, total: !!d.total, label: d.label };
     });
     const [lo, hi] = range([segs.map((s) => s.from), segs.map((s) => s.to)], 0, 0);
-    const [yLo, yHi] = M.niceDomain(lo, hi, 5);
-    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: segs.map((s) => s.label), yTickFormat: o.yTickFormat });
+    const [yLo, yHi] = valueDomain(o, lo, hi);
+    const ax = drawCartesian(this, { yMin: yLo, yMax: yHi, xLabels: segs.map((s) => s.label) });
     const slot = ax.pw / segs.length;
     const barW = Math.max(1, Math.min(60, slot * 0.7));
     const prog = this._anim.progress;
-    const up = o.colorUp || '#10b981';
-    const down = o.colorDown || '#ef4444';
-    const total = o.colorTotal || '#6366f1';
+    const c = o.colors || {};
+    const up = c.up || '#10b981';
+    const down = c.down || '#ef4444';
+    const total = c.total || '#6366f1';
 
     for (let i = 0; i < segs.length; i++) {
       const s = segs[i];
@@ -2596,15 +2836,15 @@ class WaterfallChart extends Chart {
       const y0 = ax.yToPx(s.from);
       const h = Math.abs(ax.yToPx(s.to) - y0) * prog;
       const top = s.to >= s.from ? y0 - h : y0;
-      e.rect(x, top, barW, Math.max(h, 1), { fill: s.isTotal ? total : s.value >= 0 ? up : down, radius: t.barRadius });
+      e.rect(x, top, barW, Math.max(h, 1), { fill: s.total ? total : s.value >= 0 ? up : down, radius: t.barRadius });
       if (i < segs.length - 1 && prog === 1) {
         const yEnd = ax.yToPx(s.to);
         e.poly([{ x: x + barW, y: yEnd }, { x: x + slot, y: yEnd }], { stroke: t.muted, lineWidth: 1, dash: [3, 3] });
       }
       this.hits.add({
         _id: i, x, y: top, w: barW, h: Math.max(h, 4), tipX: x + barW / 2, tipY: top,
-        data: data[i], index: i, value: s.value,
-        tooltip: `${s.label}: ${s.value > 0 && !s.isTotal ? '+' : ''}${this._fmt(s.value)}`,
+        index: i, label: s.label, value: s.value, row: data[i],
+        tooltip: `${this._lab(s.label)}: ${s.value > 0 && !s.total ? '+' : ''}${this._fmt(s.value)}`,
       });
     }
     if (this._hover) {
@@ -2615,39 +2855,47 @@ class WaterfallChart extends Chart {
 }
 
 // ── src/charts/composite.js
-// CompositeChart — bars, areas, lines and scatter on one category axis,
-// with an optional right y axis (layer.axis = 'right').
+// CompositeChart — bars, areas, lines and dots on one category axis, with an
+// optional right y axis.
 //
-// Layer: { type: 'bar'|'line'|'area'|'scatter', name, values, axis?, color?, radius? }
+//   data: { categories, series: [{ type: 'bar'|'line'|'area'|'scatter', name,
+//           values, axis?: 'right', format?, color? }] }
+// scatter values line up with categories like the others (null = no dot).
 
 
 
+const TYPES = ['bar', 'line', 'area', 'scatter'];
+
 class CompositeChart extends Chart {
-  get _kind() { return 'Composite chart'; } // aria-label default (bundlers minify class names)
+  static get meta() {
+    return { id: 'composite', name: 'CompositeChart', aria: 'Composite chart', data: 'series', options: ['labelFormat', 'min', 'max', 'xScale'], enums: { xScale: ['category', 'time'] } };
+  }
   constructor(container, options) {
     super(container, options);
     this._follow = true;
   }
   _legend() {
-    return (this.options.layers || []).map((l, i) => ({
+    return (this.options.data?.series || []).map((l, i) => ({
       label: (l.name || l.type) + (l.axis === 'right' ? ' (R)' : ''),
       color: this._colorOf(i, l),
     }));
   }
   _render() {
     const o = this.options;
-    const all = o.layers || [];
-    const cats = o.categories || [];
+    const { categories: cats = [], series: all = [] } = o.data || {};
     if (!all.length || !cats.length) return this._empty();
     const e = this.engine;
     const t = this.theme;
+    all.forEach((l, i) => {
+      if (!TYPES.includes(l.type)) warn(`CompositeChart: series[${i}] type must be ${TYPES.map((x) => `'${x}'`).join(' | ')} — got ${JSON.stringify(l.type)}.`);
+    });
     const layers = all.map((l, i) => ({ ...l, i, color: this._colorOf(i, l) })).filter((l) => !this._isOff(l.i));
-    const yOf = (l, v) => (l.type === 'scatter' ? v.y : +v);
 
     const domain = (ll) => {
       let mn = 0, mx = -Infinity;
       for (const l of ll) for (const v of l.values) {
-        const y = yOf(l, v);
+        if (v == null) continue;
+        const y = +v;
         if (y < mn) mn = y;
         if (y > mx) mx = y;
       }
@@ -2655,15 +2903,18 @@ class CompositeChart extends Chart {
     };
     const left = layers.filter((l) => l.axis !== 'right');
     const rightL = layers.filter((l) => l.axis === 'right');
-    const [lLo, lHi] = domain(left);
+    // min / max set the left axis; each axis uses the format of its first
+    // series that has one.
+    let [lLo, lHi] = domain(left);
+    if (o.min != null || o.max != null) [lLo, lHi] = valueDomain(o, o.min ?? lLo, o.max ?? lHi);
+    const fmtOf = (ll) => ll.find((l) => l.format)?.format;
     const useTime = o.xScale === 'time';
     const ax = drawCartesian(this, {
       yMin: lLo, yMax: lHi,
-      yTickFormat: o.yLeftTickFormat || o.yTickFormat,
-      right: rightL.length ? (([a, b]) => ({ yMin: a, yMax: b, yTickFormat: o.yRightTickFormat }))(domain(rightL)) : null,
+      yFormat: fmtOf(left),
+      right: rightL.length ? (([a, b]) => ({ yMin: a, yMax: b, yFormat: fmtOf(rightL) }))(domain(rightL)) : null,
       xLabels: useTime ? null : cats,
       xTime: useTime ? { min: +cats[0], max: +cats[cats.length - 1] } : null,
-      xTickFormat: o.xTickFormat,
     });
     const yPx = (l) => (l.axis === 'right' && ax.yRToPx ? ax.yRToPx : ax.yToPx);
     const xAt = useTime
@@ -2708,8 +2959,9 @@ class CompositeChart extends Chart {
     e.unclip();
     for (const l of layers.filter((x) => x.type === 'scatter')) {
       const toPx = yPx(l);
-      const items = l.values.map((p) => ({ x: xAt(typeof p.x === 'number' ? p.x : cats.indexOf(p.x)), y: toPx(p.y) }));
-      e.withAlpha(0.8, () => e.circles(items, l.color, l.radius || t.pointRadius + 1));
+      const items = [];
+      l.values.forEach((v, i) => { if (v != null) items.push({ x: xAt(i), y: toPx(+v) }); });
+      e.withAlpha(0.8, () => e.circles(items, l.color, t.pointRadius + 1));
     }
 
     // Shared tooltip for the category under the pointer.
@@ -2722,16 +2974,12 @@ class CompositeChart extends Chart {
       e.withAlpha(0.06, () => e.rect(x - slot / 2, ax.py, slot, ax.ph, { fill: t.text }));
       const rows = [];
       for (const l of layers) {
-        let v;
-        if (l.type === 'scatter') {
-          const p = l.values.find((p) => (typeof p.x === 'number' ? p.x : cats.indexOf(p.x)) === idx);
-          if (!p) continue;
-          v = p.y;
-        } else v = +l.values[idx];
-        rows.push({ color: l.color, name: l.name || l.type, value: this._fmt(v) });
+        const v = l.values[idx];
+        if (v == null) continue;
+        rows.push({ color: l.color, name: l.name || l.type, value: M.formatNumber(+v, l.format ?? o.format) });
       }
-      this._tipNow = { title: useTime ? new Date(+cats[idx]).toLocaleString() : String(cats[idx]), rows };
-      this._hover = { _id: idx, index: idx };
+      this._tipNow = { title: this._lab(cats[idx], useTime), rows };
+      this._hover = { _id: idx, index: idx, label: cats[idx] };
       this.tooltip.show(x, ax.py + 8, this._tipNow, t);
     } else if (this._cursor) {
       this.tooltip.hide();
@@ -2740,11 +2988,10 @@ class CompositeChart extends Chart {
 }
 
 // ── src/index.js
-const math = { TAU, clamp, lerp, extent, niceTicks, niceDomain, timeNiceTicks, timeFormat, minMaxDecimate, minMaxDecimateIdx, shouldDecimate, bezierControlPoints, springStep, colorParse, colorAlpha, colorMix, PALETTE, formatNumber };
-// @aeriz/chart — public API (1.x compatible).
+// @aeriz/chart 2.0 — public API.
 //
 // Every chart type is its own module, so bundlers keep only the ones you
 // import. Without a bundler, import one type directly:
 //   import { BarChart } from '@aeriz/chart/bar';
 
-export { Chart, getFPS, getActiveCount, scheduler, toRows, Engine, drawCartesian, math, PALETTE, BarChart, HBarChart, LineChart, AreaChart, StackedBarChart, GroupedBarChart, MultiLineChart, ScatterChart, BubbleChart, PieChart, RadarChart, PolarChart, GaugeChart, HeatmapChart, BoxplotChart, FunnelChart, TreemapChart, Sparkline, RealtimeChart, WaterfallChart, CompositeChart };
+export { Chart, PALETTE, BarChart, HBarChart, LineChart, AreaChart, StackedBarChart, GroupedBarChart, MultiLineChart, ScatterChart, BubbleChart, PieChart, RadarChart, PolarChart, GaugeChart, HeatmapChart, BoxplotChart, FunnelChart, TreemapChart, SparklineChart, RealtimeChart, WaterfallChart, CompositeChart };