plotagents 0.7.0 → 0.8.0

package/docs/es/getting-started.md

@@ -0,0 +1,142 @@
+# Primeros pasos
+
+plotagents convierte un objeto JSON en un gráfico SVG terminado y accesible. Tú pasas filas de datos y nombras los campos; la biblioteca toma todas las decisiones de diseño: disposición del gráfico, colores, etiquetas, formatos numéricos y espaciado.
+
+## Instalación
+
+```bash
+npm install plotagents
+```
+
+O directo desde GitHub, para tener los últimos cambios aún no publicados:
+
+```bash
+npm install github:carlosnavarreteliz/plotagents
+```
+
+Funciona tal cual en Node 18 o superior, Deno y Bun. El paquete no tiene dependencias.
+
+## Tu primer gráfico
+
+```js
+import { plot } from 'plotagents';
+
+const svg = plot({
+  type: 'bar',
+  title: 'Biobío accounts for 30% of southern sales',
+  subtitle: 'Sales by region, CLP millions, 2025',
+  source: 'illustrative data',
+  data: [
+    { region: 'Biobío', sales: 1240 },
+    { region: 'Araucanía', sales: 880 },
+    { region: 'Ñuble', sales: 610 },
+  ],
+  x: 'region',
+  y: 'sales',
+  locale: 'en',
+});
+```
+
+`svg` es una cadena de texto. Guárdala en un archivo `.svg`, ponla en HTML o Markdown, o conviértela a PDF o PNG con cualquier herramienta de SVG.
+
+## Anatomía de un spec
+
+| Campo | Qué es |
+|---|---|
+| `type` | El tipo de gráfico, como `bar`, `line` o `treemap`. Omítelo para que se infiera de los datos. |
+| `data` | Una lista de filas: `[{ region: "Biobío", sales: 1240 }]`. |
+| `x`, `y`, `series` | Qué campo va en cada lugar. Cada tipo de gráfico documenta sus propios roles en la [referencia de gráficos](charts.md). |
+| `title` | El hallazgo, como una oración completa con la cifra clave. |
+| `subtitle` | Cómo leer el gráfico: medida, unidad y período. |
+| `source` | De dónde vienen los datos. Usa `"illustrative data"` cuando sean inventados. |
+| `locale` | `"es"` (el valor por defecto, `1.234,5`) o `"en"` (`1,234.5`). |
+
+### Tablas anchas
+
+Cuando cada medida está en su propia columna, pasa una lista en `y` y cada campo se convierte en una serie:
+
+```js
+plot({
+  type: 'line',
+  data: [
+    { month: '2025-01', revenue: 120, costs: 90 },
+    { month: '2025-02', revenue: 132, costs: 94 },
+  ],
+  x: 'month',
+  y: ['revenue', 'costs'],
+});
+```
+
+### Números escritos como texto
+
+Valores como `"1.234,5"`, `"12%"` o `"$ 3.000"` se interpretan automáticamente, así que los datos copiados desde una planilla funcionan sin limpiarlos.
+
+## En el navegador
+
+Sin un bundler, carga la versión para navegador y llama a `render()`. Dibuja dentro de un elemento y agrega tooltips, ancho adaptable, deslizadores de tiempo y drill-down.
+
+```html
+<div id="chart"></div>
+<script src="https://cdn.jsdelivr.net/gh/carlosnavarreteliz/plotagents@master/dist/plotagents.js"></script>
+<script>
+  plotagents.render('#chart', {
+    type: 'line',
+    data: [
+      { month: '2025-01', sales: 120 },
+      { month: '2025-02', sales: 140 },
+      { month: '2025-03', sales: 135 },
+    ],
+    x: 'month',
+    y: 'sales',
+    title: 'Sales rose 12% in the first quarter',
+    locale: 'en',
+  });
+</script>
+```
+
+El mismo archivo viene en el paquete como `dist/plotagents.js`. Los mapas también necesitan las geometrías: agrega `dist/plotagents-geo.js` después de `plotagents.js`.
+
+`render()` devuelve un controlador con `update(spec)`, para volver a dibujar con un spec nuevo, y `destroy()`, para quitar el gráfico y sus listeners.
+
+## Un informe completo en un archivo
+
+`toHTML()` arma una página interactiva y autocontenida con la biblioteca incluida, así que funciona sin conexión y desde un archivo local.
+
+```js
+import { writeFileSync } from 'node:fs';
+import { toHTML } from 'plotagents';
+
+writeFileSync('report.html', toHTML([spec1, spec2], { title: 'Monthly report', lang: 'en', columns: 2 }));
+```
+
+## Desde la línea de comandos
+
+```bash
+npx plotagents spec.json -o chart.svg       # SVG
+npx plotagents specs.json -o report.html    # several interactive charts on one page
+npx plotagents spec.json --lint             # review and suggestions
+npx plotagents spec.json --describe         # alt text
+npx plotagents --tool                       # tool definition for an agent
+```
+
+La CLI también lee un spec desde la entrada estándar: `cat spec.json | npx plotagents > chart.svg`.
+
+## Detectar errores
+
+`plot()` lanza un `PlotError` con una pista cuando un spec no se puede dibujar. `safePlot()` nunca lanza excepciones, y `lint()` revisa un spec sin dibujarlo:
+
+```js
+import { safePlot } from 'plotagents';
+
+const { ok, svg, errors, warnings, suggestions } = safePlot(spec);
+if (!ok) console.log(errors.map((e) => `${e.message} → ${e.fix}`));
+```
+
+Cada error, advertencia y sugerencia trae un `fix` que dice qué cambiar.
+
+## Próximos pasos
+
+- Recorre la [galería](../examples/) para encontrar el gráfico que necesitas y copiar su código.
+- Prueba specs en vivo en el [playground](../playground/).
+- Lee la [referencia de gráficos](charts.md) para conocer cada opción de cada tipo.
+- Entrégale a un agente la [guía para agentes](agents.md) y la definición de la herramienta.

