plotagents 0.0.0-stage → 0.5.0

package/src/geo/projection.js

@@ -0,0 +1,152 @@
+// Proyecciones y trazado de GeoJSON a SVG (sin dependencias).
+// mercator (países alargados como Chile), equalEarth (mapamundi de áreas
+// iguales, Šavrič et al. 2018) y albersUsa (EE. UU. con Alaska, Hawái y
+// Puerto Rico en recuadros, como d3.geoAlbersUsa). fit() ajusta una
+// colección a un rectángulo.
+
+const RAD = Math.PI / 180;
+
+export function mercator() {
+  return ([lon, lat]) => {
+    const phi = Math.max(-85, Math.min(85, lat)) * RAD;
+    return [lon * RAD, -Math.log(Math.tan(Math.PI / 4 + phi / 2))];
+  };
+}
+
+const A1 = 1.340264, A2 = -0.081106, A3 = 0.000893, A4 = 0.003796, M = Math.sqrt(3) / 2;
+export function equalEarth() {
+  return ([lon, lat]) => {
+    const l = lon * RAD;
+    const th = Math.asin(M * Math.sin(lat * RAD));
+    const t2 = th * th, t6 = t2 * t2 * t2;
+    const x = (l * Math.cos(th)) / (M * (A1 + 3 * A2 * t2 + t6 * (7 * A3 + 9 * A4 * t2)));
+    const y = th * (A1 + A2 * t2 + t6 * (A3 + A4 * t2));
+    return [x, -y];
+  };
+}
+
+/**
+ * Cónica de áreas iguales (Albers) con rotación y centro, en escala unitaria:
+ * misma fórmula que d3.geoConicEqualArea. Devuelve [x, y] con y hacia abajo.
+ */
+function conic(rot, center, [p0, p1], k = 1, [tx, ty] = [0, 0]) {
+  const sy0 = Math.sin(p0 * RAD), n = (sy0 + Math.sin(p1 * RAD)) / 2;
+  const c = 1 + sy0 * (2 * n - sy0), r0 = Math.sqrt(c) / n;
+  const raw = (lon, lat) => {
+    let l = lon + rot;
+    l = ((((l + 180) % 360) + 360) % 360) - 180;
+    const r = Math.sqrt(Math.max(0, c - 2 * n * Math.sin(lat * RAD))) / n;
+    const a = l * RAD * n;
+    return [r * Math.sin(a), r0 - r * Math.cos(a)];
+  };
+  const [cx, cy] = raw(center[0], center[1]);
+  return (lon, lat) => { const [x, y] = raw(lon, lat); return [tx + k * (x - cx), ty - k * (y - cy)]; };
+}
+
+/**
+ * EE. UU. compuesto: 48 estados contiguos en Albers y recuadros para Alaska
+ * (a 0,35×), Hawái y Puerto Rico abajo, como en d3 / d3-composite-projections.
+ * Cada punto va al recuadro de su territorio (las geometrías no cruzan).
+ */
+export function albersUsa() {
+  const lower48 = conic(96, [-96.6, 38.7], [29.5, 45.5]);
+  const alaska = conic(154, [-156, 58.5], [55, 65], 0.35, [-0.307, 0.201]);
+  const hawaii = conic(157, [-160, 19.9], [8, 18], 1, [-0.205, 0.212]);
+  const puertoRico = conic(66, [-66, 18], [8, 18], 1, [0.35, 0.224]);
+  const which = ([lon, lat]) => (lat > 50 ? 'AK' : lat < 23 && lon < -150 ? 'HI' : lon > -68.5 && lon < -64 && lat < 19.5 ? 'PR' : null);
+  const P = { AK: alaska, HI: hawaii, PR: puertoRico };
+  const f = (p) => (P[which(p)] || lower48)(p[0], p[1]);
+  f.continuous = true; // sin corte en el antimeridiano: los recuadros ya son continuos
+  f.inset = which;
+  return f;
+}
+
+export const projections = { mercator, equalEarth, 'equal-earth': equalEarth, albersUsa, 'albers-usa': albersUsa, albers: albersUsa };
+
+/** Recorre todos los anillos de una geometría. */
+export function rings(geom) {
+  if (!geom) return [];
+  if (geom.type === 'Polygon') return geom.coordinates;
+  if (geom.type === 'MultiPolygon') return geom.coordinates.flat();
+  return [];
+}
+export function polygonsOf(geom) {
+  if (!geom) return [];
+  if (geom.type === 'Polygon') return [geom.coordinates];
+  if (geom.type === 'MultiPolygon') return geom.coordinates;
+  return [];
+}
+
+/**
+ * Proyección ajustada a [x0, y0, x1, y1] conservando la proporción.
+ * Devuelve una función lon/lat → [x, y] con .bounds (ancho/alto usados).
+ */
+export function fit(features, raw, [x0, y0, x1, y1], { align = 'center' } = {}) {
+  let bx0 = Infinity, by0 = Infinity, bx1 = -Infinity, by1 = -Infinity;
+  for (const f of features) for (const r of rings(f.geometry)) for (const p of r) {
+    const [x, y] = raw(p);
+    if (x < bx0) bx0 = x; if (x > bx1) bx1 = x; if (y < by0) by0 = y; if (y > by1) by1 = y;
+  }
+  const w = x1 - x0, h = y1 - y0;
+  const k = Math.min(w / (bx1 - bx0 || 1), h / (by1 - by0 || 1));
+  const mw = (bx1 - bx0) * k, mh = (by1 - by0) * k;
+  const ox = align === 'left' ? x0 : x0 + (w - mw) / 2;
+  const oy = y0 + (h - mh) / 2;
+  const proj = (p) => { const [x, y] = raw(p); return [ox + (x - bx0) * k, oy + (y - by0) * k]; };
+  proj.bounds = { x: ox, y: oy, w: mw, h: mh };
+  proj.continuous = !!raw.continuous;
+  proj.inset = raw.inset;
+  proj.aspect = (by1 - by0) / (bx1 - bx0 || 1);
+  return proj;
+}
+
+/** Proporción alto/ancho de la colección proyectada (para elegir el alto). */
+export function aspectOf(features, raw) {
+  let bx0 = Infinity, by0 = Infinity, bx1 = -Infinity, by1 = -Infinity;
+  for (const f of features) for (const r of rings(f.geometry)) for (const p of r) {
+    const [x, y] = raw(p);
+    if (x < bx0) bx0 = x; if (x > bx1) bx1 = x; if (y < by0) by0 = y; if (y > by1) by1 = y;
+  }
+  return (by1 - by0) / (bx1 - bx0 || 1);
+}
+
+const r1 = (v) => Math.round(v * 10) / 10;
+
+/**
+ * Geometría → atributo d de SVG. Los anillos que saltan más de 180° de
+ * longitud (antimeridiano) se cortan para no cruzar el mapa entero.
+ */
+export function pathD(geom, proj) {
+  let d = '';
+  const cut = !proj.continuous;
+  for (const ring of rings(geom)) {
+    let started = false, lastLon = null, lx = null, ly = null, n = 0;
+    for (const p of ring) {
+      if (cut && lastLon !== null && Math.abs(p[0] - lastLon) > 180) started = false;
+      lastLon = p[0];
+      const [x, y] = proj(p);
+      const X = r1(x), Y = r1(y);
+      if (started && X === lx && Y === ly) continue;
+      d += (started ? 'L' : 'M') + X + ',' + Y;
+      started = true; lx = X; ly = Y; n++;
+    }
+    if (n) d += 'Z';
+  }
+  return d;
+}
+
+/** Área (en px²) y centroide del polígono proyectado más grande. */
+export function centroid(geom, proj) {
+  let best = null;
+  for (const poly of polygonsOf(geom)) {
+    const pts = poly[0].map(proj);
+    let a = 0, cx = 0, cy = 0;
+    for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
+      const f = pts[j][0] * pts[i][1] - pts[i][0] * pts[j][1];
+      a += f; cx += (pts[j][0] + pts[i][0]) * f; cy += (pts[j][1] + pts[i][1]) * f;
+    }
+    a /= 2;
+    if (!best || Math.abs(a) > Math.abs(best.area)) best = { area: a, x: a ? cx / (6 * a) : pts[0][0], y: a ? cy / (6 * a) : pts[0][1] };
+  }
+  return best ? { x: best.x, y: best.y, area: Math.abs(best.area) } : { x: 0, y: 0, area: 0 };
+}

