plotagents 0.0.0-stage → 0.5.0

package/src/schema.js

@@ -0,0 +1,181 @@
+// JSON Schema of the spec: use it to declare plotagents as an agent tool, or
+// to validate an LLM's structured output. Descriptions are in English because
+// agents read them; chart text follows `locale`.
+import { TYPES, ALIASES } from './infer.js';
+
+const field = (d) => ({ type: 'string', description: d });
+const fieldOrList = (d) => ({ anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], description: d });
+const strOrList = { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] };
+
+export const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://unpkg.com/plotagents/schema.json',
+  title: 'plotagents spec',
+  description:
+    'Declarative chart spec. Data as rows (tidy) plus the field name for each role. Everything else has well-designed defaults.',
+  type: 'object',
+  required: ['data'],
+  properties: {
+    type: {
+      type: 'string',
+      enum: ['auto', ...TYPES, ...Object.keys(ALIASES)],
+      description:
+        'Compare: bar, count. Time: line, area. Relationships: scatter, bubble, regplot, residplot, jointplot, radar. Distributions (seaborn): hist, kde, ecdf, box, violin, strip, swarm, point. Part-to-whole: treemap, sunburst, donut, pie. Other: heatmap, sankey, kpi. seaborn names are accepted (barplot, countplot, histplot, kdeplot, boxplot, violinplot, lmplot…). "auto" (default) picks from the data.',
+    },
+    data: {
+      description: 'Array of rows, e.g. [{ "region": "Biobío", "sales": 1240 }]. For kpi it can be omitted in favor of `items`.',
+      anyOf: [{ type: 'array', items: { type: 'object' } }, { type: 'object' }],
+    },
+    title: { type: 'string', description: 'The finding as a full sentence, ideally with the key number, e.g. "Biobío accounts for 32% of sales".' },
+    subtitle: { type: 'string', description: 'How to read the chart: measure, unit and period, e.g. "Sales by region, CLP millions, 2025".' },
+    source: { type: 'string', description: 'Data source, shown at the bottom right.' },
+    locale: { type: 'string', enum: ['es', 'en'], description: 'Language and number format. Default "es" (1.234,5); use "en" for 1,234.5.' },
+    x: field('x-axis or category field (bar, line, area, scatter, heatmap, box, violin…).'),
+    y: fieldOrList('Value field. For line/bar a list of fields (wide table) turns each one into a series.'),
+    series: field('Field that splits the data into colored series. Alias: hue.'),
+    hue: field('Alias of series (seaborn naming).'),
+    value: field('Value field for treemap, sunburst, donut, heatmap, sankey and radar.'),
+    label: field('Name field (treemap, donut, point labels in scatter/regplot).'),
+    group: field('Level-1 group field for a two-level treemap (shortcut for path).'),
+    path: { type: 'array', items: { type: 'string' }, description: 'Hierarchy for treemap/sunburst, any depth: [level1, level2, …].' },
+    size: field('Bubble size field (area-proportional).'),
+    from: field('Sankey source field.'),
+    to: field('Sankey target field.'),
+    axis: field('radar: field with the axis names (long format).'),
+    axes: { type: 'array', items: { type: 'string' }, description: 'radar: fields to use as axes (wide format, one row per series).' },
+    items: {
+      type: 'array',
+      description: 'kpi: the indicators to show.',
+      items: {
+        type: 'object',
+        required: ['label', 'value'],
+        properties: {
+          label: { type: 'string' },
+          value: { type: 'number' },
+          delta: { type: 'number', description: 'Relative change as a fraction (0.12 = +12%).' },
+          previous: { type: 'number', description: 'Previous value; when given, the change is computed.' },
+          period: { type: 'string', description: 'What it is compared against, e.g. "vs 2025".' },
+          good: { type: 'string', enum: ['up', 'down'], description: 'Whether going up is good (up) or bad (down, e.g. costs).' },
+          trend: { type: 'array', items: { type: 'number' }, description: 'Short series for the sparkline.' },
+          target: { type: 'number', description: 'Target: draws a progress meter.' },
+          format: { type: 'string' },
+        },
+      },
+    },
+
+    // Maps, networks, flows
+    geo: { description: 'choropleth/symbolmap: "chile" (16 regions, default), "usa" (50 states + DC, Albers with Alaska/Hawaii insets; Puerto Rico when it has data), "world" (countries), a name registered with registerGeo(), or a GeoJSON FeatureCollection.', anyOf: [{ type: 'string' }, { type: 'object' }] },
+    key: field('choropleth/symbolmap: data field with the region, state or country name/code to match (US: "TX", "Texas", "06").'),
+    projection: { type: 'string', enum: ['mercator', 'equalEarth', 'albersUsa'], description: 'choropleth/symbolmap: map projection (picked automatically).' },
+    values: { type: 'boolean', description: 'choropleth with state codes (usa): false shows only the codes, without values.' },
+    featureKey: field('choropleth: feature property to match against (default tries code, id, ISO-3, name and aliases).'),
+    midpoint: { type: 'number', description: 'choropleth/heatmap: diverging color scale around this value (e.g. 0 for changes).' },
+    classes: { type: 'integer', description: 'choropleth: number of color classes (default 5).' },
+    nodes: { type: 'array', items: { type: 'object' }, description: 'network: node rows (id, group, size). flowchart: steps (id, label, type: start|end|process|decision|data|note, lane).' },
+    edges: { type: 'array', items: { type: 'object' }, description: 'flowchart: connections (from, to, label). Same as `data`.' },
+    layout: { type: 'string', enum: ['force', 'circle'], description: 'network layout.' },
+    matrix: { type: 'array', items: { type: 'array', items: { type: 'number' } }, description: 'chord: square flow matrix (with `names`).' },
+    names: { type: 'array', items: { type: 'string' }, description: 'chord: group names for `matrix`.' },
+    directed: { type: 'boolean', description: 'chord: treat flows as directed (default false).' },
+    direction: { type: 'string', enum: ['TB', 'LR'], description: 'flowchart: top-to-bottom or left-to-right (automatic by default).' },
+    age: field('pyramid: age-group field.'),
+    sex: field('pyramid: field with exactly two sides (e.g. sex).'),
+    percent: { type: 'boolean', description: 'pyramid: show shares of the total population.' },
+
+    // Layout and interaction
+    facet: field('One panel per value of this field (small multiples, seaborn col). Shared scales and colors.'),
+    columns: { type: 'integer', description: 'facet: panels per row (seaborn col_wrap). Reduced automatically on narrow screens.' },
+    sharey: { type: 'boolean', description: 'facet: same y scale in every panel (default true).' },
+    time: field('Time field (d3plus-style): shows one period at a time (the latest by default) and, in the browser, a slider with play. Not used by line/area, which get a range slider.'),
+    timeValue: { description: 'Period to show when `time` is set.' },
+    slider: { type: 'boolean', description: 'Browser: false removes the time slider (the chart shows `timeValue` or the latest period).' },
+    play: { type: 'boolean', description: 'Browser: false keeps the time slider but hides the play button.' },
+    compare: { description: 'With `time`: period to compute changes against: "previous" (default), "first", a specific period, or false.', anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }] },
+    colorBy: { type: 'string', enum: ['group', 'change', 'label'], description: 'treemap: "change" colors tiles by % change vs the comparison period (diverging, growth cool / decline warm); "label" colors a single-level treemap by item.' },
+    shade: { type: 'boolean', description: 'treemap/sunburst: subtle lightness steps inside each category (default false: one solid color per category).' },
+    xRange: { type: 'array', description: 'line/area: visible x range [from, to] (what the range slider sets).' },
+    focus: { description: 'treemap/sunburst: path to drill into, e.g. ["Mining"]. network: a node id to center and highlight with its neighbors. In the browser, clicking does it.', anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
+    depth: { type: 'integer', description: 'treemap/sunburst: how many levels to show.' },
+
+    // Scales and axes
+    xScale: { type: 'string', enum: ['linear', 'log'] },
+    yScale: { type: 'string', enum: ['linear', 'log'] },
+    xDomain: { type: 'array', items: { type: 'number' }, description: 'Fixed x domain [min, max].' },
+    yDomain: { type: 'array', items: { type: 'number' }, description: 'Fixed value-axis domain [min, max].' },
+    zero: { type: 'boolean', description: 'line: force (or prevent) a y axis starting at zero.' },
+    xLabel: { type: 'string', description: 'x-axis title.' },
+    yLabel: { type: 'string', description: 'y-axis title (drawn horizontally above the axis).' },
+    format: {
+      description: 'Value format: "number" | "compact" | "percent" | "currency" | "integer", or { type, prefix, suffix, decimals, currency }.',
+      anyOf: [
+        { type: 'string', enum: ['number', 'compact', 'percent', 'currency', 'integer'] },
+        { type: 'object', properties: { type: { type: 'string' }, prefix: { type: 'string' }, suffix: { type: 'string' }, decimals: { type: 'integer' }, currency: { type: 'string' } } },
+      ],
+    },
+
+    // Emphasis and annotation
+    highlight: { description: 'Emphasize one or more categories/series and mute the rest.', ...strOrList },
+    dashed: { description: 'Draw some shapes dashed (hatched fill + dashed outline; dashed stroke for lines) to mark estimates, projections or provisional figures. A category/series/region name or a list of them, a data field whose truthy rows are dashed, { field, equals }, or true for all.', anyOf: [{ type: 'string' }, { type: 'boolean' }, { type: 'array', items: { type: 'string' } }, { type: 'object', properties: { field: { type: 'string' }, equals: {} } }] },
+    dashedFrom: { description: 'line/area/bar on a time axis: x value from which marks are dashed (a projection). Lines turn dashed from the last firm point, over a soft labeled band.', anyOf: [{ type: 'string' }, { type: 'number' }] },
+    dashedLabel: { description: 'What the dashed shapes mean ("Projection", "Preliminary"): legend entry, band label and tooltip line. false hides the band label.', anyOf: [{ type: 'string' }, { type: 'boolean' }] },
+    labels: { description: 'Value labels: true, false or "auto". In scatter/regplot: a number of points or a list of names to label.', anyOf: [{ type: 'boolean' }, { type: 'string' }, { type: 'number' }, { type: 'array', items: { type: 'string' } }] },
+    refLines: { type: 'array', description: 'Reference lines (targets, averages).', items: { type: 'object', properties: { y: { type: 'number' }, x: { type: 'number' }, value: { type: 'number' }, label: { type: 'string' } } } },
+    annotations: { type: 'array', description: 'line/area: events on the x axis.', items: { type: 'object', properties: { x: {}, label: { type: 'string' } } } },
+
+    // Bars and lines
+    stack: { description: 'bar/area: true stacks; "percent" stacks to 100%.', anyOf: [{ type: 'boolean' }, { type: 'string', enum: ['percent'] }] },
+    horizontal: { type: 'boolean', description: 'Force horizontal orientation (otherwise chosen from label length and count).' },
+    sort: { type: 'string', enum: ['desc', 'asc', 'none', 'alpha'], description: 'bar: category order (desc by default unless the categories are time).' },
+    top: { type: 'integer', description: 'bar: keep the N largest and fold the rest into "Other".' },
+    index: { type: 'boolean', description: 'line: rebase each series to 100 at its first value (compare growth without a dual axis).' },
+    curve: { type: 'string', enum: ['linear', 'smooth', 'step'] },
+    aggregate: { type: 'string', enum: ['sum', 'mean', 'max', 'min', 'count', 'last', 'first'], description: 'How to combine repeated rows. Default sum.' },
+    ci: { description: 'line/bar/regplot: confidence interval (true = 95, or a number). In line/bar it switches the estimator to the mean.', anyOf: [{ type: 'boolean' }, { type: 'number' }] },
+    errorbar: { type: 'string', enum: ['ci', 'sd', 'se', 'pi', 'none'], description: 'Error bar or band type.' },
+    estimator: { type: 'string', enum: ['mean', 'median', 'sum', 'count'], description: 'How to summarize several observations per category.' },
+
+    // Statistics (seaborn)
+    bins: { type: 'integer', description: 'hist: number of bins.' },
+    binWidth: { type: 'number', description: 'hist: bin width.' },
+    stat: { type: 'string', enum: ['count', 'percent', 'density', 'probability'], description: 'hist: what the y axis measures.' },
+    kde: { type: 'boolean', description: 'hist: overlay a density curve.' },
+    multiple: { type: 'string', enum: ['layer', 'stack', 'dodge', 'fill'], description: 'hist/kde with hue: how groups are combined.' },
+    fill: { type: 'boolean', description: 'kde: fill the area. line: false removes the gradient under a single line.' },
+    order: { description: 'regplot: polynomial degree (number). box/violin/strip/swarm/point: category order (list).', anyOf: [{ type: 'integer' }, { type: 'array', items: { type: 'string' } }] },
+    lowess: { type: 'boolean', description: 'regplot: local regression instead of a straight line.' },
+    logx: { type: 'boolean', description: 'regplot: fit y ~ log(x) with a log x axis.' },
+    trend: { type: 'boolean', description: 'scatter: add a least-squares line and R².' },
+    annotate: { type: 'boolean', description: 'regplot: show R² and n.' },
+    kind: { type: 'string', enum: ['scatter', 'reg'], description: 'jointplot: center plot.' },
+    marginal: { type: 'string', enum: ['hist', 'kde'], description: 'jointplot: marginal plots.' },
+    inner: { type: 'string', enum: ['box', 'quartiles', 'points', 'none'], description: 'violin: what goes inside.' },
+    split: { type: 'boolean', description: 'violin: with two hue levels, one half each.' },
+    points: { type: 'boolean', description: 'box: overlay the observations. line: markers on every point.' },
+    normalize: { type: 'boolean', description: 'radar: scale each axis 0–1 by its own maximum.' },
+
+    // Part-to-whole
+    half: { type: 'boolean', description: 'donut: semicircle.' },
+
+    // Appearance
+    colors: { type: 'object', additionalProperties: { type: 'string' }, description: 'Pin colors to entities: { "Biobío": "#3A47B8" }.' },
+    palette: { description: 'Palette shortcut: a name ("cdia", "okabe-ito", "tableau10", "udec") or a list of colors in fixed order.', ...strOrList },
+    ramp: { description: 'Sequential ramp: a name ("indigo", "magenta", "teal", "amber") or a list of colors from light to dark.', ...strOrList },
+    theme: {
+      description: 'Theme: "papel" (light, default), "noche" (dark), or a JSON object deep-merged over `extends`. Keys: surface, ink, lede, muted, grid, axis, tint, dim, other, categorical (list or palette name), sequential, diverging, status {good, warning, critical}, font {family, mono, import}, type {title, subtitle, label, axis, legend, source, titleWeight}, marks {barRadius, barMax, lineWidth, pointRadius, gap, ring, areaOpacity, bandOpacity, dotOpacity}, axes {inside, grid}, layout {padding}.',
+      anyOf: [{ type: 'string', enum: ['papel', 'noche', 'light', 'dark'] }, { type: 'object' }],
+    },
+    font: { description: 'Typeface for the whole chart: a Google Fonts name ("Poppins"), a CSS stack ("\'Inter\', sans-serif") or { family, import }. configure({ font }) sets it for every chart.', anyOf: [{ type: 'string' }, { type: 'object' }] },
+    textScale: { type: 'number', description: 'Multiplies every text size (1.5, 2…); the layout is recomputed so nothing overlaps. Aliases: fontScale, labelScale. configure({ textScale }) sets it for every chart.' },
+    width: { type: 'number', description: 'Width in px (default 720; render() uses the container width).' },
+    height: { type: 'number', description: 'Height in px. Automatic for horizontal bars, heatmaps, KPI tiles, and narrow treemaps, sunbursts and radars.' },
+  },
+};
+
+/** Tool definition ready for Claude (Anthropic) or OpenAI. */
+export function toolDefinition({ name = 'plot', flavor = 'anthropic' } = {}) {
+  const description =
+    'Draws an elegant, accessible chart from tabular data. Pass rows in `data`, name the fields (x, y, series/hue…) and write a `title` that states the finding. Returns an SVG. Types: bar, count, line, area, scatter, bubble, regplot, residplot, jointplot, hist, kde, ecdf, box, violin, strip, swarm, point, radar, treemap, sunburst, donut, pie, heatmap, sankey, kpi, choropleth (Chile regions / world countries built in), symbolmap, network, chord, pyramid, flowchart (seaborn names accepted). `facet` makes panels; `time` adds a per-period slider. Set `locale: "en"` for English number formats.';
+  const { $schema, $id, title, ...params } = schema;
+  if (flavor === 'openai') return { type: 'function', function: { name, description, parameters: params } };
+  return { name, description, input_schema: params };
+}

