plotagents 0.0.0-stage → 0.5.0

package/docs/api.md

@@ -0,0 +1,154 @@
+# API reference
+
+```js
+import {
+  plot, safePlot, lint, describe, render, toHTML, configure,
+  schema, toolDefinition, validatePalette, registerGeo,
+} from 'plotagents';
+```
+
+Full types are in [`index.d.ts`](../index.d.ts) and every spec option in [`schema.json`](../schema.json).
+
+## Drawing
+
+### `plot(spec)`
+
+Draws a chart and returns an SVG string. Works in Node, Deno, Bun and the browser. Throws a `PlotError` when the spec cannot be drawn; the error's `hint` says how to fix it.
+
+```js
+const svg = plot({ type: 'bar', data, x: 'region', y: 'sales', title: 'Biobío leads with 30%' });
+```
+
+### `safePlot(spec)`
+
+The version to expose as an agent tool: it never throws.
+
+```js
+const { ok, svg, type, description, errors, warnings, suggestions } = safePlot(spec);
+```
+
+| Field | Meaning |
+|---|---|
+| `ok` | `true` when the chart was drawn. |
+| `svg` | The SVG string, or `null`. |
+| `type` | The resolved chart type (useful when `type` was inferred). |
+| `description` | Alt text for the chart. |
+| `errors` | Problems that stop the chart: `{ code, message, fix }`. |
+| `warnings` | Problems that make the chart misleading or hard to read. |
+| `suggestions` | Design improvements, such as a better title or `highlight`. |
+
+### `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.
+
+### `describe(spec)`
+
+Returns a text description of the chart, such as "Highest: Biobío with 1,240 (30%)…". The same text goes into the SVG's `<desc>` for screen readers.
+
+## In the browser
+
+### `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.
+
+```js
+const chart = plotagents.render('#chart', spec);
+chart.update({ ...spec, highlight: 'Ñuble' });   // redraw
+chart.destroy();                                // remove listeners and markup
+```
+
+| Option | Meaning |
+|---|---|
+| `controls` | `false` hides sliders and play buttons. |
+
+The handle exposes `svg` (the current `<svg>` element) and `spec`.
+
+### `attach(root)`
+
+Adds tooltips to a container that already holds a plotagents SVG, for example one rendered on the server.
+
+### `toHTML(specs, opts?)`
+
+A self-contained HTML page with one or more interactive charts and the library inlined.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `title` | `"Gráficos"` | Page title. |
+| `lang` | `"es"` | Page language. |
+| `columns` | `1` | Two or more lay charts out in a grid. |
+
+## Configuration
+
+### `configure(options)`
+
+Sets defaults for every later chart; the spec always wins.
+
+```js
+configure({ font: 'Poppins', textScale: 1.5, locale: 'en' });
+configure();       // returns the current defaults
+configure(null);   // clears them
+```
+
+It accepts any spec option: `font`, `textScale`, `locale`, `theme`, `palette`, `ramp` and so on.
+
+### `validatePalette(colors, opts?)`
+
+Checks a custom palette with the same tests the built-in one passes. See [themes](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?)`
+
+Registers your own GeoJSON so specs can use `geo: name`. Chile and the world are built in.
+
+## For agents
+
+### `toolDefinition({ name?, flavor? })`
+
+Returns a tool definition built from the JSON Schema: `flavor: "anthropic"` (default) gives `{ name, description, input_schema }`, `flavor: "openai"` gives `{ 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`
+
+The JSON Schema of a spec, also published as [`schema.json`](../schema.json) and importable as `plotagents/schema.json`.
+
+## Helpers
+
+| Export | Meaning |
+|---|---|
+| `TYPES` | Every chart type name. |
+| `themes`, `getTheme(t)`, `themeFor(spec)` | Built-in themes and the resolved theme of a spec. |
+| `palettes`, `ramps` | Named categorical palettes and sequential/diverging ramps. |
+| `timeValues(spec)` | Sorted values of the `time` field. |
+| `makeFormat(fmt, locale, values)` | The number formatter a chart would use. |
+| `formatNumber(v, decimals, locale)`, `formatCompact(v, locale)` | Locale-aware number formatting. |
+| `squarify(items, x, y, w, h)` | The treemap layout algorithm. |
+| `bundleSource()` | Node only: the browser build as a string, for inlining. |
+
+## Package entry points
+
+| Import | Contents |
+|---|---|
+| `plotagents` | Everything above (ES module). |
+| `plotagents/schema.json` | The JSON Schema. |
+| `plotagents/browser` | `dist/plotagents.js`: a `<script>` that defines `window.plotagents`. |
+| `plotagents/browser/geo` | `dist/plotagents-geo.js`: Chile and world geometries for the browser build. |
+| `plotagents/geo/chile`, `plotagents/geo/world` | The geometries as ES modules. |

package/docs/charts.md

@@ -0,0 +1,218 @@
+# Chart reference
+
+Every chart takes a spec with `data` (rows) plus field names for each role. The options below are specific to each type; the [common options](#common-options) apply to all of them. Every option is also described in [`schema.json`](../schema.json).
+
+## Common options
+
+| Option | Meaning |
+|---|---|
+| `type` | Chart type or alias. Omit (or `"auto"`) to infer it from the data. |
+| `data` | Array of row objects. `{ A: 1, B: 2 }` and arrays of numbers are accepted too. |
+| `title` | The finding, as a sentence. Wraps; never truncated. |
+| `subtitle` | How to read the chart: measure, unit, period. |
+| `source` | Data source, shown small at the bottom right. |
+| `series` / `hue` | Field that splits the data into colored groups. |
+| `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`). |
+| `xLabel`, `yLabel` | Axis titles (horizontal, never rotated). |
+| `xScale`, `yScale` | `"log"` where it makes sense. |
+| `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. |
+| `compare` | With `time`: compare against `"previous"` (default), `"first"`, a given period, or `false`. |
+| `theme`, `palette`, `ramp` | See [themes](themes.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. |
+
+## Compare
+
+### `bar` · `column` · `barplot` · `count` (`countplot`)
+
+`x` category, `y` value. Columns for few short categories, horizontal bars when labels are long or there are many; values at the bar tips and no axis when every bar is labeled.
+
+| Option | Meaning |
+|---|---|
+| `stack` | `true` stacks series; `"percent"` stacks to 100%. |
+| `horizontal` | Force orientation. |
+| `sort` | `"desc"` (default for categories), `"asc"`, `"none"`, `"alpha"`. Years and dates keep their order. |
+| `top` | Keep the N largest, fold the rest into "Other" (automatic past 40 categories). |
+| `ci`, `errorbar`, `estimator` | `barplot`: mean ± 95% CI (`"ci"`), `"sd"` or `"se"` error bars. |
+| `aggregate` | `"sum"` (default), `"mean"`, `"max"`, `"min"`, `"count"`, `"first"`, `"last"`. `countplot` counts rows. |
+| `labels` | `true`, `false` or `"auto"`. |
+| `barWidth` | Max bar thickness in px. |
+
+## Time
+
+### `line` · `area`
+
+`x` date (`"2024-03"`, `"2024-03-15"`, `Date`), year or number; `y` value or list of fields (wide table → series).
+
+| Option | Meaning |
+|---|---|
+| `labels` | End labels (default on for every series that fits; colliding labels get leader lines). |
+| `annotations` | `[{ x: "2024-01", label: "New branch" }]`. |
+| `index` | Rebase each series to 100 at its first value. |
+| `ci`, `errorbar`, `estimator` | seaborn `lineplot`: mean and confidence band when there are several rows per x. |
+| `curve` | `"linear"` (default), `"smooth"` (monotone, never invents peaks), `"step"`. |
+| `zero` | Force the y axis to include zero (on by default for areas and when it costs little). |
+| `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. |
+
+## Relationships
+
+### `scatter` · `bubble`
+
+`x`, `y` numeric; `size` for bubbles (area-proportional); `label` field with `labels` (number of points or list of names) for selective labels; `trend: true` adds a least-squares line with R².
+
+### `regplot` (`lmplot`) · `residplot` · `jointplot`
+
+| Option | Meaning |
+|---|---|
+| `ci` | Confidence band level (95 by default, `false` to hide). |
+| `order` | Polynomial degree. |
+| `lowess` (+ `frac`) | Local regression instead of a line. |
+| `logx` | Fit `y ~ log(x)` and use a log x axis. |
+| `scatter` | `false` hides the points. |
+| `truncate` | Draw the fit only over the data range (default `true`). |
+| `annotate` | Show R² and n. |
+| `label`, `labels` | Name selected points. |
+| `kind` | `jointplot`: `"scatter"` or `"reg"`. |
+| `marginal` | `jointplot`: `"hist"` or `"kde"`. |
+
+### `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.
+
+## Distributions
+
+### `hist` (`histplot`) · `kde` (`kdeplot`) · `ecdf`
+
+| Option | Meaning |
+|---|---|
+| `bins`, `binWidth` | Bin count or width (default: Freedman–Diaconis, rounded to nice edges). |
+| `stat` | `"count"`, `"percent"`, `"density"`, `"probability"`. |
+| `kde` | Overlay a density curve on the histogram. |
+| `multiple` | With `hue`: `"layer"`, `"stack"`, `"dodge"`, `"fill"`. |
+| `element` | `"bars"` or `"step"`. |
+| `cumulative` | Cumulative distribution. |
+| `fill`, `bwAdjust`, `cut`, `clip`, `rug` | Density options. |
+| `complementary` | `ecdf`: plot 1 − F(x). |
+
+### `box` · `violin` · `strip` · `swarm` (`beeswarm`) · `point` (`pointplot`)
+
+`x` category and `y` measure (swap them, or set `horizontal`, for horizontal). Long labels or many categories switch to horizontal automatically.
+
+| Option | Meaning |
+|---|---|
+| `points` | Box: overlay the observations. |
+| `showMeans` | Mark the mean. |
+| `inner` | Violin: `"box"` (default), `"quartiles"`, `"points"`, `"none"`. |
+| `split` | Violin with two `hue` levels: one half each. |
+| `scale` | Violin width: `"width"`, `"area"`, `"count"`. |
+| `jitter`, `dodge`, `radius` | Strip and swarm layout. |
+| `estimator`, `errorbar` | Point plot: `"mean"`/`"median"`/`"sum"` and `"ci"`/`"sd"`/`"se"`/`"pi"`. |
+| `order`, `hueOrder` | Category and group order. |
+
+## Part-to-whole
+
+### `treemap` · `sunburst`
+
+`path: [level1, level2, …]` of any depth (or `group` + `label`), `value`. Rows with the same path are summed.
+
+| 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. |
+| `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. |
+| `compareData` | Rows of an earlier period to compute changes without `time`. |
+| `hole`, `centerValue`, `centerLabel` | Sunburst center. |
+
+Areas are exact: there are no header bands taking space from a group. Categories are told apart by one solid color, a 4 px gap between level-1 groups (2 px and 1 px deeper) and the legend, which lists each group's share. With `time`, every tile also shows its change vs the previous period (▲ 12%). Colors belong to the level-1 group and are computed over the full tree and across all periods, so they never change when drilling or sliding.
+
+### `pyramid` (`populationpyramid`)
+
+Age groups (`age` or `y`), two sides (`sex`, `series` or `hue`) and a value. Back-to-back bars with the ages in the center column; `percent: true` for shares of the population; `compareData`, or `time` + `compare`, draws an earlier year as a stepped outline.
+
+### `donut` · `pie`
+
+`label`, `value`. More than `maxSlices` (6) folds into "Other".
+
+| Option | Meaning |
+|---|---|
+| `labels` | `"auto"`, `"inside"`, `"outside"` (leader lines), `"legend"`, `false`. |
+| `half` | Semicircle. |
+| `thickness` | Ring thickness (pie is `1`). |
+| `sort` | `"desc"` or `"none"`. |
+| `centerValue`, `centerLabel` | Donut center. |
+
+## Maps
+
+### `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").
+
+**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). |
+| `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). |
+| `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. |
+
+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.
+
+## 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`.
+
+| Option | Meaning |
+|---|---|
+| `dashed` | A category, series or region name, or a list (`["Texas", "Ohio"]`); a data field whose truthy rows are dashed (`"provisional"`, accepts `true`, `1`, `"sí"`, `"yes"`, `"x"`); `{ field, equals }`; or `true` for everything. |
+| `dashedFrom` | On a time axis (`line`, `area`, `bar`): the first x that is projected. The line turns dashed from the last firm point, projected points are hollow, stacked areas are hatched in each series' color and a soft band with `dashedLabel` marks the stretch. |
+| `dashedLabel` | What it means: "Projection", "Preliminary", "Estimate". It is the legend entry (hover it to light up only the dashed shapes), the band label and a line in the tooltip. Defaults to "Estimado"/"Estimate"; `lint` suggests setting it. |
+
+This follows the Chart.js advice of using patterns (as `patternomaly` does) and `segment.borderDash` for projected stretches, so the distinction never depends on color alone.
+
+## Networks and flows
+
+### `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`.
+
+### `chord`
+
+`from`, `to`, `value` rows, or `matrix` + `names`. `directed` (default false), `sort`, `ribbonColor: "smaller" | "larger" | "source"`, `labelOrientation: "radial"`.
+
+### `flowchart` (`flow`, `diagram`)
+
+`nodes` with `id`, `label`, `type` (`start`, `end`, `process`, `decision`, `data`, `note`), optional `lane` (swimlanes) and `group`; `edges` (or `data`) with `from`, `to` and an optional `label` ("Yes"/"No"). Layered layout with automatic direction (`direction: "TB" | "LR"`), orthogonal connectors with arrows, loops routed around the side. `nodeWidth`, `swimlanes: false`.
+
+## Grids, flows and numbers
+
+### `heatmap`
+
+`x`, `y` categories and `value`. Sequential ramp by default; `midpoint` (or `diverging: true`) for a diverging ramp. Values are written in cells when they fit.
+
+### `sankey`
+
+`from`, `to`, `value` (also detects `source`/`target`). Color starts at the first stage with more than one node and flows downstream.
+
+### `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/getting-started.md

@@ -0,0 +1,138 @@
+# Getting started
+
+plotagents turns one JSON object into a finished, accessible SVG chart. You pass rows of data and name the fields; the library makes every design decision: chart layout, colors, labels, number formats and spacing.
+
+## Install
+
+```bash
+npm install github:carlosnavarreteliz/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.
+
+Node 18 or later, Deno and Bun work out of the box. The package has no dependencies.
+
+## Your first chart
+
+```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` is a string. Write it to a `.svg` file, put it in HTML or Markdown, or convert it to PDF or PNG with any SVG tool.
+
+## Anatomy of a spec
+
+| Field | What it is |
+|---|---|
+| `type` | The chart type, such as `bar`, `line` or `treemap`. Leave it out to infer it from the data. |
+| `data` | A list of rows: `[{ region: "Biobío", sales: 1240 }]`. |
+| `x`, `y`, `series` | Which field goes where. Each chart type documents its own roles in the [chart reference](charts.md). |
+| `title` | The finding, as a full sentence with the key number. |
+| `subtitle` | How to read the chart: measure, unit and period. |
+| `source` | Where the data comes from. Use `"illustrative data"` when it is made up. |
+| `locale` | `"es"` (the default, `1.234,5`) or `"en"` (`1,234.5`). |
+
+### Wide tables
+
+When each measure is its own column, pass a list in `y` and each field becomes a series:
+
+```js
+plot({
+  type: 'line',
+  data: [
+    { month: '2025-01', revenue: 120, costs: 90 },
+    { month: '2025-02', revenue: 132, costs: 94 },
+  ],
+  x: 'month',
+  y: ['revenue', 'costs'],
+});
+```
+
+### Numbers written as text
+
+Values such as `"1.234,5"`, `"12%"` or `"$ 3.000"` are parsed automatically, so data copied from a spreadsheet works without cleaning.
+
+## In the browser
+
+Without a bundler, load the browser build and call `render()`. It draws into an element and adds tooltips, responsive width, time sliders and 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>
+```
+
+The same file ships in the package as `dist/plotagents.js`. Maps need the geometries too: add `dist/plotagents-geo.js` after `plotagents.js`.
+
+`render()` returns a handle with `update(spec)` to redraw with a new spec and `destroy()` to remove the chart and its listeners.
+
+## A whole report in one file
+
+`toHTML()` builds a self-contained, interactive page with the library inlined, so it works offline and from a file.
+
+```js
+import { writeFileSync } from 'node:fs';
+import { toHTML } from 'plotagents';
+
+writeFileSync('report.html', toHTML([spec1, spec2], { title: 'Monthly report', lang: 'en', columns: 2 }));
+```
+
+## From the command line
+
+```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
+```
+
+The CLI also reads a spec from standard input: `cat spec.json | npx plotagents > chart.svg`.
+
+## Catching mistakes
+
+`plot()` throws a `PlotError` with a hint when a spec cannot be drawn. `safePlot()` never throws, and `lint()` reviews a spec without drawing it:
+
+```js
+import { safePlot } from 'plotagents';
+
+const { ok, svg, errors, warnings, suggestions } = safePlot(spec);
+if (!ok) console.log(errors.map((e) => `${e.message} → ${e.fix}`));
+```
+
+Every error, warning and suggestion carries a `fix` that says what to change.
+
+## Next steps
+
+- Browse the [gallery](../examples/) to find the chart you need and copy its code.
+- Try specs live in the [playground](../playground/).
+- Read the [chart reference](charts.md) for every option of every type.
+- Give an agent the [agent guide](agents.md) and the tool definition.

package/docs/rendering.md

@@ -0,0 +1,47 @@
+# Rendering: SVG or Canvas?
+
+**Decision: SVG everywhere, with automatic path batching for dense marks.** Canvas was evaluated and rejected: batched SVG is faster than Canvas on every size we tested and keeps the properties that matter for a library used by agents.
+
+## What we measured
+
+Scatter plot, two colors, 720 × 420 px, Chromium (Playwright), time from inserting the markup to the second animation frame. Same machine, same data.
+
+| Points | SVG, one `<circle>` per point | Canvas 2D (`arc` + `fill`) | SVG, one `<path>` per color | plotagents (batched SVG, full chart) |
+|---|---|---|---|---|
+| 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 |
+
+The cost of naive SVG is the DOM: one element per mark. Drawing all circles of one color as arcs inside a single `<path>` removes that cost, and the browser rasterizes one path faster than a script can issue tens of thousands of Canvas calls.
+
+Reproduce it with `node scripts/bench.js` (needs Playwright with Chromium installed).
+
+## Why SVG wins for this library
+
+| Need | SVG | Canvas |
+|---|---|---|
+| Render on a server, in Node, with zero dependencies | Yes: SVG is a string | Needs a native module (`node-canvas`) or a headless browser |
+| An agent can read and check its own output | Yes: titles, labels and values are text | No: a bitmap |
+| Accessibility (`<title>`, `<desc>`, screen readers, text selection) | Built in | Must be rebuilt by hand next to the canvas |
+| Crisp at any zoom, print and PDF | Vector | Fixed resolution; must re-render for each pixel ratio |
+| Paste into slides, Word, Figma, Markdown, email | Works as a file | Only as an image |
+| Theming with CSS, dark mode, hover states | CSS classes | Manual redraw |
+| 50,000+ points | Fast with batching (above) | Fast |
+
+Canvas only wins when a chart needs hundreds of thousands of marks redrawn every frame, such as live streaming or animated particle fields. That is outside what a chart for decisions needs, and well past the point where a heatmap or a density plot (`kde`, `hist`) tells the story better than overplotted points.
+
+## How batching works
+
+`dotLayer()` in `src/svg.js` takes the circles a chart wants to draw:
+
+- **Up to 1,500 points:** one `<circle>` each, with its own tooltip and hover state.
+- **More than 1,500 points:** circles are grouped by style (color, radius, opacity) and each group becomes one `<path>` of arcs. A transparent `<rect class="pa-near">` carries the coordinates and tooltip text of up to 20,000 points, and the browser layer finds the nearest point within 14 px on hover and rings it.
+
+Scatter, bubble, regplot, residplot, jointplot, strip and swarm use it automatically. No option is needed.
+
+## Other performance choices
+
+- **Text measurement without a DOM.** Width tables calibrated for humanist sans faces let labels be fitted, wrapped and truncated identically in Node and in the browser.
+- **Numbers rounded to two decimals** in all coordinates keeps files small.
+- **One file for the browser.** `dist/plotagents.js` (no dependencies) is inlined by `toHTML()` so interactive pages work offline, from a file, or inside an artifact.

package/docs/themes.md

@@ -0,0 +1,86 @@
+# Themes
+
+A theme is a JSON object. Pass a name or an object; objects are deep-merged over a base theme, so you only write what changes.
+
+```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
+```
+
+## Library-wide defaults
+
+```js
+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.
+
+## Built-in themes
+
+| Name | Mode | Surface | Use |
+|---|---|---|---|
+| `papel` (alias `light`) | light | `#FCFBF9` paper | default |
+| `noche` (alias `dark`) | dark | `#0B0F2B` deep navy | dark pages, slides |
+
+Both share the same eight hues, stepped separately for each surface and validated on it.
+
+## Keys
+
+| Key | Type | Meaning |
+|---|---|---|
+| `extends` | `'papel' \| 'noche'` | 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). |
+| `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. |
+| `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. |
+| `marks` | `{ barRadius, barMax, barMaxH, lineWidth, pointRadius, gap, ring, areaOpacity, bandOpacity, dotOpacity }` | Mark geometry. |
+| `axes` | `{ inside, grid }` | `inside: true` puts y labels on their gridlines inside the plot (more width for data). |
+| `layout` | `{ padding, paddingSmall }` | Outer margin on wide and narrow widths. |
+
+## Named palettes and ramps
+
+| Palettes (`categorical`) | Ramps (`sequential` / `diverging`) |
+|---|---|
+| `cdia` (default), `cdia-noche`, `okabe-ito`, `tableau10`, `udec` | `indigo`, `magenta`, `teal`, `amber`, `indigo-magenta`, `teal-rust` |
+
+## Validating a palette
+
+```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' }, … ] }
+```
+
+| Check | Threshold | Why |
+|---|---|---|
+| Lightness band | OKLCH L 0.43–0.77 (light), 0.48–0.67 (dark) | Too light disappears, too dark reads as text. |
+| Chroma floor | OKLCH C ≥ 0.10 | Below it a hue reads as gray. |
+| Colorblind separation | ΔE OKLab × 100 ≥ 8 between neighbors, simulated protanopia and deuteranopia (Machado 2009) | Neighbors must stay apart for color-vision deficiencies. |
+| Normal-vision separation | ΔE ≥ 15 | Neighbors must be easy to tell apart for everyone. |
+| Contrast with the surface | ≥ 3:1, warning only | Below it, marks need visible labels. |
+
+Use `pairs: 'all'` for scatter plots and maps, where any two colors can sit next to each other. The built-in palette passes all-pairs for its first three colors, which is why `lint` warns about scatter plots with more than three groups.
+
+`lint(spec)` runs this automatically whenever a spec brings its own palette. Messages follow `locale` (Spanish by default, `'en'` for English).
+
+## Color follows the entity
+
+Colors are assigned to entities, never to positions:
+
+- With `time`, colors are computed over all periods, so a group keeps its color while the slider moves even if its rank changes.
+- With `focus` (drill-down), the subtree keeps its parent's color family.
+- With `facet`, every panel shares one color map.
+- `colors: { "Copper": "#B5562E" }` pins any entity to a color.