package/docs/es/rendering.md

@@ -0,0 +1,47 @@
+# Renderizado: ¿SVG o Canvas?
+
+**Decisión: SVG en todas partes, con agrupación automática de trazados para marcas densas.** Evaluamos Canvas y lo descartamos: el SVG agrupado es más rápido que Canvas en todos los tamaños que probamos y conserva las propiedades que importan en una biblioteca que usan agentes.
+
+## Qué medimos
+
+Gráfico de dispersión, dos colores, 720 × 420 px, Chromium (Playwright), tiempo desde que se inserta el marcado hasta el segundo cuadro de animación. Misma máquina, mismos datos.
+
+| Puntos | SVG, un `<circle>` por punto | Canvas 2D (`arc` + `fill`) | SVG, un `<path>` por color | plotagents (SVG agrupado, gráfico completo) |
+|---|---|---|---|---|
+| 1.000 | 32 ms | 29 ms | 22 ms | 26 ms |
+| 5.000 | 62 ms | 30 ms | 13 ms | 12 ms |
+| 20.000 | 671 ms · 2,9 MB | 100 ms | 37 ms | 38 ms · 2,1 MB |
+| 50.000 | 1.468 ms · 7,2 MB | 357 ms | 138 ms | 123 ms · 3,4 MB |
+
+El costo del SVG ingenuo es el DOM: un elemento por marca. Dibujar todos los círculos de un color como arcos dentro de un solo `<path>` elimina ese costo, y el navegador rasteriza un trazado más rápido de lo que un script puede emitir decenas de miles de llamadas a Canvas.
+
+Reprodúcelo con `node scripts/bench.js` (necesita Playwright con Chromium instalado).
+
+## Por qué SVG gana en esta biblioteca
+
+| Necesidad | SVG | Canvas |
+|---|---|---|
+| Renderizar en un servidor, en Node, sin dependencias | Sí: el SVG es una cadena de texto | Necesita un módulo nativo (`node-canvas`) o un navegador headless |
+| Que un agente pueda leer y revisar lo que generó | Sí: títulos, etiquetas y valores son texto | No: es un mapa de bits |
+| Accesibilidad (`<title>`, `<desc>`, lectores de pantalla, selección de texto) | Incluida | Hay que reconstruirla a mano junto al canvas |
+| Nitidez con cualquier zoom, en impresión y en PDF | Vectorial | Resolución fija; hay que volver a renderizar para cada densidad de píxeles |
+| Pegar en diapositivas, Word, Figma, Markdown o correo | Funciona como archivo | Solo como imagen |
+| Temas con CSS, modo oscuro, estados al pasar el cursor | Clases CSS | Redibujo manual |
+| 50.000 puntos o más | Rápido con agrupación (ver arriba) | Rápido |
+
+Canvas solo gana cuando un gráfico necesita redibujar cientos de miles de marcas en cada cuadro, como en transmisiones en vivo o campos de partículas animados. Eso está fuera de lo que necesita un gráfico para tomar decisiones, y mucho más allá del punto en que un mapa de calor o un gráfico de densidad (`kde`, `hist`) cuenta la historia mejor que puntos superpuestos.
+
+## Cómo funciona la agrupación
+
+`dotLayer()` en `src/svg.js` recibe los círculos que un gráfico quiere dibujar:
+
+- **Hasta 1.500 puntos:** un `<circle>` por punto, cada uno con su propio tooltip y estado al pasar el cursor.
+- **Más de 1.500 puntos:** los círculos se agrupan por estilo (color, radio, opacidad) y cada grupo se convierte en un `<path>` de arcos. Un `<rect class="pa-near">` transparente lleva las coordenadas y el texto del tooltip de hasta 20.000 puntos, y la capa del navegador busca el punto más cercano dentro de 14 px al pasar el cursor y lo marca con un anillo.
+
+Scatter, bubble, regplot, residplot, jointplot, strip y swarm la usan automáticamente. No hace falta ninguna opción.
+
+## Otras decisiones de rendimiento
+
+- **Medición de texto sin DOM.** Tablas de anchos calibradas para tipografías sans humanistas permiten ajustar, partir y truncar las etiquetas de la misma forma en Node y en el navegador.
+- **Números redondeados a dos decimales** en todas las coordenadas, para que los archivos sean livianos.
+- **Un solo archivo para el navegador.** `toHTML()` incrusta `dist/plotagents.js` (sin dependencias), así que las páginas interactivas funcionan sin conexión, desde un archivo local o dentro de un artifact.