package/src/stats.js

@@ -0,0 +1,246 @@
+// Estadística liviana para los gráficos tipo seaborn: cuantiles, intervalos
+// de confianza, histogramas, densidad (KDE), regresiones y ECDF.
+// Determinista (sin bootstrap aleatorio) para que el SVG sea reproducible.
+
+export const finite = (vs) => vs.filter((v) => Number.isFinite(v));
+export const sum = (vs) => vs.reduce((a, b) => a + b, 0);
+export const mean = (vs) => (vs.length ? sum(vs) / vs.length : NaN);
+
+export function variance(vs) {
+  const n = vs.length;
+  if (n < 2) return 0;
+  const m = mean(vs);
+  return vs.reduce((a, v) => a + (v - m) ** 2, 0) / (n - 1);
+}
+export const sd = (vs) => Math.sqrt(variance(vs));
+
+/** Cuantil con interpolación lineal (tipo 7, como numpy/R). `sorted` ordenado. */
+export function quantile(sorted, p) {
+  if (!sorted.length) return NaN;
+  const h = (sorted.length - 1) * p;
+  const lo = Math.floor(h), hi = Math.ceil(h);
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (h - lo);
+}
+export const median = (vs) => quantile([...vs].sort((a, b) => a - b), 0.5);
+
+/** Cuantil de la normal estándar (Acklam). */
+export function zQuantile(p) {
+  const a = [-39.69683028665376, 220.9460984245205, -275.9285104469687, 138.357751867269, -30.66479806614716, 2.506628277459239];
+  const b = [-54.47609879822406, 161.5858368580409, -155.6989798598866, 66.80131188771972, -13.28068155288572];
+  const c = [-0.007784894002430293, -0.3223964580411365, -2.400758277161838, -2.549732539343734, 4.374664141464968, 2.938163982698783];
+  const d = [0.007784695709041462, 0.3224671290700398, 2.445134137142996, 3.754408661907416];
+  const pl = 0.02425;
+  let q, r;
+  if (p < pl) { q = Math.sqrt(-2 * Math.log(p)); return (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1); }
+  if (p > 1 - pl) { q = Math.sqrt(-2 * Math.log(1 - p)); return -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1); }
+  q = p - 0.5; r = q * q;
+  return (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q / (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1);
+}
+
+/** Cuantil de la t de Student (expansión de Cornish-Fisher; exacta a ~1e-3 para df ≥ 3). */
+export function tQuantile(df, p = 0.975) {
+  if (df <= 0) return NaN;
+  if (df === 1) return Math.tan(Math.PI * (p - 0.5));
+  if (df === 2) { const a = 4 * p * (1 - p); return (2 * p - 1) * Math.sqrt(2 / a); }
+  const z = zQuantile(p);
+  const z3 = z ** 3, z5 = z ** 5, z7 = z ** 7, z9 = z ** 9;
+  return z + (z3 + z) / (4 * df) + (5 * z5 + 16 * z3 + 3 * z) / (96 * df ** 2) + (3 * z7 + 19 * z5 + 17 * z3 - 15 * z) / (384 * df ** 3) + (79 * z9 + 776 * z7 + 1482 * z5 - 1920 * z3 - 945 * z) / (92160 * df ** 4);
+}
+
+/** Intervalo de confianza de la media (t de Student). */
+export function meanCI(vs, level = 0.95) {
+  const v = finite(vs);
+  const m = mean(v);
+  if (v.length < 2) return [m, m];
+  const h = tQuantile(v.length - 1, 0.5 + level / 2) * sd(v) / Math.sqrt(v.length);
+  return [m - h, m + h];
+}
+
+/** Resumen para cajas: cuartiles, bigotes a 1,5·RIC y atípicos. */
+export function fiveNumber(vs) {
+  const s = finite(vs).sort((a, b) => a - b);
+  const q1 = quantile(s, 0.25), med = quantile(s, 0.5), q3 = quantile(s, 0.75);
+  const iqr = q3 - q1;
+  const loF = q1 - 1.5 * iqr, hiF = q3 + 1.5 * iqr;
+  const inside = s.filter((v) => v >= loF && v <= hiF);
+  return {
+    n: s.length, min: s[0], max: s[s.length - 1], q1, median: med, q3, iqr, mean: mean(s),
+    whiskerLo: inside.length ? inside[0] : q1, whiskerHi: inside.length ? inside[inside.length - 1] : q3,
+    outliers: s.filter((v) => v < loF || v > hiF),
+  };
+}
+
+const niceBinStep = (span, n) => {
+  const raw = span / Math.max(1, n);
+  const mag = 10 ** Math.floor(Math.log10(raw));
+  const f = raw / mag;
+  return (f <= 1 ? 1 : f <= 2 ? 2 : f <= 2.5 ? 2.5 : f <= 5 ? 5 : 10) * mag;
+};
+
+/**
+ * Histograma con anchos "bonitos". Por defecto, regla de Freedman–Diaconis
+ * acotada a 5–50 barras. Opciones: bins (número), binWidth, domain [a,b].
+ */
+export function histogram(vs, { bins, binWidth, domain } = {}) {
+  const s = finite(vs).sort((a, b) => a - b);
+  if (!s.length) return [];
+  let [lo, hi] = domain || [s[0], s[s.length - 1]];
+  if (lo === hi) { lo -= 0.5; hi += 0.5; }
+  let step = binWidth;
+  if (!step) {
+    let n = bins;
+    if (!n) {
+      const iqr = quantile(s, 0.75) - quantile(s, 0.25);
+      const fd = iqr > 0 ? 2 * iqr / Math.cbrt(s.length) : 0;
+      n = fd > 0 ? Math.ceil((hi - lo) / fd) : Math.ceil(Math.log2(s.length) + 1);
+      n = Math.max(5, Math.min(50, n));
+    }
+    step = bins ? (hi - lo) / bins : niceBinStep(hi - lo, n);
+  }
+  const start = bins ? lo : Math.floor(lo / step + 1e-9) * step;
+  const count = Math.max(1, Math.ceil((hi - start) / step - 1e-9));
+  const out = Array.from({ length: count }, (_, i) => ({ x0: start + i * step, x1: start + (i + 1) * step, count: 0 }));
+  for (const v of s) {
+    let i = Math.floor((v - start) / step);
+    if (i >= count) i = count - 1;
+    if (i >= 0) out[i].count++;
+  }
+  return out;
+}
+
+/** Ancho de banda de Scott (el de seaborn por defecto). */
+export function scottBandwidth(vs) {
+  const v = finite(vs);
+  const s = sd(v);
+  const iqr = quantile([...v].sort((a, b) => a - b), 0.75) - quantile([...v].sort((a, b) => a - b), 0.25);
+  const sigma = Math.min(s, iqr / 1.349) || s || 1;
+  return 1.06 * sigma * v.length ** -0.2;
+}
+
+/**
+ * Densidad por kernel gaussiano. Devuelve [[x, densidad], ...] en una grilla.
+ * `cut` extiende la grilla `cut` anchos de banda más allá de los extremos.
+ */
+export function kde(vs, { bandwidth, adjust = 1, gridSize = 160, extent, cut = 3, clip } = {}) {
+  const v = finite(vs);
+  if (!v.length) return [];
+  const bw = (bandwidth ?? scottBandwidth(v)) * adjust || 1;
+  let [lo, hi] = extent || [Math.min(...v) - cut * bw, Math.max(...v) + cut * bw];
+  if (clip) { lo = Math.max(lo, clip[0]); hi = Math.min(hi, clip[1]); }
+  const k = 1 / (v.length * bw * Math.sqrt(2 * Math.PI));
+  const out = [];
+  for (let i = 0; i < gridSize; i++) {
+    const x = lo + ((hi - lo) * i) / (gridSize - 1);
+    let d = 0;
+    for (const xi of v) { const u = (x - xi) / bw; if (u > -6 && u < 6) d += Math.exp(-0.5 * u * u); }
+    out.push([x, d * k]);
+  }
+  return out;
+}
+
+/** Función de distribución empírica: [[x, proporción acumulada], ...]. */
+export function ecdf(vs) {
+  const s = finite(vs).sort((a, b) => a - b);
+  return s.map((x, i) => [x, (i + 1) / s.length]);
+}
+
+// ── Regresión ──────────────────────────────────────────────────────────────
+
+function solve(A, b) {
+  // Gauss-Jordan con pivoteo parcial. Devuelve x tal que A·x = b.
+  const n = A.length;
+  const M = A.map((row, i) => [...row, b[i]]);
+  for (let c = 0; c < n; c++) {
+    let p = c;
+    for (let r = c + 1; r < n; r++) if (Math.abs(M[r][c]) > Math.abs(M[p][c])) p = r;
+    [M[c], M[p]] = [M[p], M[c]];
+    const d = M[c][c] || 1e-12;
+    for (let k = c; k <= n; k++) M[c][k] /= d;
+    for (let r = 0; r < n; r++) if (r !== c) { const f = M[r][c]; for (let k = c; k <= n; k++) M[r][k] -= f * M[c][k]; }
+  }
+  return M.map((row) => row[n]);
+}
+
+function inverse(A) {
+  const n = A.length;
+  return A.map((_, j) => solve(A, A.map((__, i) => (i === j ? 1 : 0)))).reduce((acc, col, j) => {
+    col.forEach((v, i) => { acc[i][j] = v; });
+    return acc;
+  }, A.map(() => new Array(n).fill(0)));
+}
+
+/**
+ * Regresión polinomial por mínimos cuadrados (order 1 = lineal), con banda de
+ * confianza para la media de y. Devuelve { coef, predict(x), band(x) → [lo,hi], r2, n }.
+ */
+export function polyfit(xs, ys, { order = 1, level = 0.95 } = {}) {
+  const pts = xs.map((x, i) => [x, ys[i]]).filter(([x, y]) => Number.isFinite(x) && Number.isFinite(y));
+  const n = pts.length;
+  const p = order + 1;
+  if (n <= p) {
+    const my = mean(pts.map((q) => q[1]));
+    return { coef: [my], predict: () => my, band: () => [my, my], r2: 0, n };
+  }
+  // Centrar x mejora la estabilidad numérica.
+  const mx = mean(pts.map((q) => q[0]));
+  const row = (x) => Array.from({ length: p }, (_, k) => (x - mx) ** k);
+  const X = pts.map(([x]) => row(x));
+  const XtX = Array.from({ length: p }, (_, i) => Array.from({ length: p }, (_, j) => X.reduce((a, r) => a + r[i] * r[j], 0)));
+  const Xty = Array.from({ length: p }, (_, i) => X.reduce((a, r, k) => a + r[i] * pts[k][1], 0));
+  const beta = solve(XtX, Xty);
+  const predict = (x) => row(x).reduce((a, v, k) => a + v * beta[k], 0);
+  const resid = pts.map(([x, y]) => y - predict(x));
+  const sse = sum(resid.map((r) => r * r));
+  const my = mean(pts.map((q) => q[1]));
+  const sst = sum(pts.map(([, y]) => (y - my) ** 2));
+  const s2 = sse / (n - p);
+  const inv = inverse(XtX);
+  const t = tQuantile(n - p, 0.5 + level / 2);
+  const band = (x) => {
+    const r = row(x);
+    let v = 0;
+    for (let i = 0; i < p; i++) for (let j = 0; j < p; j++) v += r[i] * inv[i][j] * r[j];
+    const h = t * Math.sqrt(Math.max(0, s2 * v));
+    const yh = predict(x);
+    return [yh - h, yh + h];
+  };
+  return { coef: beta, center: mx, predict, band, r2: sst ? 1 - sse / sst : 0, n };
+}
+
+/** Pearson r. */
+export function pearson(xs, ys) {
+  const pts = xs.map((x, i) => [x, ys[i]]).filter(([x, y]) => Number.isFinite(x) && Number.isFinite(y));
+  const mx = mean(pts.map((p) => p[0])), my = mean(pts.map((p) => p[1]));
+  let sxy = 0, sxx = 0, syy = 0;
+  for (const [x, y] of pts) { sxy += (x - mx) * (y - my); sxx += (x - mx) ** 2; syy += (y - my) ** 2; }
+  return sxx && syy ? sxy / Math.sqrt(sxx * syy) : 0;
+}
+
+/** LOWESS (Cleveland): suavizado local robusto. Devuelve [[x, y], ...] ordenado. */
+export function lowess(xs, ys, { frac = 2 / 3, iters = 2 } = {}) {
+  const pts = xs.map((x, i) => [x, ys[i]]).filter(([x, y]) => Number.isFinite(x) && Number.isFinite(y)).sort((a, b) => a[0] - b[0]);
+  const n = pts.length;
+  if (n < 3) return pts;
+  const r = Math.max(2, Math.ceil(frac * n));
+  let robust = new Array(n).fill(1);
+  let fit = new Array(n).fill(0);
+  for (let it = 0; it <= iters; it++) {
+    for (let i = 0; i < n; i++) {
+      const x0 = pts[i][0];
+      const d = pts.map(([x]) => Math.abs(x - x0)).sort((a, b) => a - b);
+      const h = d[Math.min(n - 1, r - 1)] || 1e-12;
+      let sw = 0, swx = 0, swy = 0, swxx = 0, swxy = 0;
+      for (let j = 0; j < n; j++) {
+        const u = Math.abs(pts[j][0] - x0) / h;
+        const w = u < 1 ? (1 - u ** 3) ** 3 * robust[j] : 0;
+        sw += w; swx += w * pts[j][0]; swy += w * pts[j][1]; swxx += w * pts[j][0] ** 2; swxy += w * pts[j][0] * pts[j][1];
+      }
+      const den = sw * swxx - swx * swx;
+      fit[i] = Math.abs(den) < 1e-12 ? swy / (sw || 1) : ((swxx * swy - swx * swxy) + (sw * swxy - swx * swy) * x0) / den;
+    }
+    const res = pts.map(([, y], i) => Math.abs(y - fit[i]));
+    const m = median(res) || 1e-12;
+    robust = res.map((e) => { const u = e / (6 * m); return u < 1 ? (1 - u * u) ** 2 : 0; });
+  }
+  return pts.map(([x], i) => [x, fit[i]]);
+}