package/src/geo/registry.js

@@ -0,0 +1,31 @@
+// Registro de geometrías. El núcleo no trae mapas pesados: se registran al
+// importar 'plotagents/geo/chile', 'plotagents/geo/usa' o 'plotagents/geo/world', o se pasa un
+// GeoJSON propio en spec.geo.
+import { PlotError } from '../data.js';
+
+const REG = new Map();
+
+export function registerGeo(name, fc, aliases = []) {
+  if (!fc || fc.type !== 'FeatureCollection') throw new PlotError(`La geometría "${name}" debe ser un GeoJSON FeatureCollection.`);
+  for (const n of [name, ...aliases]) REG.set(String(n).toLowerCase(), fc);
+  return fc;
+}
+
+export function getGeo(geo) {
+  if (geo && typeof geo === 'object') {
+    if (geo.type === 'FeatureCollection') return geo;
+    if (geo.type === 'Feature') return { type: 'FeatureCollection', features: [geo] };
+    throw new PlotError('`geo` debe ser un nombre registrado o un GeoJSON FeatureCollection.');
+  }
+  const fc = REG.get(String(geo || '').toLowerCase());
+  if (!fc) {
+    const known = [...new Set(REG.keys())];
+    throw new PlotError(
+      `No hay una geometría registrada con el nombre "${geo}".`,
+      known.length ? `Disponibles: ${known.join(', ')}. O pasa un GeoJSON en \`geo\`.` : "Importa 'plotagents/geo/chile', 'plotagents/geo/usa' o 'plotagents/geo/world', o pasa un GeoJSON en `geo`."
+    );
+  }
+  return fc;
+}
+
+export const registeredGeo = () => [...new Set(REG.keys())];

