plotagents 0.5.0 → 0.8.0

package/docs/es/colorscales.md

@@ -0,0 +1,46 @@
+# Escalas de color
+
+Todos los mapas de colores que trae matplotlib están disponibles por nombre, además de los tuyos. Úsalos en cualquier gráfico que asigne un color a un número: mapas de calor, coropletas, mapas de puntos, treemaps coloreados por cambio y nubes de palabras.
+
+```js
+plot({ type: 'heatmap', data, x: 'hour', y: 'day', value: 'trips', colorScale: 'viridis' });
+plot({ type: 'choropleth', geo: 'chile', data, key: 'region', value: 'change', colorScale: 'RdBu' });
+plot({ ...spec, colorScale: 'magma_r' });                       // _r reverses any map
+plot({ ...spec, colorScale: ['#FFF7EC', '#FC8D59', '#7F0000'] }); // your own stops
+plot({ ...spec, colorScale: { name: 'coolwarm', mid: 100 } });    // diverging around 100
+```
+
+- **Los nombres no distinguen mayúsculas** (`'rdbu'` funciona) y `_r` invierte cualquier mapa.
+- **Los mapas divergentes se centran solos**: en 0 cuando los datos cruzan el cero; si no, en el punto medio de los datos. Fija `mid` (o `midpoint`) para elegir el centro.
+- **Tu propia escala** es una lista de dos o más colores, repartidos de forma pareja de menor a mayor, o `{ colors, reverse, mid }`.
+- La interpolación ocurre en OKLab, así que los pasos se ven parejos. Las paradas se muestrearon de matplotlib 3.9 y quedan a menos de 2 ΔE (×100) del original.
+- `cmap` y `colormap` son alias de `colorScale`. La opción anterior `ramp` todavía funciona.
+
+## Paletas categóricas
+
+`palette` acepta una lista de colores, una paleta de plotagents o uno de los mapas cualitativos de matplotlib:
+
+```js
+plot({ ...spec, palette: 'tab10' });
+plot({ ...spec, palette: 'Set2' });
+plot({ ...spec, palette: 'viridis' });   // a continuous map, sampled into distinct colors
+```
+
+La paleta por defecto está validada para deficiencias de visión del color; `lint` revisa cualquier otra paleta que traigas (consulta [Temas](themes.md#validating-a-palette)).
+
+## ¿Cuál usar?
+
+| Datos | Usa | Evita |
+|---|---|---|
+| Valores ordenados, de menor → mayor | `viridis`, `cividis`, `magma`, `Blues`, `YlGnBu` | `jet`, `rainbow`, `hsv` (inventan bordes donde los datos no los tienen) |
+| Valores en torno a un centro con significado (0, una meta, un promedio) | `RdBu`, `coolwarm`, `PuOr`, `BrBG` | un mapa secuencial |
+| Ángulos, horas del día, meses | `twilight`, `hsv` | un mapa secuencial |
+| Categorías | `palette: 'tab10'`, `'Set2'`, `'Dark2'` | cualquier mapa continuo como `colorScale` |
+
+`lint` marca los mapas arcoíris con una sugerencia y rechaza un mapa cualitativo usado como escala continua.
+
+## Todas las escalas
+
+{{colorscales}}
+
+La lista también está disponible en código: `colorScaleNames()` devuelve los nombres agrupados por tipo y `resolveColorScale(name)` devuelve `{ name, stops, kind }`.

package/docs/es/dashboards.md

@@ -0,0 +1,79 @@
+# Dashboards
+
+`dashboard(spec)` convierte un puñado de especificaciones de gráficos en un dashboard HTML terminado y autocontenido. Igual que en un gráfico individual, las decisiones de diseño vienen incluidas: tú dices qué va en la página y la biblioteca decide dónde y cómo.
+
+```js
+import { dashboard } from 'plotagents';
+import { writeFileSync } from 'node:fs';
+
+writeFileSync('sales.html', dashboard({
+  title: 'How are southern sales doing?',
+  subtitle: 'Sales by month, region and channel, 2024–2025, CLP millions',
+  source: 'Commercial ERP',
+  updated: '2026-01-05',
+  locale: 'en',
+  data: sales,                              // shared rows
+  kpis: [
+    { label: 'Sales 2025', field: 'sales', agg: 'sum', format: 'compact',
+      compare: { field: 'year', current: 2025, previous: 2024 }, trendBy: 'month' },
+    { label: 'Orders 2025', field: 'orders', agg: 'sum', format: 'compact',
+      compare: { field: 'year', current: 2025, previous: 2024 } },
+    { label: 'Online share', value: 0.361, delta: 0.13, format: 'percent', period: 'vs 2024' },
+  ],
+  filters: ['region', 'channel'],
+  charts: [
+    { type: 'line', x: 'month', y: 'sales', series: 'region', highlight: 'Ñuble',
+      title: 'Ñuble grew 37% this year, faster than any other region' },
+    { type: 'choropleth', geo: 'chile', key: 'region', value: 'sales', fitTo: ['Biobío', 'Ñuble', 'Maule', 'Araucanía'],
+      title: 'Biobío makes 36% of sales' },
+    { type: 'bar', x: 'channel', y: 'sales', series: 'year',
+      title: 'Online is the only channel growing strongly' },
+    { type: 'treemap', path: ['region', 'channel'], value: 'sales',
+      title: 'Physical stores are still half the business' },
+  ],
+}));
+```
+
+La página funciona sin JavaScript: cada gráfico se dibuja en el servidor, así que se abre en cualquier navegador, se imprime y se convierte a PDF. Cuando la versión para navegador está disponible (lo está, en Node), la página también recibe tooltips, ampliación de mapas y filtros en vivo. En una aplicación web, `renderDashboard('#board', spec)` dibuja el mismo dashboard dentro de un elemento.
+
+## Lo que decide por ti
+
+Estos valores por defecto vienen de la práctica del diseño de dashboards: *Information Dashboard Design* de Stephen Few, el patrón de lectura en Z y lo que hace difíciles de leer los dashboards de negocio.
+
+| Regla | Lo que hace plotagents |
+|---|---|
+| **Una pregunta por dashboard** | El `title` es la pregunta ("¿Cómo van las ventas del sur?"). `lintDashboard` advierte sobre 9 gráficos y sugiere dividir sobre 6. |
+| **Primero los números** | Los KPI van en una fila arriba, como máximo 5 (advertencia sobre eso). Cada uno tiene una etiqueta, la cifra, su cambio con una flecha **y** un signo (nunca solo color), el período de comparación y una minilínea opcional. |
+| **Lectura en Z** | El gráfico principal va justo después de los KPI, a todo el ancho: el marcado con `primary: true` o, si no, la primera serie de tiempo. |
+| **Filas completas, sin huecos** | Una cuadrícula de 12 columnas en filas equilibradas: 2 gráficos → 6 + 6 (8 + 4 cuando uno es ancho), 3 → 4 + 4 + 4, 4 → dos filas de dos, 5 → 3 + 2. Los paneles de una fila comparten la altura. |
+| **El ancho sigue al gráfico** | Las series de tiempo, las cartas Gantt, los mapas de calor y los flujos se leen de izquierda a derecha, así que reciben paneles anchos. Las donas, los KPI y los rankings cortos reciben paneles angostos. El mapa de Chile recibe una columna angosta. |
+| **Lo mismo, del mismo color** | Un solo mapa de colores para todos los gráficos: "Ñuble" tiene el mismo color en la línea, el treemap y las barras. `colors` fija colores para toda la página. |
+| **Una sola voz** | Un tema, un idioma y una tipografía para todos los paneles. La fuente aparece una vez, abajo; un gráfico conserva su propia fuente solo cuando es distinta. |
+| **Filtros como botones** | `filters` se convierten en botones cuando un campo tiene hasta 6 valores, y en una lista desplegable cuando tiene más. Filtran todos los gráficos que tienen el campo, recalculan los KPI y dicen qué está filtrado en cada subtítulo. Un filtro sobre el campo `time` de un gráfico lleva ese gráfico al período elegido. |
+| **Teléfonos** | Una columna en orden de lectura; los KPI en dos columnas. |
+| **Impresión** | Los paneles no se cortan entre páginas; la barra de filtros no queda fija en papel. |
+
+## Especificación
+
+| Opción | Significado |
+|---|---|
+| `title`, `subtitle` | La pregunta y el alcance (medida, unidad, período). |
+| `source`, `updated`, `note` | Metadatos del pie y del encabezado. |
+| `locale`, `theme`, `font`, `palette` | Se aplican a todos los gráficos (`theme: "noche"` para un dashboard oscuro). |
+| `data` | Filas compartidas. Los gráficos sin `data` las usan; los KPI calculados y los filtros trabajan sobre ellas. |
+| `kpis` | `[{ label, value, delta, period, trend, good, format }]` (fijos) o `[{ label, field, agg, over, scale, compare, trendBy, format }]` (calculados). `agg`: `sum`, `mean`, `median`, `min`, `max`, `count`, `distinct`, `ratio` (con `over`). `compare: { field, current, previous }` muestra el período actual y su cambio. `trendBy: "month"` dibuja la minilínea. |
+| `charts` | Especificaciones de gráficos, como en `plot()`. Por gráfico: `primary: true`, `size: "full" \| "large" \| "medium" \| "small"` o `span` (de 12). |
+| `filters` | `["region"]` o `[{ field, label, control: "buttons" \| "select", value }]`. |
+| `layout` | `"auto"` (por defecto), `"executive"` (gráfico principal a todo el ancho y luego pares) o `"grid"` (paneles iguales). |
+| `colors` | `{ "Biobío": "#3A47B8" }` para todos los gráficos. |
+
+## Para agentes
+
+```js
+import { safeDashboard, toolDefinition } from 'plotagents';
+
+const tool = toolDefinition({ kind: 'dashboard' });   // JSON Schema of the dashboard spec
+const { ok, html, errors, warnings, suggestions } = safeDashboard(input);
+```
+
+`safeDashboard` nunca lanza errores. Revisa el dashboard como un todo (demasiados gráficos o KPI, varios gráficos de torta, temas mezclados, filtros sobre campos que ningún gráfico tiene, paneles sin título) y cada gráfico que contiene, y etiqueta cada problema con el número y el título del gráfico para que el modelo sepa cuál corregir. `planDashboard(spec)` devuelve las decisiones de diseño (paneles, anchos, filas, colores, filtros) sin dibujar nada.

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/docs/getting-started.md

@@ -5,10 +5,14 @@ plotagents turns one JSON object into a finished, accessible SVG chart. You pass
 ## Install
 
 ```bash
-npm install github:carlosnavarreteliz/plotagents
+npm install plotagents
 ```
 
-plotagents is not on the npm registry yet, so install it from GitHub for now. Once it is published, `npm install plotagents` will work too. After installing, `npx plotagents` runs the CLI from your project.
+Or straight from GitHub, for the latest unreleased changes:
+
+```bash
+npm install github:carlosnavarreteliz/plotagents
+```
 
 Node 18 or later, Deno and Bun work out of the box. The package has no dependencies.
 

package/docs/themes.md

@@ -15,7 +15,34 @@ plot({ ...spec, ramp: 'teal' });                            // shortcut for them
 configure({ font: 'Poppins', textScale: 1.4, theme: { extends: 'papel', marks: { lineWidth: 2.5 } } });
 ```
 
-Every later `plot()`, `render()` and `toHTML()` starts from these values; the spec always wins. `configure()` returns the current defaults and `configure(null)` clears them.
+Every later `plot()`, `render()`, `toHTML()` and dashboard starts from these values; the spec always wins. A spec's own `theme` object is deep-merged **over** the global theme, so `configure({ theme: 'noche' })` plus `theme: { marks: { barRadius: 0 } }` stays dark. `configure()` returns the current defaults and `configure(null)` clears them.
+
+## Your own theme, everywhere
+
+The default theme (`papel`) never changes unless you ask. To restyle every chart, register a theme once and make it the default:
+
+```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'` also works per chart, and `{ extends: 'acme', … }` builds on it. Colors are validated: anything that is not a CSS color (hex, `rgb()`, `hsl()` or a color name) is dropped and the base value is kept.
 
 ## Built-in themes
 
@@ -30,17 +57,20 @@ Both share the same eight hues, stepped separately for each surface and validate
 
 | Key | Type | Meaning |
 |---|---|---|
-| `extends` | `'papel' \| 'noche'` | Base to merge over (default `papel`, or `noche` when `mode: 'dark'`). |
+| `extends` | theme name or object | Base to merge over (default `papel`, or `noche` when `mode: 'dark'`). |
 | `mode` | `'light' \| 'dark'` | Affects tooltips and text-on-fill contrast. |
-| `surface` | color | Chart background. Also used for 2 px gaps and rings around marks. |
-| `ink`, `lede`, `muted` | color | Primary text, secondary text, axis and source text. |
-| `grid`, `axis` | color | Gridlines and baselines (1 px, solid). |
+| `surface` (alias `background`) | color | Chart background. Also used for 2 px gaps and rings around marks. |
+| `ink` (alias `text`), `lede`, `muted` | color | Primary text, secondary text, axis and source text. |
+| `grid` | color or `{ color, dash, width }` | Gridlines (default 1 px, solid). `dash: '2 3'` draws dotted gridlines. |
+| `axis` | color or `{ color, width }` | Baselines. |
+| `tooltip` | `{ bg, ink }` | Tooltip card colors in the browser (default: white card on light themes, navy on dark). |
+| `radius`, `barRadius` | number | Corner radius of bars (default 4). `radius` sets it for every mark that has corners. |
 | `tint`, `tint2` | color | Quiet fills: KPI tiles, slider tracks, meters. |
 | `dim` | color | Muted marks when `highlight` is used. |
 | `other` | color | The "Other" bucket and series past the 8th. |
-| `categorical` | colors or palette name | Identity colors, assigned in this order. |
-| `sequential` | colors or ramp name | Light → dark, for heatmaps. |
-| `diverging` | colors or ramp name | Two poles with a neutral midpoint. |
+| `categorical` | colors, palette or colormap name | Identity colors, assigned in this order. |
+| `sequential` | colors, ramp or colormap name | Light → dark, for heatmaps and maps. |
+| `diverging` | colors, ramp or colormap name | Two poles with a neutral midpoint. |
 | `status` | `{ good, warning, critical }` | KPI deltas and meters. Never used for series. |
 | `font` | `{ family, mono, import }` | Font stack and optional Google Fonts URL (`fontImport: true` embeds it in the SVG). |
 | `type` | `{ title, subtitle, label, axis, legend, source, titleWeight }` | Type sizes in px. Titles shrink automatically on narrow widths. |
@@ -52,7 +82,7 @@ Both share the same eight hues, stepped separately for each surface and validate
 
 | Palettes (`categorical`) | Ramps (`sequential` / `diverging`) |
 |---|---|
-| `cdia` (default), `cdia-noche`, `okabe-ito`, `tableau10`, `udec` | `indigo`, `magenta`, `teal`, `amber`, `indigo-magenta`, `teal-rust` |
+| `cdia` (default), `cdia-noche`, `okabe-ito`, `tableau10`, `udec`, plus matplotlib's `tab10`, `tab20`, `tab20b`, `tab20c`, `Set1`, `Set2`, `Set3`, `Pastel1`, `Pastel2`, `Paired`, `Accent`, `Dark2` | `indigo`, `magenta`, `teal`, `amber`, `indigo-magenta`, `teal-rust`, plus every matplotlib colormap (see [Color scales](colorscales.md)) |
 
 ## Validating a palette