package/docs/es/themes.md

@@ -0,0 +1,116 @@
+# Temas
+
+Un tema es un objeto JSON. Pasa un nombre o un objeto; los objetos se combinan en profundidad sobre un tema base, así que solo escribes lo que cambia.
+
+```js
+plot({ ...spec, theme: 'noche' });                         // built-in dark theme
+plot({ ...spec, theme: { extends: 'noche', marks: { lineWidth: 3 } } });
+plot({ ...spec, palette: 'okabe-ito' });                    // shortcut for theme.categorical
+plot({ ...spec, ramp: 'teal' });                            // shortcut for theme.sequential
+```
+
+## Valores por defecto de toda la biblioteca
+
+```js
+configure({ font: 'Poppins', textScale: 1.4, theme: { extends: 'papel', marks: { lineWidth: 2.5 } } });
+```
+
+Cada `plot()`, `render()`, `toHTML()` y dashboard posterior parte de estos valores; la especificación siempre manda. El objeto `theme` propio de una especificación se combina en profundidad **sobre** el tema global, así que `configure({ theme: 'noche' })` más `theme: { marks: { barRadius: 0 } }` sigue siendo oscuro. `configure()` devuelve los valores por defecto actuales y `configure(null)` los borra.
+
+## Tu propio tema, en todas partes
+
+El tema por defecto (`papel`) nunca cambia a menos que lo pidas. Para cambiar el estilo de todos los gráficos, registra un tema una vez y déjalo como predeterminado:
+
+```js
+import { registerTheme, configure } from 'plotagents';
+
+registerTheme('acme', {
+  extends: 'papel',              // or 'noche', or another registered theme
+  background: '#FFFFFF',         // alias of surface
+  text: '#111827',               // alias of ink
+  lede: '#4B5563',
+  muted: '#6B7280',
+  grid: { color: '#EEF0F4', dash: '2 3', width: 1 },
+  axis: '#C7CBD6',
+  categorical: 'tab10',          // any palette or matplotlib qualitative map
+  sequential: 'viridis',         // any colormap name
+  tooltip: { bg: '#111827', ink: '#FFFFFF' },
+  radius: 2,                     // bar, tile and swatch corners
+  font: 'Inter',                 // Google Fonts name or CSS stack
+});
+
+configure({ theme: 'acme' });
+```
+
+`theme: 'acme'` también funciona en cada gráfico, y `{ extends: 'acme', … }` se construye sobre él. Los colores se validan: todo lo que no sea un color CSS (hex, `rgb()`, `hsl()` o un nombre de color) se descarta y se mantiene el valor base.
+
+## Temas incluidos
+
+| Nombre | Modo | Superficie | Uso |
+|---|---|---|---|
+| `papel` (alias `light`) | claro | `#FCFBF9` papel | por defecto |
+| `noche` (alias `dark`) | oscuro | `#0B0F2B` azul marino profundo | páginas oscuras, presentaciones |
+
+Ambos comparten los mismos ocho tonos, escalonados por separado para cada superficie y validados sobre ella.
+
+## Claves
+
+| Clave | Tipo | Significado |
+|---|---|---|
+| `extends` | nombre u objeto de tema | Base sobre la que se combina (por defecto `papel`, o `noche` cuando `mode: 'dark'`). |
+| `mode` | `'light' \| 'dark'` | Afecta los tooltips y el contraste del texto sobre rellenos. |
+| `surface` (alias `background`) | color | Fondo del gráfico. También se usa en las separaciones de 2 px y en los anillos alrededor de las marcas. |
+| `ink` (alias `text`), `lede`, `muted` | color | Texto principal, texto secundario, texto de ejes y de la fuente. |
+| `grid` | color o `{ color, dash, width }` | Líneas de cuadrícula (por defecto 1 px, continuas). `dash: '2 3'` dibuja líneas de cuadrícula punteadas. |
+| `axis` | color o `{ color, width }` | Líneas base. |
+| `tooltip` | `{ bg, ink }` | Colores de la tarjeta del tooltip en el navegador (por defecto: tarjeta blanca en temas claros, azul marino en oscuros). |
+| `radius`, `barRadius` | número | Radio de las esquinas de las barras (por defecto 4). `radius` lo fija para todas las marcas que tienen esquinas. |
+| `tint`, `tint2` | color | Rellenos discretos: tarjetas KPI, rieles de deslizadores, medidores. |
+| `dim` | color | Marcas atenuadas cuando se usa `highlight`. |
+| `other` | color | El grupo "Otros" y las series desde la novena. |
+| `categorical` | colores, paleta o nombre de mapa de colores | Colores de identidad, asignados en este orden. |
+| `sequential` | colores, rampa o nombre de mapa de colores | De claro → oscuro, para mapas de calor y mapas. |
+| `diverging` | colores, rampa o nombre de mapa de colores | Dos polos con un punto medio neutro. |
+| `status` | `{ good, warning, critical }` | Deltas y medidores de KPI. Nunca se usa para series. |
+| `font` | `{ family, mono, import }` | Pila de fuentes y URL opcional de Google Fonts (`fontImport: true` la incrusta en el SVG). |
+| `type` | `{ title, subtitle, label, axis, legend, source, titleWeight }` | Tamaños de letra en px. Los títulos se achican de forma automática en anchos angostos. |
+| `marks` | `{ barRadius, barMax, barMaxH, lineWidth, pointRadius, gap, ring, areaOpacity, bandOpacity, dotOpacity }` | Geometría de las marcas. |
+| `axes` | `{ inside, grid }` | `inside: true` pone las etiquetas de y sobre sus líneas de cuadrícula, dentro del gráfico (más ancho para los datos). |
+| `layout` | `{ padding, paddingSmall }` | Margen exterior en anchos amplios y angostos. |
+
+## Paletas y rampas con nombre
+
+| Paletas (`categorical`) | Rampas (`sequential` / `diverging`) |
+|---|---|
+| `cdia` (por defecto), `cdia-noche`, `okabe-ito`, `tableau10`, `udec`, más las de matplotlib `tab10`, `tab20`, `tab20b`, `tab20c`, `Set1`, `Set2`, `Set3`, `Pastel1`, `Pastel2`, `Paired`, `Accent`, `Dark2` | `indigo`, `magenta`, `teal`, `amber`, `indigo-magenta`, `teal-rust`, más todos los mapas de colores de matplotlib (consulta [Escalas de color](colorscales.md)) |
+
+## Validar una paleta
+
+```js
+import { validatePalette } from 'plotagents';
+
+validatePalette(['#223C6A', '#E69B0A', '#D21428'], { mode: 'light', surface: '#FFFFFF', locale: 'en' });
+// { ok: false, checks: [
+//   { name: 'lightness', status: 'fail', detail: 'Outside the lightness band 0.43–0.77: #223C6A' }, … ] }
+```
+
+| Prueba | Umbral | Por qué |
+|---|---|---|
+| Banda de luminosidad | OKLCH L 0.43–0.77 (claro), 0.48–0.67 (oscuro) | Demasiado claro desaparece; demasiado oscuro se lee como texto. |
+| Croma mínimo | OKLCH C ≥ 0.10 | Por debajo, un tono se lee como gris. |
+| Separación para daltonismo | ΔE OKLab × 100 ≥ 8 entre vecinos, con protanopía y deuteranopía simuladas (Machado 2009) | Los vecinos deben seguir distinguiéndose con deficiencias de visión del color. |
+| Separación con visión normal | ΔE ≥ 15 | Los vecinos deben ser fáciles de distinguir para todos. |
+| Contraste con la superficie | ≥ 3:1, solo advertencia | Por debajo, las marcas necesitan etiquetas visibles. |
+
+Usa `pairs: 'all'` para diagramas de dispersión y mapas, donde dos colores cualesquiera pueden quedar uno al lado del otro. La paleta incluida pasa la prueba de todos los pares para sus tres primeros colores; por eso `lint` advierte sobre diagramas de dispersión con más de tres grupos.
+
+`lint(spec)` ejecuta esta validación de forma automática cada vez que una especificación trae su propia paleta. Los mensajes siguen `locale` (español por defecto, `'en'` para inglés).
+
+## El color sigue a la entidad
+
+Los colores se asignan a entidades, nunca a posiciones:
+
+- Con `time`, los colores se calculan sobre todos los períodos, así que un grupo mantiene su color mientras se mueve el deslizador aunque cambie su posición en el ranking.
+- Con `focus` (navegación en profundidad), el subárbol mantiene la familia de colores de su padre.
+- Con `facet`, todos los paneles comparten un mismo mapa de colores.
+- `colors: { "Copper": "#B5562E" }` fija cualquier entidad a un color.