package/src/geo/usa.js

@@ -0,0 +1,8 @@
+// Registra los 50 estados de EE. UU., DC y Puerto Rico como 'usa'
+// (alias 'us', 'eeuu', 'estados-unidos', 'united-states', 'states').
+import { registerGeo } from './registry.js';
+import estados, { attribution } from './data/usa-estados.js';
+
+registerGeo('usa', estados, ['us', 'eeuu', 'ee.uu.', 'estados-unidos', 'estados unidos', 'united-states', 'united states', 'states', 'us-states']);
+export { estados, attribution };
+export default estados;

package/src/geo/world.js

@@ -0,0 +1,7 @@
+// Registra los países del mundo (Natural Earth 1:110m) como 'world' (alias 'mundo').
+import { registerGeo } from './registry.js';
+import world, { attribution } from './data/world.js';
+
+registerGeo('world', world, ['mundo', 'countries', 'paises', 'países']);
+export { world, attribution };
+export default world;

package/src/hierarchy.js

@@ -0,0 +1,139 @@
+// Jerarquías para treemap y sunburst: filas planas + campos de ruta → árbol
+// agregado, ordenado de mayor a menor. También colores por familia, foco
+// (drill-down) y migas de pan.
+import { ensureData, requireField, num, fieldsOf, fieldKind, PlotError } from './data.js';
+import { hexToRgb, rgbToHex } from './theme.js';
+import { formatNumber } from './format.js';
+import { el, g, text } from './svg.js';
+import { measure, truncate } from './text.js';
+
+/** Resuelve los campos de ruta y valor desde el spec (path | group+label | label | x). */
+export function hierarchyFields(spec, data) {
+  const fields = fieldsOf(data);
+  const cats = fields.filter((f) => fieldKind(data, f) === 'category');
+  let path = spec.path ? [].concat(spec.path) : null;
+  if (!path) {
+    const leaf = spec.label ?? spec.x;
+    path = spec.group ? [spec.group, leaf ?? cats.find((f) => f !== spec.group)] : [leaf ?? cats[0]];
+  }
+  path = path.filter(Boolean);
+  const value = spec.value ?? spec.y ?? (typeof spec.size === 'string' ? spec.size : null) ?? fields.find((f) => fieldKind(data, f) === 'number');
+  if (!path.length) throw new PlotError('No encontré un campo de categorías para la jerarquía.', 'Indica path: ["grupo", "elemento"] o label: "campo".');
+  path.forEach((p, i) => requireField(data, p, `path[${i}]`));
+  requireField(data, value, 'value');
+  return { path, value };
+}
+
+/**
+ * Construye el árbol. Nodo: { name, path, depth, value, children, parent }.
+ * `depth` (opcional) agrega todo bajo ese nivel.
+ */
+export function buildHierarchy(spec) {
+  const data = ensureData(spec);
+  const { path, value } = hierarchyFields(spec, data);
+  const levels = Math.max(1, Math.min(path.length, spec.depth ?? path.length));
+  const root = { name: '', path: [], depth: 0, value: 0, children: [], map: new Map() };
+  for (const r of data) {
+    const v = num(r[value]);
+    if (!(v > 0)) continue;
+    let node = root;
+    root.value += v;
+    for (let d = 0; d < levels; d++) {
+      const raw = r[path[d]];
+      const name = raw === null || raw === undefined || raw === '' ? '—' : String(raw);
+      if (!node.map.has(name)) {
+        const child = { name, path: [...node.path, name], depth: d + 1, value: 0, children: [], map: new Map(), parent: node };
+        node.map.set(name, child);
+        node.children.push(child);
+      }
+      node = node.map.get(name);
+      node.value += v;
+    }
+  }
+  const sortRec = (n) => { n.children.sort((a, b) => b.value - a.value); n.children.forEach(sortRec); delete n.map; };
+  sortRec(root);
+  return { root, fields: path.slice(0, levels), valueField: value, data };
+}
+
+/** Busca un nodo por ruta; si no existe, devuelve el más profundo que coincida. */
+export function findNode(root, focus = []) {
+  let node = root;
+  for (const name of focus || []) {
+    const next = node.children.find((c) => c.name === String(name));
+    if (!next) break;
+    node = next;
+  }
+  return node;
+}
+
+export const height = (n) => (n.children.length ? 1 + Math.max(...n.children.map(height)) : 0);
+export const descendants = (n) => [n, ...n.children.flatMap(descendants)];
+
+/** Mezcla un color hacia otro (t ∈ [0,1]). */
+export function mix(a, b, t) {
+  const A = hexToRgb(a), B = hexToRgb(b);
+  return rgbToHex(A.map((v, i) => v + (B[i] - v) * t));
+}
+
+/**
+ * Colores por familia: el primer nivel visible toma la paleta categórica en
+ * orden de tamaño (desde el 8.º, "Otros" en gris); los descendientes heredan
+ * el color con una variación de luminosidad sutil por hermano.
+ */
+export function assignColors(displayRoot, theme, spec, { single = false } = {}) {
+  const top = displayRoot.children;
+  const n = theme.categorical.length;
+  const fold = top.length > n;
+  top.forEach((c, i) => {
+    const fixed = spec.colors && spec.colors[c.name];
+    c.color = fixed || (single ? theme.categorical[0] : fold && i >= n - 1 ? theme.other : theme.categorical[i] || theme.other);
+    c.folded = !fixed && !single && fold && i >= n - 1;
+  });
+  const steps = [0, 0.14, 0.07, 0.2, 0.1];
+  const toward = theme.surface;
+  const rec = (node) => node.children.forEach((c, i) => {
+    // Color sólido por categoría completa (por defecto); `shade: true` vuelve a los tonos por hermano.
+    if (node !== displayRoot) c.color = (spec.colors && spec.colors[c.name]) || (spec.shade ? mix(node.color, toward, steps[i % steps.length]) : node.color);
+    rec(c);
+  });
+  rec(displayRoot);
+}
+
+export function shareFmt(locale) {
+  return (v, total) => {
+    const p = total > 0 ? (v / total) * 100 : 0;
+    return formatNumber(p, p < 1 ? 1 : p < 10 ? 1 : 0, locale, true) + '%';
+  };
+}
+
+export const SEP = ' › ';
+
+/**
+ * Migas de pan de foco: "Todo › Minería › Cobre". Cada miga lleva data-drill
+ * con la ruta de su ancestro (la raíz, "[]"). Devuelve { svg, h }.
+ */
+export function breadcrumb(focusNode, x, y, w, theme, locale = 'es') {
+  if (!focusNode || !focusNode.path.length) return { svg: '', h: 0 };
+  const en = String(locale).startsWith('en');
+  const crumbs = [{ name: en ? 'All' : 'Todo', path: [] }, ...focusNode.path.map((name, i) => ({ name, path: focusNode.path.slice(0, i + 1) }))];
+  const out = [];
+  let cx = x;
+  const size = 12.5;
+  crumbs.forEach((c, i) => {
+    const last = i === crumbs.length - 1;
+    const label = truncate(c.name, Math.max(60, w / crumbs.length), size, last ? 600 : 400);
+    const wLab = measure(label, size, last ? 600 : 400);
+    const attrs = { fill: last ? theme.ink : theme.lede, fontSize: size, fontWeight: last ? 600 : 400 };
+    if (last) out.push(text(cx, y + 13, label, attrs));
+    else out.push(g({ class: 'pa-crumb', 'data-drill': JSON.stringify(c.path), style: 'cursor:pointer' }, [
+      el('rect', { x: cx - 3, y, width: wLab + 6, height: 18, fill: 'transparent' }),
+      text(cx, y + 13, label, { ...attrs, textDecoration: 'underline', 'text-decoration-color': theme.axis }),
+    ]));
+    cx += wLab;
+    if (!last) {
+      out.push(text(cx + 6, y + 13, '›', { fill: theme.muted, fontSize: size }));
+      cx += 18;
+    }
+  });
+  return { svg: g({ class: 'pa-breadcrumb' }, out), h: 26 };
+}