package/src/svg.js

@@ -0,0 +1,85 @@
+// Constructor mínimo de SVG como texto (funciona en Node y en el navegador).
+
+import { ctx } from './context.js';
+
+const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+export const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ESC[c]);
+
+/** Redondea a 2 decimales para SVG compactos. */
+export const r2 = (n) => Math.round(n * 100) / 100;
+
+const ATTR_ALIAS = { className: 'class' };
+const KEEP_CASE = new Set(['viewBox', 'preserveAspectRatio', 'gradientUnits', 'gradientTransform', 'patternUnits', 'patternTransform', 'patternContentUnits', 'clipPathUnits', 'refX', 'refY', 'markerWidth', 'markerHeight', 'markerUnits', 'textLength', 'lengthAdjust', 'startOffset']);
+
+export function el(tag, attrs = {}, children) {
+  let s = '<' + tag;
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === null || v === false) continue;
+    const name = ATTR_ALIAS[k] || (KEEP_CASE.has(k) ? k : k.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase()));
+    // Escala de texto global: todo font-size numérico se multiplica aquí.
+    const val = typeof v === 'number' ? r2(k === 'fontSize' ? v * ctx.textScale : v) : v;
+    s += ` ${name}="${esc(val)}"`;
+  }
+  if (children === undefined || children === null || children === '') return s + '/>';
+  const inner = Array.isArray(children) ? children.flat(Infinity).filter(Boolean).join('') : children;
+  return s + '>' + inner + '</' + tag + '>';
+}
+
+export const g = (attrs, children) => el('g', attrs, children);
+
+/** Texto SVG. `children` se escapa. */
+export function text(x, y, str, attrs = {}) {
+  return el('text', { x, y, ...attrs }, esc(str));
+}
+
+/**
+ * Barra con extremo de dato redondeado (4px) y base recta.
+ * dir: hacia dónde crece la barra: 'up' | 'down' | 'right' | 'left'.
+ */
+export function barPath(x, y, w, h, dir = 'up', radius = 4) {
+  if (w <= 0 || h <= 0) return '';
+  const r = Math.max(0, Math.min(radius, (dir === 'up' || dir === 'down' ? w : h) / 2, dir === 'up' || dir === 'down' ? h : w));
+  const R = r2;
+  const x1 = x + w, y1 = y + h;
+  if (r === 0) return `M${R(x)},${R(y)}H${R(x1)}V${R(y1)}H${R(x)}Z`;
+  switch (dir) {
+    case 'up':
+      return `M${R(x)},${R(y1)}V${R(y + r)}Q${R(x)},${R(y)} ${R(x + r)},${R(y)}H${R(x1 - r)}Q${R(x1)},${R(y)} ${R(x1)},${R(y + r)}V${R(y1)}Z`;
+    case 'down':
+      return `M${R(x)},${R(y)}V${R(y1 - r)}Q${R(x)},${R(y1)} ${R(x + r)},${R(y1)}H${R(x1 - r)}Q${R(x1)},${R(y1)} ${R(x1)},${R(y1 - r)}V${R(y)}Z`;
+    case 'right':
+      return `M${R(x)},${R(y)}H${R(x1 - r)}Q${R(x1)},${R(y)} ${R(x1)},${R(y + r)}V${R(y1 - r)}Q${R(x1)},${R(y1)} ${R(x1 - r)},${R(y1)}H${R(x)}Z`;
+    case 'left':
+      return `M${R(x1)},${R(y)}H${R(x + r)}Q${R(x)},${R(y)} ${R(x)},${R(y + r)}V${R(y1 - r)}Q${R(x)},${R(y1)} ${R(x + r)},${R(y1)}H${R(x1)}Z`;
+    default:
+      return `M${R(x)},${R(y)}H${R(x1)}V${R(y1)}H${R(x)}Z`;
+  }
+}
+
+/** Texto de tooltip: líneas unidas por \n en un atributo data-tip. */
+export const tip = (...lines) => lines.filter((l) => l !== undefined && l !== null && l !== '').join('\n');
+
+/**
+ * Capa de puntos. Con pocos puntos, un <circle> por punto (tooltip propio).
+ * Con muchos (> threshold), un solo <path> por estilo —los círculos como
+ * arcos— y una capa invisible que busca el punto más cercano al pasar el
+ * mouse. Es tan rápido como Canvas y conserva lo vectorial (ver docs).
+ */
+export function dotLayer(circles, { threshold = 1500, maxTips = 20000 } = {}) {
+  if (circles.length <= threshold) return circles.map((c) => el('circle', c)).join('');
+  const groups = new Map();
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  const near = [];
+  for (const c of circles) {
+    const k = [c.fill, c.fillOpacity, c.r, c.stroke, c.strokeWidth].join('|');
+    if (!groups.has(k)) groups.set(k, { attrs: c, d: [] });
+    const r = +c.r, cx = +c.cx, cy = +c.cy;
+    groups.get(k).d.push(`M${r2(cx - r)},${r2(cy)}a${r},${r} 0 1,0 ${r2(2 * r)},0a${r},${r} 0 1,0 ${r2(-2 * r)},0`);
+    x0 = Math.min(x0, cx - r); y0 = Math.min(y0, cy - r); x1 = Math.max(x1, cx + r); y1 = Math.max(y1, cy + r);
+    if (near.length < maxTips) near.push([r2(cx), r2(cy), c['data-tip'] || '', c.fill]);
+  }
+  const paths = [...groups.values()].map(({ attrs, d }) =>
+    el('path', { d: d.join(''), fill: attrs.fill, fillOpacity: attrs.fillOpacity, stroke: attrs.stroke && attrs.stroke !== 'none' ? attrs.stroke : null, strokeWidth: attrs.stroke && attrs.stroke !== 'none' ? Math.min(+attrs.strokeWidth || 1, 0.75) : null }));
+  const hover = el('rect', { class: 'pa-near', x: x0, y: y0, width: Math.max(1, x1 - x0), height: Math.max(1, y1 - y0), fill: 'transparent', 'data-near': JSON.stringify(near) });
+  return g({ class: 'pa-dense' }, [...paths, hover]);
+}