package/index.d.ts

@@ -5,11 +5,40 @@ export type ChartType =
   | 'regplot' | 'residplot' | 'jointplot' | 'hist' | 'kde' | 'ecdf'
   | 'box' | 'violin' | 'strip' | 'swarm' | 'point' | 'radar'
   | 'treemap' | 'sunburst' | 'donut' | 'pie' | 'heatmap' | 'sankey' | 'kpi'
-  | 'network' | 'chord' | 'pyramid' | 'flowchart' | 'gantt' | 'wordcloud' | 'choropleth' | 'symbolmap' | 'pointmap'
+  | 'network' | 'chord' | 'pyramid' | 'flowchart' | 'gantt' | 'wordcloud' | 'choropleth' | 'symbolmap' | 'pointmap' | 'table' | 'corr' | 'pairplot'
   // Aliases (seaborn and others)
   | 'barplot' | 'countplot' | 'lineplot' | 'scatterplot' | 'histplot' | 'kdeplot' | 'ecdfplot'
   | 'lmplot' | 'boxplot' | 'violinplot' | 'stripplot' | 'swarmplot' | 'beeswarm' | 'pointplot' | 'spider'
-  | 'timeline' | 'roadmap' | 'schedule' | 'cronograma' | 'map' | 'mapa';
+  | 'timeline' | 'roadmap' | 'schedule' | 'cronograma' | 'map' | 'mapa' | 'tabla' | 'datatable'
+  | 'correlation' | 'corrplot' | 'clustermap' | 'pairs' | 'splom' | 'scattermatrix';
+
+export type Locale = 'es' | 'en' | 'pt' | 'fr' | 'de' | 'auto';
+
+/** table: one column. A bare field name infers everything. */
+export interface TableColumn {
+  field?: string;
+  label?: string;
+  /** Indicator. Inferred when omitted: bar on the main measure, delta on change fields, sparkline on lists of numbers, progress on 0–1 goals, badge on status words, check on booleans. */
+  type?: 'text' | 'number' | 'bar' | 'heat' | 'delta' | 'sparkline' | 'progress' | 'badge' | 'check' | 'date' | 'link' | 'rank';
+  format?: Format;
+  align?: 'left' | 'right' | 'center';
+  width?: number;
+  /** delta/progress: whether up is good (default) or down (costs). */
+  good?: 'up' | 'down';
+  /** progress: field or number to compare against. */
+  target?: string | number;
+  /** heat: matplotlib colormap or colors. */
+  colorScale?: string | string[] | { name?: string; colors?: string[]; reverse?: boolean; mid?: number };
+  /** Totals row for this column. */
+  total?: boolean | 'sum' | 'mean' | 'min' | 'max' | 'count';
+  /** Text: lines before truncating (default 2, 3 for long text). */
+  lines?: number;
+  /** link: field with the text shown instead of the URL. */
+  text?: string;
+  /** badge: { value: "#hex" }. */
+  colors?: Record<string, string>;
+  sortable?: boolean;
+}
 
 export type Row = Record<string, string | number | Date | null | undefined>;
 
