plotagents 0.7.0 → 0.8.0

package/docs/charts.md

@@ -15,7 +15,7 @@ Every chart takes a spec with `data` (rows) plus field names for each role. The
 | `highlight` | One name or a list: emphasize these, mute the rest. |
 | `colors` | `{ "name": "#hex" }` to pin an entity's color. |
 | `format`, `xFormat`, `yFormat` | `"number" \| "compact" \| "percent" \| "currency" \| "integer"` or `{ prefix, suffix, decimals, currency }`. |
-| `locale` | `"es"` (default: `1.234,5`) or `"en"` (`1,234.5`). |
+| `locale` | `"es"` (default: `1.234,5`), `"en"` (`1,234.5`), `"pt"`, `"fr"` (`1 234,5`), `"de"`, or `"auto"`: recognized from the title, subtitle, column names and categories. Tables use `"auto"` when `locale` is omitted. |
 | `xLabel`, `yLabel` | Axis titles (horizontal, never rotated). |
 | `xScale`, `yScale` | `"log"` where it makes sense. |
 | `xDomain`, `yDomain` | Fixed `[min, max]`. |
@@ -134,6 +134,40 @@ plot({
 | `kind` | `jointplot`: `"scatter"` or `"reg"`. |
 | `marginal` | `jointplot`: `"hist"` or `"kde"`. |
 
+### `corr` (`correlation`, `corrplot`) · `clustermap`
+
+Correlation matrix of numeric fields, computed for you from the rows (pairwise complete cases, like `df.corr()`). Each pair appears once, below the diagonal, on a diverging scale fixed at −1 to 1, so the same color means the same strength in every chart. Long labels turn 45°. The tooltip gives r, n and the p-value.
+
+```js
+plot({ type: 'corr', data, vars: ['income', 'schooling', 'poverty', 'density'], alpha: 0.05,
+  title: 'Where schooling is higher, income is higher (r = 0.85) and poverty lower (r = −0.81)' });
+```
+
+| Option | Meaning |
+|---|---|
+| `vars` | Fields to relate, in order. Default: every numeric field. `y: [...]` works too. |
+| `method` | `"pearson"` (default) or `"spearman"` (ranks: monotonic relations, robust to outliers). |
+| `triangle` | `"lower"` (default) or `"full"`. |
+| `cluster` | Reorder by hierarchical clustering (average linkage on 1 − r) and draw the dendrogram on top. `type: "clustermap"` sets it and shows the full matrix; `dendrogram: false` keeps the order without the tree. |
+| `alpha` | Grey out pairs with p ≥ alpha (Fisher's z) and add a legend key. |
+| `order` | Variable order (list). |
+| `highlight` | One variable: its row and column stay, the rest fade. |
+| `labelsFor` | Display names, e.g. `{ areas_verdes: "Green space" }`. |
+| `x`, `y`, `value` | Draw a matrix you already computed, in long form (one row per pair). |
+
+### `pairplot` (`pairs`, `splom`, `scattermatrix`)
+
+Scatter-plot matrix: each pair as a scatter below the diagonal, each variable's distribution on it (histogram, or density with `hue`), and Pearson r above, tinted by strength and split by `hue` group when there is room. Axes are shared by column and row; tick labels sit only on the outer edges.
+
+| Option | Meaning |
+|---|---|
+| `vars` | Fields to plot (3–6 read best). Default: the first 6 numeric fields. |
+| `hue` | Color by group, with a legend. |
+| `diag` | `"hist"` or `"kde"`. |
+| `upper` | `"corr"` (default), `"scatter"` or `false`. `corner: true` keeps only the lower triangle. |
+| `kind` | `"reg"` adds a least-squares line to every scatter panel. |
+| `radius`, `bins`, `panelSize` | Point radius, histogram bins, maximum panel size. |
+
 ### `radar` (`spider`)
 
 Long data (`axis`, `value`, `series`) or wide data (`axes: [fields]`, one row per series with `label`). `normalize` scales each axis to its own maximum (tooltips keep raw values); `grid: "polygon" | "circle"`; `domain`. Best with ≤ 4 series.
@@ -350,3 +384,54 @@ A cloud is good at "what comes up most" and bad at "by how much". `lint` suggest
 ### `kpi`
 
 `items: [{ label, value, delta, previous, period, good: "up" | "down", trend: [...], target, format }]`. Delta is a fraction (`0.12` → +12%); `good: "down"` for costs. Tiles reflow into balanced rows.
+
+## Tables
+
+### `table` (`tabla`, `datatable`)
+
+For when the reader needs to look up the exact number. Thin rules between rows and nothing else; numbers right-aligned in tabular figures with the same decimals down each column; empty cells as a dash. Each column gets the indicator that explains it.
+
+```js
+plot({
+  type: 'table',
+  title: 'Two of six projects are already over budget',
+  data: projects,
+  columns: ['project', 'area',
+    { field: 'progress', type: 'progress' },
+    { field: 'spent', label: 'Spent / budget', type: 'progress', target: 'budget', good: 'down' },
+    'status'],
+  sortBy: 'progress',
+});
+```
+
+| Column `type` | Draws | Inferred when |
+|---|---|---|
+| `bar` | Value + data bar on a shared scale (diverging around 0) | The main numeric column (`value`/`y`, or the first number); `bars: false` turns it off |
+| `delta` | ▲ / ▼ + signed change, green or red by `good` (`"down"` for costs) | Field named var, change, delta, growth, yoy, cambio, variación… |
+| `heat` | Cell tinted by a sequential scale (diverging when it crosses 0); `colorScale` per column | — |
+| `sparkline` | Mini line, last point in the accent | The field holds lists of numbers |
+| `progress` | Percent + meter; against `target` (field or number) or as 0–1 / 0–100 | Field named progress, avance, completion…, or meta/target/goal with fractions |
+| `badge` | Status pill | Values are status words (done, at risk, late, in progress… in es/en/pt/fr/de): good, warning, critical, info colors |
+| `check` | ✓ or a dash, with an accessible label | Booleans, or sí/no, yes/no… |
+| `date` | Readable date in the chart's language | ISO dates |
+| `link` | Underlined link; only `http(s)` and `mailto` get an `href` | URLs |
+| `rank` | Position under the current sort | `rank: true` |
+| `text`, `number` | Text (wraps to 2–3 lines) and plain numbers | Everything else |
+
+| Option | Meaning |
+|---|---|
+| `columns` | Order and type: field names or `{ field, label, type, format, align, width, good, target, colorScale, total, lines }`. Omit to use every field. `x`/`label` picks the row-name column and `y` a list of value columns. |
+| `sortBy`, `sort` | Column and direction (`"desc"` for numbers, `"asc"` for text by default). `sort: "-sales"` works too. Empty cells always go last. |
+| `pageSize`, `page` | Up to 15 rows are shown whole; beyond that, pages of 10. `pageSize: false` shows everything. The pager is numbers and arrows only (`11–20 / 248`, `‹ 1 2 3 … 25 ›`). |
+| `query` | Keep rows that contain these words, ignoring accents and case. |
+| `total` | Totals row: sums numbers, averages percents and progress, leaves changes blank. `{ sales: "mean" }` per column; `totalLabel` renames it. |
+| `group` | Rows under a tinted band per value, with a count. |
+| `highlight` | Rows whose name matches get a tint and an accent mark; the bars of the other rows are muted. |
+| `top` | Keep the first N rows after sorting. |
+| `cards` | `"auto"` (default) turns each row into a card when the columns do not fit (phones): name and main value on top, the bar under them, the other columns as label–value lines. `true` always, `false` never. |
+| `density`, `striped` | `"compact"` / `"comfortable"` rows; zebra stripes for very wide tables. |
+
+In the browser `render()` adds a search box above 20 rows (`search: false` hides it; `true` forces it), click-to-sort headers (natural order, reversed, then the original order), and page buttons; all of them work from the keyboard and announce `aria-sort` and `aria-current`. Resizing re-renders at the new width, so a table becomes cards on a phone and columns again on a desktop.
+
+The language of the few words a table writes (Total, Search, No results) and the number format come from `locale`; without it, the table recognizes the language from its own title, headers and categories.
+

package/docs/es/agents.md

@@ -0,0 +1,102 @@
+# plotagents · guía para agentes de IA
+
+Una función, un objeto JSON. Sin decisiones de diseño: la biblioteca las toma por ti.
+
+```js
+import { plot, safePlot } from 'plotagents';
+const svg = plot({ type, data, x, y, series, title, subtitle, source });
+```
+
+## Reglas para un buen gráfico
+
+1. **`title` es el hallazgo**, una oración completa con la cifra clave: "Biobío concentra el 30% de las ventas", no "Ventas por región".
+2. **`subtitle` dice cómo leerlo**: medida, unidad y período.
+3. **Define siempre `source`.** Si los datos son inventados, usa `source: "illustrative data"`.
+4. `data` es una lista de filas (`[{ region: "Biobío", sales: 1240 }]`). Para una tabla ancha, pasa `y: ["revenue", "costs"]`.
+5. Usa `safePlot(spec)` como tu herramienta: nunca lanza excepciones y devuelve `errors`, `warnings` y `suggestions`, cada uno con un `fix`. Si `ok` es `false`, corrige el spec y vuelve a llamarla.
+6. Define `locale: "en"` para formatos numéricos en inglés (el valor por defecto es español: `1.234,5`); también hay `"pt"`, `"fr"`, `"de"` o `"auto"` para reconocerlo a partir del texto. Las tablas lo reconocen por sí solas.
+
+## Qué tipo usar
+
+| Para mostrar | `type` | Campos clave |
+|---|---|---|
+| Comparar categorías | `bar` | `x`, `y`, `series?`, `stack?` (`true` / `"percent"`), `top?` |
+| Contar filas por categoría | `countplot` | `x` |
+| Media por categoría con un IC | `barplot` o `point` | `x`, `y`, `hue?` |
+| Cambio en el tiempo | `line` | `x` fecha (`"2024-03"`) o año, `y`, `series?`; `ci: true` con varias observaciones por x |
+| Un plan de proyecto o un cronograma | `gantt` | `task`, `start`, `end` (o `duration`), `group?`, `progress?`, `dependsOn?`, `today?`, `collapsed?` |
+| Volumen en el tiempo | `area` | como `line`; se apila con `series` |
+| Medidas en escalas distintas | `line` + `index: true`, o `facet` | **no hay doble eje** |
+| Crecimiento exponencial | `line` + `yScale: "log"` | |
+| Relación entre dos medidas | `regplot` (ajuste + IC) / `scatter` / `bubble` | `x`, `y`, `hue?`, `size?`, `label?` |
+| Relación + marginales | `jointplot` | `x`, `y` |
+| Qué medidas se mueven juntas | `corr` (`correlation`) | `vars?` (por defecto: todos los campos numéricos), `method?` (`"spearman"`), `alpha?: 0.05`; `cluster: true` o `type: "clustermap"` las agrupa con un dendrograma |
+| Todos los pares de medidas a la vez | `pairplot` (`splom`) | `vars` (3–6), `hue?`, `corner?`, `kind?: "reg"` |
+| Distribución de una medida | `hist` (`kde: true`), `kde`, `ecdf` | `x`, `hue?` |
+| Distribución por categoría | `box`, `violin`, `strip`, `swarm` | `x` categoría, `y` medida, `hue?` |
+| Perfil multidimensional | `radar` | `axis`, `value`, `series` (≤ 4 series) |
+| Parte de un todo jerárquico | `treemap` o `sunburst` | `path: [level1, level2, …]`, `value` |
+| Parte de un todo, ≤ 6 partes | `donut` / `pie` | `label`, `value`; `half: true` para un semicírculo |
+| Magnitud en una grilla | `heatmap` | `x`, `y`, `value` |
+| Un valor por región, estado o país | `choropleth` (`symbolmap` para totales) | `geo: "chile" \| "usa" \| "world"` o cualquier objeto GeoJSON/TopoJSON, `key`, `value` (texto → un color por categoría) |
+| Puntos en lugares reales sobre un mapa de calles | `pointmap` | `lon`, `lat` (se detectan solos), `size?`, `hue?`, `value?`, `label?`; `tiles: "osm"` (por defecto) / `"esri-gray"` / `"esri-dark"`, o carto-* / mapbox-* con `tilesKey` |
+| Quién se conecta con quién | `network` | aristas `from`, `to`, `value?`; `nodes?` con `group`; `layout?` |
+| Intercambios entre pocos grupos | `chord` | `from`, `to`, `value` |
+| Estructura por edad | `pyramid` | `age`, `sex`, `value` |
+| Un proceso con decisiones | `flowchart` | `nodes` (`type`, `lane`), `edges` (`label`) |
+| Flujos entre etapas | `sankey` | `from`, `to`, `value` |
+| Una o más cifras | `kpi` | `items: [{ label, value, delta, period, trend, target, good }]` |
+| Valores exactos para consultar | `table` | `columns?: [field \| { field, type, label, format, good, target }]`, `sortBy?`, `total?`, `group?`; los tipos `bar`, `delta`, `heat`, `sparkline`, `progress`, `badge` y `check` se infieren cuando se omiten |
+| Lo que más aparece en un texto | `wordcloud` | `text` (campo o texto sin procesar), `value?`, `series?`; para comparar con exactitud, prefiere `bar` + `top` |
+
+Los nombres de seaborn funcionan (`histplot`, `kdeplot`, `boxplot`, `violinplot`, `lmplot`, `stripplot`, `swarmplot`, `pointplot`), y `hue` es un alias de `series`. Omite `type` para que se infiera de los datos.
+
+## Opciones más útiles
+
+- `highlight: "Ñuble"`: destaca una categoría o serie y atenúa el resto. `exclude: ["Maule"]` quita entradas y recalcula el gráfico; los colores no cambian.
+- `legend: "top" | "bottom" | "left" | "right" | false`: dónde va la leyenda (arriba por defecto).
+- `colorScale: "viridis"`: cualquier mapa de colores de matplotlib para mapas de calor, mapas y treemaps por variación (`"RdBu"` diverge en torno a 0; `_r` lo invierte; también sirve una lista de colores). `palette: "tab10"` para categorías.
+- `dashed` para lo que no es una cifra firme (estimaciones, proyecciones, cifras provisionales): un nombre, una lista o un campo de los datos (`dashed: "provisional"`). Las formas mantienen su color, con relleno achurado y contorno discontinuo. En un eje de tiempo, `dashedFrom: 2025` dibuja con trazo discontinuo las líneas, áreas y columnas desde ese año. **Define siempre `dashedLabel`** ("Proyección", "Preliminar") para que los lectores sepan qué significa el achurado.
+- `facet: "region"` (+ `columns`): un panel por valor, con una escala compartida.
+- `time: "year"`: un período a la vez (el más reciente) con la variación % respecto del anterior. Los controles de tiempo están **desactivados por defecto**: agrega `slider: true` solo cuando la persona pida recorrer los períodos (botones para ≤ 8 períodos y un deslizador mínimo en los demás casos; `"buttons"` / `"slider"` fuerzan uno de los dos, `play: false` oculta el botón de reproducir). Los treemaps se pueden colorear por variación con `colorBy: "change"`.
+- `refLines: [{ y: 600, label: "Target" }]` y `annotations: [{ x: "2024-01", label: "New branch" }]`.
+- `format: "percent" | "currency" | "compact" | "integer"` o `{ prefix, suffix, decimals }`.
+- `xScale` / `yScale: "log"`.
+- `table`: dale un título que enuncie el hallazgo, como a cualquier gráfico. Con más de 15 filas se pagina de a diez (`pageSize`), en teléfonos cada fila se muestra como una tarjeta y el navegador agrega orden, búsqueda y paginación. Usa `good: "down"` en los costos para que ▲ se vuelva rojo, `progress` con `target: "budget"` para el gasto frente al presupuesto y `total: true` para una fila de totales. Usa entre 4 y 7 columnas.
+- `theme: "noche"` o un objeto JSON (`{ extends, categorical, type, marks, font }`); `palette: [...]` para tus propios colores.
+- `font: "Poppins"` y `textScale: 1.5` (modo presentación); `configure({ font, textScale })` los define para todos los gráficos.
+- `network` + `focus: "node id"`: centra un nodo y destaca sus vecinos.
+- Tu propio mapa: `geo: <GeoJSON or TopoJSON>`; la propiedad que coincide se busca sola (`featureKey` para forzarla). Agrega `markers: [{ lon, lat, label }]`, `layers: [{ geo, label }]` para ríos o rutas, y `fitTo: ["Biobío"]` o una caja `[lonMin, latMin, lonMax, latMax]` para hacer zoom.
+- `gantt`: las fechas `end` por día son inclusivas; una fila sin `end` es un hito. Define siempre `today` en un plan en curso. `collapsed: ["Phase 2"]` (o `true`) pliega las fases en una barra resumen; en el navegador, un clic en una fase la abre o la cierra.
+- `network` + `layout: "force" | "circular" | "radial" | "concentric" | "clusters" | "tree" | "grid"` elige la disposición; `curveness: 0` endereza las aristas.
+- `pointmap` dibuja sobre teselas de OpenStreetMap por defecto (`tiles: "esri-gray"`, `"mapbox-light"` + `tilesKey`, o tus propias `{ url, attribution }`). Las teselas solo se cargan cuando el SVG va incrustado en la página o en `toHTML`, no dentro de `<img>`.
+- Tu propio estilo para todos los gráficos: `registerTheme("acme", { background, text, grid: { color, dash }, categorical: "tab10", font })` y luego `configure({ theme: "acme" })`.
+- `geo: "usa"`: los estados coinciden por código postal ("TX"), nombre en inglés o en español, o código FIPS ("48"). Alaska y Hawái aparecen en recuadros; Puerto Rico aparece solo cuando tus datos lo incluyen. En el navegador, los mapas hacen zoom con un clic, con Ctrl/⌘ + rueda o pellizcando.
+
+## Errores que la biblioteca ya resuelve
+
+- Más de 8 series → de la 9.ª en adelante se pintan en gris; `lint` sugiere `highlight` o `facet`.
+- Etiquetas de líneas que chocan → se separan con líneas guía.
+- Dona con más de 6 partes → el resto se agrupa en "Otros".
+- Etiquetas de categoría largas → el gráfico pasa a horizontal.
+- Paleta propia difícil de distinguir → `lint` nombra el par problemático.
+- Números como texto ("1.234,5", "12%", "$ 3.000") → se interpretan automáticamente.
+- Decenas de miles de puntos → se dibujan como trazados agrupados y sigue siendo rápido.
+
+## Tableros
+
+Cuando alguien pida un dashboard, llama a `safeDashboard({ title, subtitle, source, data, kpis, charts, filters })` (herramienta: `toolDefinition({ kind: 'dashboard' })`). La disposición, los anchos, los colores compartidos y los filtros se deciden por ti:
+
+- `title` es la **pregunta** que responde el tablero; cada gráfico igual lleva su hallazgo como título.
+- Como máximo **5 KPI**, calculados a partir de `data` cuando sea posible: `{ label, field, agg: "sum", compare: { field: "year", current: 2025, previous: 2024 }, trendBy: "month" }`.
+- **De 4 a 6 gráficos**. La primera serie de tiempo (o la que tenga `primary: true`) va a todo el ancho; el resto llena filas equilibradas.
+- `filters: ["region", "channel"]` se convierten en botones que filtran todos los gráficos y KPI.
+- No más de una dona; una sola `source` para la página.
+
+## Salidas
+
+- `plot(spec)` → cadena SVG. Insértala en HTML, Markdown, un archivo `.svg` o un PDF.
+- `toHTML([spec1, spec2])` → página autocontenida con tooltips, deslizadores y drill-down.
+- `describe(spec)` → texto alternativo del gráfico.
+- `schema` / `toolDefinition()` → JSON Schema y definición de herramienta (Anthropic u OpenAI).
+- CLI: `npx plotagents spec.json -o chart.svg`.

package/docs/es/api.md

@@ -0,0 +1,172 @@
+# Referencia de la API
+
+```js
+import {
+  plot, safePlot, lint, describe, render, toHTML, configure,
+  dashboard, safeDashboard, renderDashboard, lintDashboard, planDashboard,
+  schema, dashboardSchema, toolDefinition, validatePalette, registerGeo, countWords,
+} from 'plotagents';
+```
+
+Los tipos completos están en [`index.d.ts`](../index.d.ts) y cada opción del spec, en [`schema.json`](../schema.json).
+
+## Dibujo
+
+### `plot(spec)`
+
+Dibuja un gráfico y devuelve una cadena SVG. Funciona en Node, Deno, Bun y el navegador. Lanza un `PlotError` cuando el spec no se puede dibujar; el `hint` del error dice cómo corregirlo.
+
+```js
+const svg = plot({ type: 'bar', data, x: 'region', y: 'sales', title: 'Biobío leads with 30%' });
+```
+
+### `safePlot(spec)`
+
+La versión que debes exponer como herramienta de un agente: nunca lanza excepciones.
+
+```js
+const { ok, svg, type, description, errors, warnings, suggestions } = safePlot(spec);
+```
+
+| Campo | Significado |
+|---|---|
+| `ok` | `true` cuando el gráfico se dibujó. |
+| `svg` | La cadena SVG, o `null`. |
+| `type` | El tipo de gráfico resuelto (útil cuando `type` se infirió). |
+| `description` | Texto alternativo del gráfico. |
+| `errors` | Problemas que impiden dibujar el gráfico: `{ code, message, fix }`. |
+| `warnings` | Problemas que vuelven el gráfico engañoso o difícil de leer. |
+| `suggestions` | Mejoras de diseño, como un mejor título o `highlight`. |
+
+### `lint(spec)`
+
+Revisa un spec sin dibujarlo y devuelve `{ ok, type, errors, warnings, suggestions }`. Los mensajes siguen el `locale` del spec (español por defecto, inglés con `locale: "en"`); cada uno trae un `fix` con el cambio que hay que hacer.
+
+### `dashboard(spec)` · `safeDashboard(spec)` · `renderDashboard(el, spec)`
+
+Un dashboard HTML autocontenido con una disposición según buenas prácticas, colores compartidos, KPI y filtros. `safeDashboard` nunca lanza excepciones y devuelve `{ ok, html, plan, errors, warnings, suggestions }`; `renderDashboard` dibuja dentro de un elemento en el navegador; `lintDashboard` revisa; `planDashboard` devuelve las decisiones de disposición. Consulta [Tableros](dashboards.md).
+
+### `describe(spec)`
+
+Devuelve una descripción en texto del gráfico, como "Mayor: Biobío con 1.240 (30%)…". El mismo texto va en el `<desc>` del SVG para los lectores de pantalla.
+
+## En el navegador
+
+### `render(target, spec, opts?)`
+
+Dibuja dentro de un elemento (un selector CSS o un nodo del DOM) con tooltips, ancho adaptable, controles de tiempo cuando el spec los pide (`slider: true`), drill-down en treemaps y sunbursts, clic para enfocar en redes, fases plegables en Gantt y clics en la leyenda (shift + clic excluye una entrada; en treemaps y sunbursts, un clic hace zoom en la categoría).
+
+```js
+const chart = plotagents.render('#chart', spec);
+chart.update({ ...spec, highlight: 'Ñuble' });   // redraw
+chart.destroy();                                // remove listeners and markup
+```
+
+| Opción | Significado |
+|---|---|
+| `controls` | `false` oculta los controles de tiempo aunque el spec los pida (`slider: true`). |
+
+El controlador expone `svg` (el elemento `<svg>` actual) y `spec`.
+
+### `attach(root)`
+
+Agrega tooltips a un contenedor que ya tiene un SVG de plotagents, por ejemplo uno generado en el servidor.
+
+### `toHTML(specs, opts?)`
+
+Una página HTML autocontenida con uno o más gráficos interactivos y la biblioteca incluida.
+
+| Opción | Por defecto | Significado |
+|---|---|---|
+| `title` | `"Gráficos"` | Título de la página. |
+| `lang` | `"es"` | Idioma de la página. |
+| `columns` | `1` | Con dos o más, los gráficos se ordenan en una grilla. |
+
+## Configuración
+
+### `configure(options)`
+
+Define valores por defecto para todos los gráficos siguientes; el spec siempre tiene prioridad.
+
+```js
+configure({ font: 'Poppins', textScale: 1.5, locale: 'en' });
+configure();       // returns the current defaults
+configure(null);   // clears them
+```
+
+Acepta cualquier opción del spec: `font`, `textScale`, `locale`, `theme`, `palette`, `ramp`, `colorScale`, `legend`, etc. Si un spec trae su propio objeto `theme`, este se combina sobre el global.
+
+### `registerTheme(name, theme)`
+
+Registra un tema con nombre (combinado sobre `extends`, `papel` por defecto) para que `theme: name` y `configure({ theme: name })` puedan usarlo. Consulta [Temas](themes.md#your-own-theme-everywhere).
+
+```js
+registerTheme('acme', { background: '#FFF', text: '#111', categorical: 'tab10', grid: { dash: '2 3' } });
+configure({ theme: 'acme' });
+```
+
+### `colorScaleNames()` · `resolveColorScale(name)`
+
+Todos los nombres de escalas de color agrupados por tipo (`sequential`, `diverging`, `cyclic`, `qualitative`), y las paradas de una escala: `{ name, stops, kind }`. `interpolateColor(stops, t)` devuelve el color en `t ∈ [0, 1]` (OKLab).
+
+### `validatePalette(colors, opts?)`
+
+Revisa una paleta propia con las mismas pruebas que pasa la paleta incluida. Consulta [temas](themes.md#validating-a-palette).
+
+```js
+validatePalette(['#223C6A', '#E69B0A', '#D21428'], { mode: 'light', surface: '#FFFFFF' });
+// → { ok: false, checks: [{ name: 'lightness', status: 'fail', detail: '…' }, …] }
+```
+
+### `registerGeo(name, featureCollection, aliases?)`
+
+Registra tu propio GeoJSON para que los specs puedan usar `geo: name`. Chile y el mundo vienen incluidos.
+
+## Para agentes
+
+### `toolDefinition({ name?, flavor? })`
+
+Devuelve una definición de herramienta construida a partir del JSON Schema: `flavor: "anthropic"` (por defecto) entrega `{ name, description, input_schema }` y `flavor: "openai"` entrega `{ type: "function", function: { … } }`.
+
+```js
+import Anthropic from '@anthropic-ai/sdk';
+import { safePlot, toolDefinition } from 'plotagents';
+
+const client = new Anthropic();
+const res = await client.messages.create({
+  model: process.env.ANTHROPIC_MODEL,
+  max_tokens: 4096,
+  tools: [toolDefinition()],
+  messages: [{ role: 'user', content: 'Plot the distribution of service times per clinic: …' }],
+});
+const call = res.content.find((b) => b.type === 'tool_use');
+const { ok, svg, errors } = safePlot(call.input);
+// If !ok, send `errors` back as the tool_result: every error carries a `fix`.
+```
+
+### `schema`
+
+El JSON Schema de un spec, publicado también como [`schema.json`](../schema.json) e importable como `plotagents/schema.json`.
+
+## Utilidades
+
+| Exportación | Significado |
+|---|---|
+| `TYPES` | Todos los nombres de tipos de gráfico. |
+| `themes`, `getTheme(t)`, `themeFor(spec)` | Los temas incluidos y el tema resuelto de un spec. |
+| `palettes`, `ramps` | Paletas categóricas con nombre y rampas secuenciales y divergentes. |
+| `timeValues(spec)` | Valores ordenados del campo `time`. |
+| `makeFormat(fmt, locale, values)` | El formateador de números que usaría un gráfico. |
+| `formatNumber(v, decimals, locale)`, `formatCompact(v, locale)` | Formato de números según el idioma. |
+| `squarify(items, x, y, w, h)` | El algoritmo de disposición del treemap. |
+| `bundleSource()` | Solo en Node: la versión para navegador como cadena, para incrustarla. |
+
+## Puntos de entrada del paquete
+
+| Importación | Contenido |
+|---|---|
+| `plotagents` | Todo lo anterior (módulo ES). |
+| `plotagents/schema.json` | El JSON Schema. |
+| `plotagents/browser` | `dist/plotagents.js`: un `<script>` que define `window.plotagents`. |
+| `plotagents/browser/geo` | `dist/plotagents-geo.js`: geometrías de Chile y del mundo para la versión de navegador. |
+| `plotagents/geo/chile`, `plotagents/geo/world` | Las geometrías como módulos ES. |