package/src/text.js

@@ -0,0 +1,61 @@
+// Medición aproximada de texto sin DOM (Node, workers, SSR).
+// Calibrada para sans humanistas (Mozilla Text, Inter, system-ui).
+// Respeta la escala de texto global (textScale): el layout se calcula con el
+// tamaño real con que se dibuja el texto.
+import { ctx } from './context.js';
+
+const W = {};
+const set = (chars, w) => { for (const c of chars) W[c] = w; };
+set('abcdeghknopqsuvxyzáéóúñü', 0.54);
+set('ijlíï', 0.25);
+set('frt', 0.36);
+set('mw', 0.82);
+set('ABCDEFGHKNOPQRSTUVXYZÁÉÍÓÚÑ', 0.64);
+set('IJ', 0.3);
+set('MW', 0.86);
+set('0123456789', 0.56);
+set(' ', 0.27);
+set('.,:;\'!|', 0.26);
+set('-–()[]/', 0.36);
+set('%', 0.82);
+set('$€', 0.58);
+set('+=<>±×', 0.58);
+set('—', 0.9);
+set('▲▼■●', 0.9);
+set('·', 0.3);
+set('→', 0.9);
+
+export function measure(str, size = 12, weight = 400) {
+  let w = 0;
+  for (const c of String(str ?? '')) w += W[c] ?? 0.56;
+  const bold = weight >= 600 ? 1.06 : weight >= 500 ? 1.03 : 1;
+  return w * size * ctx.textScale * bold * 1.05; // margen: Mozilla Text es un poco más ancha
+}
+
+/** Recorta con elipsis para caber en `max` px. */
+export function truncate(str, max, size = 12, weight = 400) {
+  str = String(str ?? '');
+  if (measure(str, size, weight) <= max) return str;
+  let s = str;
+  while (s.length > 1 && measure(s + '…', size, weight) > max) s = s.slice(0, -1);
+  return s.trimEnd() + '…';
+}
+
+/** Ajusta texto en líneas de ancho `max`. Devuelve un arreglo de líneas. */
+export function wrap(str, max, size = 12, weight = 400, maxLines = Infinity) {
+  const words = String(str ?? '').split(/\s+/).filter(Boolean);
+  const lines = [];
+  let cur = '';
+  for (const w of words) {
+    const next = cur ? cur + ' ' + w : w;
+    if (measure(next, size, weight) <= max || !cur) cur = next;
+    else { lines.push(cur); cur = w; }
+  }
+  if (cur) lines.push(cur);
+  if (lines.length > maxLines) {
+    const kept = lines.slice(0, maxLines);
+    kept[maxLines - 1] = truncate(lines.slice(maxLines - 1).join(' '), max, size, weight);
+    return kept;
+  }
+  return lines;
+}