@@ -165,7 +194,26 @@ export interface Spec {
   lowess?: boolean;
   logx?: boolean;
   annotate?: boolean;
+  /** jointplot: center plot. pairplot: "reg" adds a fit line to every scatter panel. */
   kind?: 'scatter' | 'reg';
+  /** corr/pairplot: numeric fields to relate (default: all numeric; pairplot: first 6). */
+  vars?: string[];
+  /** corr: "pearson" (default) or "spearman". */
+  method?: 'pearson' | 'spearman';
+  /** corr: "lower" (default) or "full" (default with `cluster`). */
+  triangle?: 'lower' | 'full' | boolean;
+  /** corr: hierarchical clustering order + dendrogram (clustermap). */
+  cluster?: boolean;
+  dendrogram?: boolean;
+  /** corr: grey out cells with p ≥ alpha. */
+  alpha?: number;
+  cellSize?: number;
+  /** pairplot: diagonal panels ("kde" by default with hue). */
+  diag?: 'hist' | 'kde';
+  /** pairplot: above the diagonal. */
+  upper?: 'corr' | 'scatter' | false;
+  corner?: boolean;
+  panelSize?: number;
   marginal?: 'hist' | 'kde';
   inner?: 'box' | 'quartiles' | 'points' | 'stick' | 'none';
   split?: boolean;
@@ -181,7 +229,7 @@ export interface Spec {
   colorScale?: ColorScale;
   cmap?: ColorScale;
   colormap?: ColorScale;
-  locale?: 'es' | 'en';
+  locale?: Locale;
   width?: number;
   height?: number;
   padding?: number;
@@ -299,7 +347,30 @@ export interface Spec {
   /** wordcloud: words field, or raw text to count. */
   text?: string | string[];
   textField?: string;
-  columns?: number;
+  /** facet/kpi: panels or tiles per row. table: the columns. */
+  columns?: number | Array<string | TableColumn>;
+  /** table: column to sort by (field or label). */
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+  /** table: rows per page (default: all up to 15, then 10). false shows every row. */
+  pageSize?: number | false;
+  page?: number;
+  /** table: keep rows containing these words (accent- and case-insensitive). */
+  query?: string;
+  /** table: browser search box (default: on above 20 rows). */
+  search?: boolean;
+  /** table: totals row. */
+  total?: boolean | 'sum' | 'mean' | 'min' | 'max' | Record<string, string | boolean>;
+  totalLabel?: string;
+  /** table: "#" column with the position. */
+  rank?: boolean;
+  /** table: one card per row. "auto" (default) when the columns do not fit. */
+  cards?: boolean | 'auto';
+  density?: 'compact' | 'normal' | 'comfortable';
+  striped?: boolean;
+  /** table: false disables the automatic data bar. */
+  bars?: boolean;
+  sortable?: boolean;
   [key: string]: unknown;
 }
 
@@ -330,15 +401,20 @@ export declare const schema: Record<string, unknown>;
 export declare function configure(options?: Partial<Spec> | null): Partial<Spec>;
 export interface DashboardSpec {
   title?: string; subtitle?: string; source?: string; updated?: string; note?: string;
-  locale?: 'es' | 'en'; theme?: Spec['theme']; font?: Spec['font']; palette?: string | string[];
+  locale?: Locale; theme?: Spec['theme']; font?: Spec['font']; palette?: string | string[];
   data?: Row[];
-  kpis?: Array<{ label: string; value?: number; delta?: number; period?: string; trend?: number[]; good?: 'up' | 'down'; format?: Format;
+  kpis?: Array<{ label: string; value?: number; delta?: number; period?: string; previous?: number; display?: string; trend?: number[]; good?: 'up' | 'down'; format?: Format;
     field?: string; agg?: 'sum' | 'mean' | 'median' | 'min' | 'max' | 'count' | 'distinct' | 'ratio'; over?: string; scale?: number;
     compare?: { field: string; current: string | number; previous: string | number }; trendBy?: string }>;
-  charts: Array<Spec & { primary?: boolean; size?: 'full' | 'large' | 'medium' | 'small'; span?: number }>;
+  /** Optional when there are `kpis`. */
+  charts?: Array<Spec & { primary?: boolean; size?: 'full' | 'large' | 'medium' | 'small'; span?: number }>;
   filters?: Array<string | { field: string; label?: string; control?: 'buttons' | 'select'; value?: string }>;
   layout?: 'auto' | 'executive' | 'grid';
   colors?: Record<string, string>;
+  /** "given" keeps the charts in the order written (otherwise the main time series goes first). */
+  order?: 'given';
+  ramp?: string | string[];
+  textScale?: number;
 }
 /** Self-contained HTML dashboard with best-practice layout, shared colors, KPIs and filters. */
 export declare function dashboard(spec: DashboardSpec): string;
@@ -347,10 +423,16 @@ export declare function safeDashboard(spec: DashboardSpec): { ok: boolean; html:
 export declare function lintDashboard(spec: DashboardSpec): { ok: boolean; errors: Issue[]; warnings: Issue[]; suggestions: Issue[] };
 export declare function planDashboard(spec: DashboardSpec): object;
 /** Browser: draws a dashboard into an element. */
+/** Browser: wires the filters and charts of a dashboard already in the DOM. */
+export declare function mountDashboard(root: Element, plan: object): { plan: object; update(): void; destroy(): void };
+export declare function packRows(spans: number[]): Array<Array<{ i: number; span: number }>>;
+export declare function balancedRows(spans: number[], hasPrimary?: boolean): Array<Array<{ i: number; span: number }>>;
 export declare function renderDashboard(target: string | Element, spec: DashboardSpec): { update(): void; destroy(): void };
 export declare const dashboardSchema: Record<string, unknown>;
 /** Raw text → [{ text, value }] word counts without stopwords. */
 export declare function countWords(text: string | string[], opts?: { minLength?: number; stopwords?: string[] }): { text: string; value: number }[];
+export declare function getGeo(geo: string | object, objectName?: string): object;
+export declare function registeredGeo(): string[];
 export declare function registerGeo(name: string, geo: object, aliases?: string[]): object;
 /** Any GeoJSON / TopoJSON shape → FeatureCollection. */
 export declare function toFeatureCollection(geo: object | object[], objectName?: string): object;
@@ -361,7 +443,7 @@ export declare const ramps: Record<string, string[]>;
 export declare function themeFor(spec: Spec): Theme;
 export declare function timeValues(spec: Spec): (string | number)[];
 export declare function validatePalette(colors: string[], opts?: { mode?: 'light' | 'dark'; surface?: string; pairs?: 'adjacent' | 'all' }): { ok: boolean; checks: { name: string; status: 'pass' | 'warn' | 'fail'; detail: string }[] };
-export declare function bundleSource(): string | null;
+export declare function bundleSource(file?: string): string | null;
 export declare function toolDefinition(opts?: { name?: string; flavor?: 'anthropic' | 'openai'; kind?: 'chart' | 'dashboard' }): Record<string, unknown>;
 export declare const themes: Record<'papel' | 'noche' | 'light' | 'dark', Theme> & Record<string, Theme>;
 export declare function getTheme(t?: Spec['theme']): Theme;
@@ -378,6 +460,8 @@ export declare const QUALITATIVE: Record<string, string>;
 export declare const TYPES: ChartType[];
 export declare function squarify<T extends { value: number }>(items: T[], x: number, y: number, w: number, h: number): (T & { x: number; y: number; w: number; h: number })[];
 export declare function makeFormat(fmt?: Format, locale?: string, values?: number[]): ((v: number) => string) & { type: string };
+/** Most likely language of some texts ('es' | 'en' | 'pt' | 'fr' | 'de'), or null. */
+export declare function detectLocale(texts: string | string[]): 'es' | 'en' | 'pt' | 'fr' | 'de' | null;
 export declare function formatNumber(v: number, decimals?: number, locale?: string, trim?: boolean): string;
 export declare function formatCompact(v: number, locale?: string, decimals?: number): string;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotagents",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The chart protocol for AI agents: one JSON spec in, a finished accessible SVG out. Bars, lines, Gantt charts, treemaps, sankeys, maps from any GeoJSON/TopoJSON, networks and seaborn-style plots. Zero dependencies.",
   "type": "module",
   "main": "./src/index.js",
@@ -25,6 +25,7 @@
     "src",
     "dist",
     "docs",
+    "skills",
     "bin",
     "index.d.ts",
     "schema.json",
@@ -38,7 +39,7 @@
     "bench": "node scripts/bench.js",
     "prepublishOnly": "node scripts/bundle.js && node --test test/*.test.js",
     "examples": "node examples/build.js",
-    "site": "node scripts/build-site.js",
+    "site": "node scripts/build-site.js && node scripts/build-site.js --lang es",
     "schema": "node -e \"import('./src/index.js').then(m=>process.stdout.write(JSON.stringify(m.schema,null,2)))\" > schema.json"
   },
   "keywords": [