plotagents 0.5.0 → 0.7.0

package/docs/api.md

@@ -3,7 +3,8 @@
 ```js
 import {
   plot, safePlot, lint, describe, render, toHTML, configure,
-  schema, toolDefinition, validatePalette, registerGeo,
+  dashboard, safeDashboard, renderDashboard, lintDashboard, planDashboard,
+  schema, dashboardSchema, toolDefinition, validatePalette, registerGeo, countWords,
 } from 'plotagents';
 ```
 
@@ -39,7 +40,11 @@ const { ok, svg, type, description, errors, warnings, suggestions } = safePlot(s
 
 ### `lint(spec)`
 
-Reviews a spec without drawing it and returns `{ ok, type, errors, warnings, suggestions }`. Messages are written in Spanish; each one carries a `fix` with the change to make.
+Reviews a spec without drawing it and returns `{ ok, type, errors, warnings, suggestions }`. Messages follow the spec's `locale` (Spanish by default, English with `locale: "en"`); each one carries a `fix` with the change to make.
+
+### `dashboard(spec)` · `safeDashboard(spec)` · `renderDashboard(el, spec)`
+
+A self-contained HTML dashboard with best-practice layout, shared colors, KPIs and filters. `safeDashboard` never throws and returns `{ ok, html, plan, errors, warnings, suggestions }`; `renderDashboard` draws into an element in the browser; `lintDashboard` reviews; `planDashboard` returns the layout decisions. See [Dashboards](dashboards.md).
 
 ### `describe(spec)`
 
@@ -49,7 +54,7 @@ Returns a text description of the chart, such as "Highest: Biobío with 1,240 (3
 
 ### `render(target, spec, opts?)`
 
-Draws into an element (a CSS selector or a DOM node) with tooltips, responsive width, time sliders, a range slider for time series, drill-down for treemaps and sunbursts, and click-to-focus for networks.
+Draws into an element (a CSS selector or a DOM node) with tooltips, responsive width, time controls when the spec asks for them (`slider: true`), drill-down for treemaps and sunbursts, click-to-focus for networks, collapsible Gantt phases, and legend clicks (shift + click excludes an entry; in treemaps and sunbursts a click zooms to the category).
 
 ```js
 const chart = plotagents.render('#chart', spec);
@@ -59,7 +64,7 @@ chart.destroy();                                // remove listeners and markup
 
 | Option | Meaning |
 |---|---|
-| `controls` | `false` hides sliders and play buttons. |
+| `controls` | `false` hides time controls even when the spec asks for them (`slider: true`). |
 
 The handle exposes `svg` (the current `<svg>` element) and `spec`.
 
@@ -89,7 +94,20 @@ configure();       // returns the current defaults
 configure(null);   // clears them
 ```
 
-It accepts any spec option: `font`, `textScale`, `locale`, `theme`, `palette`, `ramp` and so on.
+It accepts any spec option: `font`, `textScale`, `locale`, `theme`, `palette`, `ramp`, `colorScale`, `legend` and so on. A spec's own `theme` object is merged over the global one.
+
+### `registerTheme(name, theme)`
+
+Registers a named theme (merged over `extends`, `papel` by default) so `theme: name` and `configure({ theme: name })` can use it. See [Themes](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)`
+
+All color scale names grouped by kind (`sequential`, `diverging`, `cyclic`, `qualitative`), and the stops of one scale: `{ name, stops, kind }`. `interpolateColor(stops, t)` returns the color at `t ∈ [0, 1]` (OKLab).
 
 ### `validatePalette(colors, opts?)`
 

package/docs/charts.md

@@ -21,12 +21,20 @@ Every chart takes a spec with `data` (rows) plus field names for each role. The
 | `xDomain`, `yDomain` | Fixed `[min, max]`. |
 | `refLines` | `[{ y: 600, label: "Target" }]` (or `x`, or `value` for bars). |
 | `facet` (`col`), `columns`, `sharey`, `sharex` | Small multiples, one panel per value. |
-| `time`, `timeValue`, `slider`, `play` | One period at a time with a slider in the browser; `slider: false` removes it, `play: false` hides only the play button. |
+| `time`, `timeValue` | One period at a time: the latest by default, or `timeValue`. The period is appended to the subtitle. |
+| `slider`, `play` | Browser time controls, **off by default**. `slider: true` adds period buttons when there are few periods (≤ 8) and a minimal slider when there are many; line and area charts get a two-handle range. `"buttons"` or `"slider"` force one; `play: false` hides the play button. |
 | `compare` | With `time`: compare against `"previous"` (default), `"first"`, a given period, or `false`. |
 | `theme`, `palette`, `ramp` | See [themes](themes.md). |
+| `colorScale` (`cmap`) | Any matplotlib colormap (`"viridis"`, `"RdBu_r"`…) or your own list of colors. See [color scales](colorscales.md). |
 | `font`, `textScale` | Typeface (Google Fonts name, CSS stack or `{ family, import }`) and a text-size multiplier (aliases `fontScale`, `labelScale`). Set them for every chart with `configure()`. |
 | `width`, `height`, `padding` | Pixels. Height is automatic for horizontal bars, heatmaps, KPI tiles, and narrow treemaps, sunbursts and radars. |
-| `legend` | `false` hides the legend. |
+| `legend` | Position: `"top"` (default), `"bottom"`, `"left"`, `"right"`, or `false` to hide it. Side legends move to the bottom below 520 px. Setting a position also forces a legend where the chart would otherwise label lines directly. |
+| `exclude` | One name or a list: drop these legend entries (series, first-level groups) and recompute axes, shares and layout. Colors stay fixed and the excluded entries stay in the legend, faded and struck through. |
+
+### In the browser
+
+- **Tooltips** sit next to the hovered mark, never over the title or subtitle, and stay inside the chart. Their header takes the mark's color, with white or dark text depending on contrast.
+- **Legend**: hovering a key highlights its marks; a click pins the highlight. **Shift + click** excludes that entry (click it again to bring it back). In treemaps and sunbursts a plain click zooms the whole plot to that category; click it again, a breadcrumb, or press Esc to go back.
 
 ## Compare
 
@@ -62,7 +70,48 @@ Every chart takes a spec with `data` (rows) plus field names for each role. The
 | `points` | Markers on every point (automatic for short series). |
 | `stack` | Areas: `true` (default with series), `"percent"`, or `false` to overlap. |
 | `fill` | Single line: `false` removes the soft gradient. |
-| `xRange` | Visible range `[from, to]`; this is what the browser slider sets. |
+| `xRange` | Visible range `[from, to]`; this is what the range slider sets (`slider: true`). |
+
+## Projects
+
+### `gantt` (`timeline`, `roadmap`, `schedule`, `cronograma`)
+
+One row per task: `task`, `start` and `end` (or `duration`). Dates like `"2026-03-02"` or `"2026-03"`, or plain numbers for weeks or sprints. Day dates are **inclusive**: a task from March 3 to March 5 lasts 3 days. A row without `end`, or with `end` equal to `start`, is a milestone, drawn as a diamond with its date.
+
+The time axis sits on top, like a calendar. With `group`, each phase opens with its name and a thin summary bar in its color, so no legend is needed. The filled part of each bar is the progress; the rest stays in a light tint of the same color. Dependencies are thin right-angle arrows behind the bars.
+
+```js
+plot({
+  type: 'gantt',
+  title: 'The project goes live on June 15; the ERP integration is the critical path',
+  data: [
+    { phase: 'Design', task: 'Data model', start: '2026-02-09', end: '2026-03-06', progress: 80 },
+    { phase: 'Build', task: 'ERP integration', start: '2026-03-16', end: '2026-04-30', progress: 10, after: 'Data model' },
+    { phase: 'Launch', task: 'Go-live', start: '2026-06-15' },
+  ],
+  task: 'task', start: 'start', end: 'end', group: 'phase', progress: 'progress', dependsOn: 'after',
+  today: '2026-03-12', locale: 'en',
+});
+```
+
+| Option | Meaning |
+|---|---|
+| `task`, `start`, `end` | Field names (detected when they are called `task`/`tarea`, `start`/`inicio`, `end`/`fin`). |
+| `duration` | Length instead of `end`: days on a date axis, units on a numeric one. |
+| `group` (`series`, `hue`) | Phase or team: one colored section per value. `groupHeaders: false` uses a color legend instead. |
+| `progress` | 0–1 or 0–100. Shown as the filled part, with the percentage inside the bar when it fits. |
+| `dependsOn` | Field with the predecessor's name, or several: `"A, B"`. |
+| `milestone` | Boolean field that forces milestones. |
+| `today` | A date (or `true`) for the "today" line, labeled on the axis. `refLines: [{ x, label }]` adds more. |
+| `dashed`, `dashedLabel` | Hatch tentative tasks: a field (`dashed: "tentative"`), names or phases. |
+| `highlight` | Emphasize a task or a whole phase. |
+| `sort` | `"start"` orders tasks by date (default: data order, grouped by phase). |
+| `rowHeight`, `xLabel`, `unit` | Row height in px; axis title and unit for numeric axes. |
+| `collapsed`, `collapsible` | Phases drawn as one summary row (duration-weighted progress, milestone diamonds): a list of names or `true`. In the browser a click on a phase toggles it (Alt + click toggles all); the time axis and name column stay put. `collapsible: false` hides the chevrons. |
+| `critical`, `criticalColor` | Outline the critical path: tasks with zero slack along `dependsOn` (working days on day dates), with accent arrows. |
+| `weekends` | Weekend bands on day-date plans of up to 120 days; `false` turns them off. |
+
+`lint` warns about tasks that end before they start and suggests a `today` line. The alt text names the span, the longest task, the milestones and the overall progress weighted by duration.
 
 ## Relationships
 
@@ -128,7 +177,8 @@ Long data (`axis`, `value`, `series`) or wide data (`axes: [fields]`, one row pe
 | Option | Meaning |
 |---|---|
 | `depth` | Show only the first N levels. |
-| `focus` | Path to drill into, e.g. `["Mining"]`. In the browser, clicking a group does it and breadcrumbs go back. |
+| `focus` | Path to drill into, e.g. `["Mining"]`. In the browser, clicking a group or its legend key does it (the category fills the whole plot) and breadcrumbs or Esc go back. |
+| `exclude` | Level-1 groups to leave out; the rest fill the plane and shares are recomputed. Shift + click on a legend key does it in the browser. |
 | `showValues` | Append values to the labels. |
 | `colorBy` | `"change"` colors tiles by % change vs the comparison period (growth cool, decline warm); `"label"` colors a single-level treemap by item. |
 | `shade` | Subtle lightness steps inside each category. Off by default: one solid color per category. |
@@ -157,26 +207,74 @@ Age groups (`age` or `y`), two sides (`sex`, `series` or `hue`) and a value. Bac
 
 ### `choropleth` (`map`) · `symbolmap` (`bubblemap`)
 
-Chilean regions (`geo: "chile"`, default), US states (`geo: "usa"`) and world countries (`geo: "world"`) ship with the library; any GeoJSON FeatureCollection works too. `key` is the data field to match and `value` the measure. Matching is forgiving: names, codes and aliases, ignoring accents, case and "Región de" ("RM", "Biobio", "XIII", "Aisén", "ARG", "EE.UU.", "TX", "Nueva York", "48").
+Chilean regions (`geo: "chile"`, default), US states (`geo: "usa"`) and world countries (`geo: "world"`) ship with the library, and **any geometry of your own** works too (see below). `key` is the data field to match and `value` the measure; a text `value` (a party, a language, a zone) colors by category with a legend of swatches. Matching is forgiving: names, codes and aliases, ignoring accents, case and "Región de" ("RM", "Biobio", "XIII", "Aisén", "ARG", "EE.UU.", "TX", "Nueva York", "48").
 
 **United States.** 50 states and DC in an Albers equal-area projection (`albersUsa`, the same composite as `d3.geoAlbersUsa`): Alaska (at 0.35×) and Hawaii sit in insets at the bottom left with a fine dashed frame; Puerto Rico gets its own inset only when the data includes it (`territories: true` forces it). Each state shows its postal code, plus the value when it fits; the small northeastern states (VT, NH, MA, RI, CT, NJ, DE, MD, DC) are labeled in a column on the right with leader lines. `values: false` keeps only the codes; `labels: false` removes them.
 
 | Option | Meaning |
 |---|---|
-| `geo` | `"chile"`, `"usa"`, `"world"`, a name registered with `registerGeo()`, or a GeoJSON object. |
-| `featureKey` | Feature property to match (default: tries code, id, ISO-3, name and aliases). |
+| `geo` | `"chile"`, `"usa"`, `"world"`, a name registered with `registerGeo()`, a GeoJSON or TopoJSON object, or (browser) a URL. |
+| `featureKey`, `nameKey` | Feature property to match, and the one with the display name (both detected when omitted). |
+| `fitTo` | Zoom to regions, a `[lonMin, latMin, lonMax, latMax]` box or `"markers"`. |
+| `markers`, `layers` | Points by lon/lat on top; extra GeoJSON lines, polygons or points over or under the map. |
 | `scale`, `classes` | `"quantile"` (default), `"equal"`, `"continuous"` or a list of breaks; 5 classes by default. |
 | `midpoint` / `diverging` | Diverging classes around a value (e.g. 0 for changes). |
 | `missing` | `"plain"` drops the hatch and the "No data" legend entry. |
 | `labels`, `bars` | Chile gets a north-to-south column with name, bar and value; `bars: false` hides the bars. World maps label the top N. |
-| `projection` | `"mercator"`, `"equalEarth"` or `"albersUsa"` (picked automatically). |
+| `projection` | `"mercator"`, `"equalEarth"`, `"albersUsa"`, `"equirectangular"`, `"conic"`, `"identity"`, `"planar"` or `{ type, parallels, rotate }` (picked automatically). |
+| `borderColor`, `borderWidth` | Region borders. |
 | `dashed`, `dashedLabel` | Hatch some regions (preliminary figures, disputed areas): names, codes or a data field. They keep their class color. |
 | `maxRadius` | `symbolmap`: largest circle radius. |
 
+#### Your own geometry: GeoJSON and TopoJSON
+
+`geo` takes whatever you have: a GeoJSON `FeatureCollection`, a single `Feature`, an array of features or a bare geometry, or a TopoJSON `Topology` (`geoObject` picks the object; default the first). Polygons are filled, lines are stroked and points become dots colored by value. In the browser, `render()` also accepts a URL and downloads it once: `geo: "/maps/comunas.topojson"`. In Node, read the file and pass the object.
+
+```js
+import { readFileSync } from 'node:fs';
+const comunas = JSON.parse(readFileSync('comunas-biobio.geojson', 'utf8'));
+plot({
+  type: 'choropleth',
+  geo: comunas,                       // properties: { CUT_COM: "08101", NOM_COM: "Concepción", … }
+  data: [{ comuna: 'Concepción', poverty: 7.1 }, { comuna: 'Coronel', poverty: 12.4 }],
+  key: 'comuna', value: 'poverty',   // NOM_COM is found automatically
+  markers: { data: hospitals, lon: 'lon', lat: 'lat', label: 'name', legend: 'Hospital' },
+  layers: [{ geo: rivers, label: 'Biobío river', stroke: '#5BA3E0', width: 2 }],
+  fitTo: ['Concepción', 'Talcahuano', 'Hualpén'],
+});
+```
+
+- **Matching without configuration.** Rows are matched against the usual keys (code, id, ISO-3, name, aliases); if some rows don't match, plotagents finds the feature property whose values do (`NOM_COM`, `CUT_REG`, `GEOID`, `ADMIN`…). `featureKey` forces one. Display names come from `nameKey`, or the first of `name`, `NOMBRE`, `NAME_1`, `ADMIN` and similar.
+- **Projections.** Picked from the geometry: Mercator for a country or region, Equal Earth for the world, and a plain cartesian plane when coordinates are not longitudes and latitudes (UTM metres, for instance). Set `projection` to `"equirectangular"`, `"conic"` (or `{ type: "conic", parallels: [-30, -45], rotate: 72 }`), `"identity"` (pixel coordinates, y down, for hand-drawn or tile maps) or `"planar"` (y up).
+- **Framing.** `fitTo` zooms to some regions, a box `[lonMin, latMin, lonMax, latMax]` or `"markers"`; the rest of the map stays as clipped context. `tall: false` turns off the side column for elongated shapes.
+- **Markers.** `markers: [{ lon, lat, label, value }]` or `{ data, lon, lat, label, size, color, legend, maxRadius }`: dots on top, area-proportional when there is a `size`, labels placed where they don't collide.
+- **Layers.** `layers: [{ geo, label, stroke, width, fill, dash, opacity, below }]` overlays rivers, roads, routes, faults or district lines (or draws them under the regions with `below: true`). A `label` adds a legend key.
+- **Style.** `borderColor`, `borderWidth`, `pointRadius`, `lineWidth`, `ramp` (a named or custom sequential ramp), `palette` and `colors` (categories).
+- **Register once, use by name.** `registerGeo('biobio', comunas, ['comunas-biobio'])` and then `geo: 'biobio'` in every spec, which keeps tool calls short for an agent.
+
 In the browser (`render()` or `toHTML()`), maps are interactive: hovering outlines the shape; clicking a region zooms to fit it (click again, double-click, Esc or the reset button to go back); Ctrl/⌘ + scroll zooms around the pointer (plain scroll keeps scrolling the page, as `chartjs-plugin-zoom` recommends with its `modifierKey`); pinch zooms on touch screens; drag pans when zoomed; +/− buttons work from the keyboard. Each color class in the legend is a key: hover it to light up its regions, click to pin. With `time`, every region's color transitions into the next period's instead of jumping, and the zoom is kept while the slider plays.
 
 `lint` warns about rows that match no region or country. Sources: Natural Earth 1:110m (public domain) for the world; Biblioteca del Congreso Nacional for Chilean regions (attribution in `src/geo/data/chile-regiones.js`); U.S. Census Bureau cartographic boundaries 1:10m (public domain) via us-atlas 3.0.1 for US states. In the browser, `dist/plotagents-geo.js` adds the geometries; `toHTML()` includes it only when a page has a map.
 
+### `pointmap` (`dotmap`, `tilemap`)
+
+Dots at longitude/latitude over a real basemap in Web Mercator. Fields `lon`/`lat` are found by name (lon, lng, longitude, longitud / lat, latitude, latitud). `size` → circle area (key in the corner, largest labeled); `hue` → category colors with a legend; numeric `value` → sequential ramp (`midpoint` for diverging, `colorScale` for any matplotlib map). Zoom and center fit the points (`zoom`, `center: [lon, lat]` to fix them).
+
+```js
+plot({ type: 'pointmap', data: cities, lon: 'lon', lat: 'lat', size: 'population', label: 'city',
+  title: 'Santiago concentrates 40% of the population', source: 'INE' });
+```
+
+| Option | Meaning |
+|---|---|
+| `tiles` | `"osm"` (default, OpenStreetMap), `"esri-gray"`, `"esri-dark"`, `"carto-light"` / `"carto-dark"` (free key: carto.com/basemaps/apikey), `"mapbox-light"` / `"mapbox-dark"` (public `pk.` token in `tilesKey`; `sk.` tokens are refused), `{ url, attribution, subdomains, maxZoom, retina }`, or `false` (vector world outline only). |
+| `tilesKey` | Key or token for CARTO, Mapbox or Esri. |
+| `tileStyle` | `"muted"` (default) desaturates and tints the tiles to the theme (a navy night map on `noche`); `"original"` keeps them as they are. |
+| `tileOpacity`, `zoom`, `center` | Tile opacity, fixed zoom level and `[lon, lat]` center. |
+| `labels`, `labelValues` | How many dots to name (8 largest by default), or a list; `labelValues: false` hides values. |
+
+The attribution is always drawn. Tiles are external images: they show in inline SVG, `render()` and `toHTML()`, **not** when the SVG is used as `<img>`, opened from a PDF converter, or offline; then the vector world outline underneath still gives context. `await embedTiles(svg)` inlines them as data: URIs (not for OSM, whose tile policy forbids bulk downloads; use `esri-gray` or your own server). For heavy traffic, use a provider with a key or your own tiles: OSM's servers are donated.
+
 ## Dashed shapes: estimates, projections, provisional figures
 
 Some numbers are not firm yet. Instead of a new color (which reads as a new category), plotagents keeps the shape's color and changes its texture: a hatched fill (stripes of the color over a light tint of it) and a dashed outline at 3:1 contrast. Lines get a dashed stroke with hollow points. It works in `bar`, `line`, `area`, `donut`/`pie`, `choropleth` and `symbolmap`.
@@ -193,7 +291,21 @@ This follows the Chart.js advice of using patterns (as `patternomaly` does) and
 
 ### `network` (`graph`)
 
-Edges in `data` (`from`, `to`, optional `value`), optional `nodes` with `id`, `group` and `size`. Deterministic force layout fitted to the whole area, or `layout: "circle"`. `labels` (number or list), `highlight` (a node and its neighbors), `focus` (a node id: it is pinned at the center and highlighted with its neighbors, all of them labeled; in the browser a click does it with a smooth transition, and a second click or Esc returns), `iterations`, `maxRadius`.
+Edges in `data` (`from`, `to`, optional `value`), optional `nodes` with `id`, `group` and `size`. Node area ∝ weight (weighted degree by default), color by group; edges curve in the color of their source node (`curveness`, default 0.3; `0` = straight), 1 px wide without a value field. The largest nodes are named (ink with a halo, never overlapping each other or a node); every name is in the tooltip. Hovering a node lights up its neighbors and their edges.
+
+`layout` picks the placement (all deterministic, all fitted to the area):
+
+| `layout` | Placement |
+|---|---|
+| `force` (default) | Force-directed (Barnes–Hut above 150 nodes). |
+| `circular` (`circle`) | Around a circle by group, a gap between groups, names rotated outward. |
+| `radial` | A tree from `focus` (or the most connected node); each ring is one step further. Links outside the tree are faint. |
+| `concentric` | Rings by weight, the largest in the centre, by group within each ring. |
+| `clusters` | One sunflower cluster per group, space ∝ √size. |
+| `tree` | The radial tree laid flat (left → right on wide areas), S-shaped connectors. |
+| `grid` | A grid ordered by group and weight, every node named. |
+
+`labels` (number, list or `true`), `highlight` (a node and its neighbors), `focus` (a node id: it goes to the center, or the root in `radial`/`tree`, and is highlighted with its neighbors, all labeled; in the browser a click does it with a smooth transition, and a second click or Esc returns), `iterations`, `maxRadius`, `curveness`.
 
 ### `chord`
 
@@ -213,6 +325,28 @@ Edges in `data` (`from`, `to`, optional `value`), optional `nodes` with `id`, `g
 
 `from`, `to`, `value` (also detects `source`/`target`). Color starts at the first stage with more than one node and flows downstream.
 
+### `wordcloud` (`words`, `tagcloud`, `nube`)
+
+Words sized by frequency, done carefully: every word horizontal; each word's **area** proportional to its count (font size grows with the square root); a deterministic spiral layout from the most frequent word outwards, with no collisions; one hue that darkens with frequency, or one color per `series` with a legend. If the important words don't fit, the whole cloud shrinks; the words that still don't fit are named in the alt text, never cut off.
+
+```js
+plot({ type: 'wordcloud', data, text: 'word', value: 'mentions', title: '“Data” dominates what companies ask for' });
+plot({ type: 'wordcloud', text: openAnswers, title: '…', subtitle: 'Mentions in 312 open answers' });  // raw text
+```
+
+| Option | Meaning |
+|---|---|
+| `text` | Field with the words, or the raw text to count (a string or a list of strings). Raw text drops Spanish and English stopwords and numbers. |
+| `textField` | A field of free text in each row (open survey answers): words are counted across rows. |
+| `value` | Weight of each word (default: 1 per row, summed). |
+| `series` | Color by group, with a legend. |
+| `top` | Most words to show (default 80). |
+| `stopwords`, `minLength` | Extra words to ignore; shortest word kept (default 3). |
+| `minFont`, `maxFont` | Font size range. |
+| `highlight` | Words to emphasize; the rest are muted. |
+
+A cloud is good at "what comes up most" and bad at "by how much". `lint` suggests a bar chart (`top: 15`) when there are few words, and asks for a `subtitle` that says what was counted.
+
 ### `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.

package/docs/colorscales.md

@@ -0,0 +1,46 @@
+# Color scales
+
+Every colormap that ships with matplotlib is available by name, plus your own. Use them wherever a chart maps a number to a color: heatmaps, choropleths, point maps, treemaps colored by change and word clouds.
+
+```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
+```
+
+- **Names are case-insensitive** (`'rdbu'` works) and `_r` reverses any map.
+- **Diverging maps center themselves**: on 0 when the data crosses zero, otherwise on the middle of the data. Set `mid` (or `midpoint`) to choose the center.
+- **Your own scale** is a list of two or more colors, evenly spaced from low to high, or `{ colors, reverse, mid }`.
+- Interpolation happens in OKLab, so steps look even. The stops were sampled from matplotlib 3.9 and stay within 2 ΔE (×100) of the original.
+- `cmap` and `colormap` are aliases of `colorScale`. The older `ramp` option still works.
+
+## Categorical palettes
+
+`palette` takes a list of colors, a plotagents palette, or one of matplotlib's qualitative maps:
+
+```js
+plot({ ...spec, palette: 'tab10' });
+plot({ ...spec, palette: 'Set2' });
+plot({ ...spec, palette: 'viridis' });   // a continuous map, sampled into distinct colors
+```
+
+The default palette is validated for color-vision deficiencies; `lint` checks any other palette you bring (see [Themes](themes.md#validating-a-palette)).
+
+## Which one?
+
+| Data | Use | Avoid |
+|---|---|---|
+| Ordered values, low → high | `viridis`, `cividis`, `magma`, `Blues`, `YlGnBu` | `jet`, `rainbow`, `hsv` (they invent edges where the data has none) |
+| Values around a meaningful center (0, a target, an average) | `RdBu`, `coolwarm`, `PuOr`, `BrBG` | a sequential map |
+| Angles, hours of the day, months | `twilight`, `hsv` | a sequential map |
+| Categories | `palette: 'tab10'`, `'Set2'`, `'Dark2'` | any continuous map as `colorScale` |
+
+`lint` flags the rainbow maps with a suggestion, and refuses a qualitative map used as a continuous scale.
+
+## All scales
+
+{{colorscales}}
+
+The list is also available in code: `colorScaleNames()` returns the names grouped by kind, and `resolveColorScale(name)` returns `{ name, stops, kind }`.

package/docs/dashboards.md

@@ -0,0 +1,79 @@
+# Dashboards
+
+`dashboard(spec)` turns a handful of chart specs into a finished, self-contained HTML dashboard. Like a single chart, the design decisions come built in: you say what goes on the page, and the library decides where and how.
+
+```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' },
+  ],
+}));
+```
+
+The page works without JavaScript: every chart is drawn on the server, so it opens in any browser, prints and converts to PDF. When the browser build is available (it is, in Node), the page also gets tooltips, map zoom and live filters. In a web app, `renderDashboard('#board', spec)` draws the same dashboard into an element.
+
+## What it decides for you
+
+These defaults come from dashboard design practice: Stephen Few's *Information Dashboard Design*, the Z-pattern of reading, and what makes business dashboards hard to read.
+
+| Rule | What plotagents does |
+|---|---|
+| **One question per dashboard** | The `title` is the question ("How are southern sales doing?"). `lintDashboard` warns above 9 charts and suggests splitting above 6. |
+| **Numbers first** | KPIs go in one row at the top, at most 5 (warning above). Each one has a label, the figure, its change with an arrow **and** a sign (never color alone), the comparison period and an optional sparkline. |
+| **Z-pattern reading** | The main chart comes right after the KPIs, at full width: the one marked `primary: true`, or else the first time series. |
+| **Full rows, no holes** | A 12-column grid in balanced rows: 2 charts → 6 + 6 (8 + 4 when one is wide), 3 → 4 + 4 + 4, 4 → two rows of two, 5 → 3 + 2. Panels in a row share a height. |
+| **Width follows the chart** | Time series, Gantt charts, heatmaps and flows read left to right, so they get wide panels. Donuts, KPIs and short rankings get narrow ones. Chile's map gets a narrow column. |
+| **Same thing, same color** | One color map across every chart: "Ñuble" is the same color in the line, the treemap and the bars. `colors` pins colors for the whole page. |
+| **One voice** | One theme, locale and typeface for every panel. The source appears once, at the bottom; a chart keeps its own source only when it differs. |
+| **Filters as buttons** | `filters` become buttons when a field has up to 6 values, and a dropdown when it has more. They filter every chart that has the field, recompute the KPIs and say what is filtered in each subtitle. A filter on a chart's `time` field moves that chart to the chosen period. |
+| **Phones** | One column in reading order; KPIs in two columns. |
+| **Print** | Panels don't break across pages; the filter bar is not sticky on paper. |
+
+## Spec
+
+| Option | Meaning |
+|---|---|
+| `title`, `subtitle` | The question, and the scope (measure, unit, period). |
+| `source`, `updated`, `note` | Footer and header metadata. |
+| `locale`, `theme`, `font`, `palette` | Applied to every chart (`theme: "noche"` for a dark dashboard). |
+| `data` | Shared rows. Charts without `data` use them; computed KPIs and filters work on them. |
+| `kpis` | `[{ label, value, delta, period, trend, good, format }]` (fixed) or `[{ label, field, agg, over, scale, compare, trendBy, format }]` (computed). `agg`: `sum`, `mean`, `median`, `min`, `max`, `count`, `distinct`, `ratio` (with `over`). `compare: { field, current, previous }` shows the current period and its change. `trendBy: "month"` draws the sparkline. |
+| `charts` | Chart specs, as in `plot()`. Per chart: `primary: true`, `size: "full" \| "large" \| "medium" \| "small"` or `span` (of 12). |
+| `filters` | `["region"]` or `[{ field, label, control: "buttons" \| "select", value }]`. |
+| `layout` | `"auto"` (default), `"executive"` (main chart full width, then pairs) or `"grid"` (equal panels). |
+| `colors` | `{ "Biobío": "#3A47B8" }` for every chart. |
+
+## For agents
+
+```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` never throws. It reviews the dashboard as a whole (too many charts or KPIs, several pies, mixed themes, filters on fields no chart has, panels without a title) and every chart in it, tagging each issue with the chart's number and title so the model knows which one to fix. `planDashboard(spec)` returns the layout decisions (panels, widths, rows, colors, filters) without drawing anything.

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