package/src/index.js

@@ -0,0 +1,271 @@
+// plotagents · gráficos bellos con una sola llamada, pensados para agentes.
+//
+//   import { plot } from 'plotagents';
+//   const svg = plot({ data, x: 'region', y: 'ventas', title: 'Biobío lidera las ventas' });
+//
+import { getTheme, themeFor, themes, palettes, ramps, colorMap, fontSpec, FONT_CSS } from './theme.js';
+import { withContext } from './context.js';
+import { validatePalette } from './palette.js';
+import { bar } from './charts/bar.js';
+import { line } from './charts/line.js';
+import { scatter } from './charts/scatter.js';
+import { treemap, squarify } from './charts/treemap.js';
+import { donut, pie } from './charts/donut.js';
+import { sunburst } from './charts/sunburst.js';
+import { hist, kde, ecdf } from './charts/dist.js';
+import { regplot, residplot, jointplot } from './charts/regplot.js';
+import { box, violin, strip, swarm, point } from './charts/categorical.js';
+import { radar } from './charts/radar.js';
+import { network } from './charts/network.js';
+import { chord } from './charts/chord.js';
+import { pyramid } from './charts/pyramid.js';
+import { flowchart } from './charts/flowchart.js';
+import { choropleth, symbolMap } from './charts/choropleth.js';
+import { registerGeo, getGeo, registeredGeo } from './geo/registry.js';
+// Mapas incluidos (Chile por regiones, estados de EE. UU. y países del mundo): listos sin importar nada más.
+// El bundle del navegador los separa en dist/plotagents-geo.js.
+import './geo/chile.js';
+import './geo/world.js';
+import './geo/usa.js';
+import { heatmap } from './charts/heatmap.js';
+import { sankey } from './charts/sankey.js';
+import { kpi } from './charts/kpi.js';
+import { ensureData, PlotError, fieldKind, uniq, num } from './data.js';
+import { facet } from './facet.js';
+import { parseDate } from './format.js';
+import { inferType, TYPES, ALIASES, normalizeType } from './infer.js';
+import { lint, _setProbe } from './lint.js';
+import { schema, toolDefinition } from './schema.js';
+import { attach, attachSource } from './interact.js';
+import { render, _bind } from './runtime.js';
+import { makeFormat, formatNumber, formatCompact } from './format.js';
+import { esc } from './svg.js';
+
+const RENDERERS = {
+  bar: (s, t) => bar(s, t),
+  column: (s, t) => bar({ ...s, horizontal: false }, t),
+  count: (s, t) => bar({ aggregate: 'count', ...s }, t),
+  line: (s, t) => line(s, t, 'line'),
+  area: (s, t) => line(s, t, 'area'),
+  scatter: (s, t) => scatter(s, t),
+  bubble: (s, t) => scatter(s, t),
+  treemap: (s, t) => treemap(s, t),
+  sunburst: (s, t) => sunburst(s, t),
+  donut: (s, t) => donut(s, t),
+  pie: (s, t) => pie(s, t),
+  heatmap: (s, t) => heatmap(s, t),
+  sankey: (s, t) => sankey(s, t),
+  kpi: (s, t) => kpi(s, t),
+  hist: (s, t) => hist(s, t),
+  kde: (s, t) => kde(s, t),
+  ecdf: (s, t) => ecdf(s, t),
+  regplot: (s, t) => regplot(s, t),
+  residplot: (s, t) => residplot(s, t),
+  jointplot: (s, t) => jointplot(s, t),
+  box: (s, t) => box(s, t),
+  violin: (s, t) => violin(s, t),
+  strip: (s, t) => strip(s, t),
+  swarm: (s, t) => swarm(s, t),
+  point: (s, t) => point(s, t),
+  radar: (s, t) => radar(s, t),
+  network: (s, t) => network(s, t),
+  chord: (s, t) => chord(s, t),
+  pyramid: (s, t) => pyramid(s, t),
+  flowchart: (s, t) => flowchart(s, t),
+  choropleth: (s, t) => choropleth(s, t),
+  symbolmap: (s, t) => symbolMap(s, t),
+};
+
+
+
+/** Normaliza el spec: tipo inferido y datos como filas. */
+export function resolve(spec = {}) {
+  if (!spec || typeof spec !== 'object') throw new PlotError('El spec debe ser un objeto.', 'plot({ data: [...], x: "campo", y: "campo" })');
+  const s = withDefaults(spec);
+  if (s.color && !s.series && typeof s.color === 'string' && !s.color.startsWith('#')) s.series = s.color;
+  let type = s.type && s.type !== 'auto' ? String(s.type).toLowerCase() : null;
+  if (type) {
+    const [t, extra] = normalizeType(type);
+    type = t;
+    for (const [k, v] of Object.entries(extra)) if (s[k] === undefined) s[k] = v;
+  }
+  if (!type) {
+    const data = s.items ? [] : ensureData(s);
+    type = inferType(s, data);
+  }
+  if (!RENDERERS[type]) throw new PlotError(`Tipo de gráfico "${s.type}" no soportado.`, `Usa uno de: ${TYPES.join(', ')} o "auto".`);
+  s.type = type;
+  return s;
+}
+
+/**
+ * Dibuja un gráfico y devuelve un SVG (texto). Funciona en Node y navegador.
+ * Lanza PlotError con una pista de corrección si el spec no se puede dibujar.
+ */
+export function plot(spec) {
+  let s = resolve(spec);
+  s = applyTime(s);
+  const theme = themeFor(s);
+  const textScale = Math.max(0.5, Math.min(4, +(s.textScale ?? s.fontScale ?? s.labelScale ?? 1) || 1));
+  return withContext({ textScale }, () => {
+    if (s.facet || s.col) return facet(s, theme, (p) => RENDERERS[s.type](p, themeFor(p)));
+    return RENDERERS[s.type](s, theme);
+  });
+}
+
+// ── Configuración global ──────────────────────────────────────────────────
+const DEFAULTS = {};
+
+/**
+ * Valores por defecto para TODOS los gráficos (el spec siempre gana):
+ *   configure({ font: 'Poppins', textScale: 1.5, locale: 'en', theme: 'noche', palette: 'okabe-ito' })
+ * `font` acepta un nombre de Google Fonts, una pila CSS o { family, import }.
+ * `textScale` multiplica todos los textos (1.5, 2…) y el layout se recalcula.
+ * configure() sin argumentos devuelve la configuración actual; configure(null) la borra.
+ */
+export function configure(options) {
+  if (options === null) { for (const k of Object.keys(DEFAULTS)) delete DEFAULTS[k]; return {}; }
+  if (options) Object.assign(DEFAULTS, options);
+  return { ...DEFAULTS };
+}
+
+function withDefaults(spec) {
+  const s = { ...DEFAULTS, ...spec };
+  if (DEFAULTS.theme && typeof DEFAULTS.theme === 'object' && spec.theme && typeof spec.theme === 'object') s.theme = { ...DEFAULTS.theme, ...spec.theme };
+  // `font`: atajo de theme.font (familia + URL para cargarla).
+  const f = fontSpec(s.font);
+  if (f) {
+    const base = s.theme && typeof s.theme === 'object' ? s.theme : { extends: s.theme || undefined };
+    s.theme = { ...base, font: { ...(base.font || {}), ...f } };
+  }
+  return s;
+}
+
+const TIME_AXIS = new Set(['line', 'area', 'ecdf']);
+
+/** Valores ordenados del campo `time` (para sliders y animación). */
+export function timeValues(spec) {
+  const s = spec.type ? spec : resolve(spec);
+  if (!s.time) return [];
+  const data = ensureData(s);
+  const k = fieldKind(data, s.time);
+  const vals = uniq(data.map((r) => r[s.time]).filter((v) => v !== null && v !== undefined && v !== ''));
+  return vals.sort((a, b) => (k === 'date' ? parseDate(a) - parseDate(b) : k === 'year' || k === 'number' ? num(a) - num(b) : 0));
+}
+
+/**
+ * `time` (estilo d3plus): en gráficos que no tienen el tiempo en el eje x,
+ * muestra un solo periodo (`timeValue`, por defecto el último). El periodo se
+ * agrega a la bajada; en el navegador, render() suma un slider con "play".
+ */
+function applyTime(s) {
+  if (!s.time || TIME_AXIS.has(s.type) || s.x === s.time) return s;
+  const vals = timeValues(s);
+  if (!vals.length) return s;
+  const cur = s.timeValue ?? vals[vals.length - 1];
+  const all = ensureData(s);
+  const data = all.filter((r) => String(r[s.time]) === String(cur));
+  const label = String(cur);
+  // Periodo de comparación para variaciones (treemap y otros): el anterior, o el primero con compare: "first".
+  const idx = vals.findIndex((v) => String(v) === String(cur));
+  const pv = s.compare === 'first' ? vals[0] : s.compare !== undefined && s.compare !== 'previous' && s.compare !== false ? s.compare : vals[idx - 1];
+  const _prev = s.compare !== false && pv !== undefined && String(pv) !== String(cur) ? { data: all.filter((r) => String(r[s.time]) === String(pv)), label: String(pv) } : undefined;
+  return { ...s, data, colors: stableColors(s, all), subtitle: s.subtitle ? `${s.subtitle} · ${label}` : label, _time: { field: s.time, value: cur, values: vals }, _prev };
+}
+
+/**
+ * Colores fijos por entidad a lo largo de TODOS los periodos: al mover el
+ * slider, "Minería" sigue siendo índigo aunque cambie su tamaño o su orden.
+ */
+function stableColors(s, all) {
+  const idf = s.series ?? s.hue ?? (Array.isArray(s.path) ? s.path[0] : null) ?? s.group ?? s.from
+    ?? (['donut', 'pie'].includes(s.type) ? s.label ?? s.x : null);
+  if (!idf || !all.length || !(idf in all[0])) return s.colors;
+  const vf = s.value ?? (typeof s.y === 'string' ? s.y : null);
+  const tot = new Map();
+  for (const r of all) {
+    const k = String(r[idf]);
+    tot.set(k, (tot.get(k) || 0) + (vf && Number.isFinite(num(r[vf])) ? Math.abs(num(r[vf])) : 1));
+  }
+  const keys = [...tot.keys()].sort((a, b) => tot.get(b) - tot.get(a));
+  const cmap = colorMap(keys, themeFor(s), s.colors);
+  return { ...Object.fromEntries(cmap), ...(s.colors || {}) };
+}
+
+/**
+ * Versión que nunca lanza: ideal como herramienta de un agente.
+ * Devuelve { ok, svg, type, description, errors, warnings, suggestions }.
+ */
+export function safePlot(spec) {
+  const report = lint(spec || {});
+  try {
+    const svg = plot(spec);
+    return { ok: true, svg, type: report.type, description: describeSvg(svg), errors: [], warnings: report.warnings, suggestions: report.suggestions };
+  } catch (e) {
+    const errors = report.errors.length ? report.errors : [{ code: 'render', message: e.message.split('\n')[0], fix: e.hint }];
+    return { ok: false, svg: null, type: report.type, description: '', errors, warnings: report.warnings, suggestions: report.suggestions };
+  }
+}
+
+/** Descripción en texto del gráfico (también va en <desc> del SVG). */
+export function describe(spec) {
+  return describeSvg(plot(spec));
+}
+
+function describeSvg(svg) {
+  const m = /<desc[^>]*>([\s\S]*?)<\/desc>/.exec(svg);
+  return m ? m[1].replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'") : '';
+}
+
+/**
+ * Página HTML autónoma (un archivo) con uno o varios gráficos interactivos:
+ * tooltips, slider temporal y navegación por niveles. Incluye la biblioteca
+ * en línea (dist/plotagents.js) cuando está disponible; si no, solo tooltips.
+ */
+export function toHTML(specs, { title = 'Gráficos', lang = 'es', columns = 1 } = {}) {
+  const list = Array.isArray(specs) ? specs : [specs];
+  const dark = list.every((s) => themeFor(s).mode === 'dark');
+  const bg = dark ? '#0B0F2B' : '#FCFBF9';
+  const needsGeo = list.some((s) => { try { return ['choropleth', 'symbolmap'].includes(resolve(s).type); } catch { return false; } });
+  const bundle = bundleSource() && (needsGeo ? bundleSource() + '\n' + (bundleSource('plotagents-geo.js') || '') : bundleSource());
+  const safeJSON = (o) => JSON.stringify(o).replace(/</g, '\\u003c');
+  const charts = list.map((s, i) => `<figure class="pa" id="pa-${i}">${plot(s)}</figure>` + (bundle ? `<script type="application/json" id="pa-spec-${i}">${safeJSON(s)}</script>` : '')).join('\n');
+  const boot = bundle
+    ? `<script>${bundle.replace(/<\/(script)/gi, '<\\/$1')}</script>\n<script>document.querySelectorAll('figure.pa').forEach(function(f,i){var s=JSON.parse(document.getElementById('pa-spec-'+i).textContent);plotagents.render(f,s);});</script>`
+    : `<script>document.querySelectorAll('figure.pa').forEach(function(f){(${attachSource})(f)});</script>`;
+  return `<!doctype html>
+<html lang="${esc(lang)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(title)}</title>
+${[...new Set([FONT_CSS, ...list.map((s) => themeFor(withDefaults(s)).font?.import).filter(Boolean)])].map((u) => `<link rel="stylesheet" href="${esc(u)}">`).join('\n')}
+<style>
+:root{color-scheme:${dark ? 'dark' : 'light'}}
+body{margin:0;background:${bg};font-family:${esc(themeFor(withDefaults(list[0])).font?.family || "'Mozilla Text',system-ui,sans-serif")}}
+main{max-width:${columns > 1 ? 1500 : 820}px;margin:0 auto;padding:24px 16px;display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,${columns > 1 ? 560 : 320}px),1fr));gap:24px}
+figure.pa{margin:0;min-width:0}
+figure.pa svg{width:100%;height:auto;display:block}
+</style></head>
+<body><main>
+${charts}
+</main>
+${boot}
+</body></html>`;
+}
+
+/** Código de la biblioteca en un archivo (para incrustar en HTML). */
+export function bundleSource(file = 'plotagents.js') {
+  try {
+    const fs = globalThis.process?.getBuiltinModule?.('node:fs');
+    if (!fs) return null;
+    return fs.readFileSync(new URL('../dist/' + file, import.meta.url), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+_bind(plot, resolve);
+_setProbe((s) => plot(s));
+export { render };
+
+export { RENDERERS, ALIASES, registerGeo, getGeo, registeredGeo };
+export { lint, schema, toolDefinition, themes, palettes, ramps, validatePalette, getTheme, themeFor, attach, PlotError, TYPES, squarify, makeFormat, formatNumber, formatCompact };
+export default plot;

package/src/infer.js

@@ -0,0 +1,49 @@
+// Elige el tipo de gráfico cuando el agente no lo indica (type: "auto").
+import { fieldsOf, fieldKind } from './data.js';
+
+export const TYPES = ['bar', 'column', 'count', 'line', 'area', 'scatter', 'bubble', 'treemap', 'sunburst', 'donut', 'pie', 'heatmap', 'sankey', 'kpi', 'hist', 'kde', 'ecdf', 'regplot', 'residplot', 'jointplot', 'box', 'violin', 'strip', 'swarm', 'point', 'radar', 'network', 'chord', 'pyramid', 'flowchart', 'choropleth', 'symbolmap'];
+
+// Nombres de seaborn, d3plus y otros: el agente puede usar el que conozca.
+export const ALIASES = {
+  barplot: ['bar', { ci: true }], countplot: 'count', columns: 'column', lineplot: 'line', areaplot: 'area',
+  scatterplot: 'scatter', histplot: 'hist', histogram: 'hist', kdeplot: 'kde', density: 'kde', ecdfplot: 'ecdf',
+  lmplot: 'regplot', reg: 'regplot', regression: 'regplot', joint: 'jointplot', boxplot: 'box', violinplot: 'violin',
+  stripplot: 'strip', swarmplot: 'swarm', beeswarm: 'swarm', pointplot: 'point', spider: 'radar', doughnut: 'donut',
+  graph: 'network', force: 'network', red: 'network', 'chord-diagram': 'chord', cuerdas: 'chord',
+  populationpyramid: 'pyramid', population: 'pyramid', piramide: 'pyramid', 'pirámide': 'pyramid',
+  flow: 'flowchart', diagram: 'flowchart', process: 'flowchart', diagrama: 'flowchart',
+  map: 'choropleth', mapa: 'choropleth', choroplethmap: 'choropleth', symbol: 'symbolmap', bubblemap: 'symbolmap', 'mapa-simbolos': 'symbolmap',
+  tree: 'treemap', stat: 'kpi', stats: 'kpi', number: 'kpi', heat: 'heatmap', flow: 'sankey',
+};
+
+/** Tipo canónico + opciones implícitas del alias (p. ej. barplot → bar con ci). */
+export function normalizeType(t) {
+  const k = String(t || '').toLowerCase();
+  const al = ALIASES[k];
+  if (!al) return [k, {}];
+  return Array.isArray(al) ? [al[0], al[1]] : [al, {}];
+}
+
+export function inferType(spec, data = []) {
+  if (spec.items) return 'kpi';
+  if (spec.geo) return 'choropleth';
+  if (spec.nodes && spec.nodes.some?.((n) => n && n.type)) return 'flowchart';
+  if (spec.nodes) return 'network';
+  if (spec.matrix) return 'chord';
+  if (spec.from || spec.to) return 'sankey';
+  if (spec.path || spec.group) return 'treemap';
+  if (spec.size) return 'bubble';
+  const fields = fieldsOf(data);
+  if ((fields.includes('source') && fields.includes('target')) || (fields.includes('from') && fields.includes('to'))) return 'sankey';
+  const kinds = Object.fromEntries(fields.map((f) => [f, fieldKind(data, f)]));
+  const x = spec.x ?? fields[0];
+  const xk = kinds[x];
+  if (xk === 'date' || xk === 'year') return 'line';
+  if (xk === 'number') {
+    const y = spec.y ?? fields.find((f) => f !== x && kinds[f] === 'number');
+    if (y && kinds[y] === 'number') return 'scatter';
+  }
+  const cats = fields.filter((f) => kinds[f] === 'category');
+  if (cats.length >= 2 && !spec.series && fields.some((f) => kinds[f] === 'number') && spec.value) return 'heatmap';
+  return 'bar';
+}