@unovis/mcp 1.7.0-mcp.0

package/docs/programmatic.md

@@ -0,0 +1,234 @@
+# Programmatic use
+
+The MCP server is the packaging, not the engine. Everything it does is exported,
+so you can render charts from a script, a build step, a web server, or your own
+MCP server.
+
+```bash
+npm install @unovis/mcp
+```
+
+## Render a chart spec
+
+```ts
+import { renderChart } from '@unovis/mcp'
+
+const { svg, width, height, warnings } = await renderChart({
+  container: 'xy',
+  width: 800,
+  height: 400,
+  theme: 'light',
+  title: 'Weekly deploys',
+  components: [{
+    type: 'GroupedBar',
+    config: { x: { $index: true }, y: { $field: 'count', as: 'number' } },
+  }],
+  xAxis: { tickFormat: { $lookup: ['W1', 'W2', 'W3'] }, tickValues: [0, 1, 2] },
+  yAxis: { gridLine: true },
+  data: [{ count: 12 }, { count: 19 }, { count: 14 }],
+})
+
+await writeFile('deploys.svg', svg)
+```
+
+See [Chart spec](./chart-spec.md) for the full format. `warnings` is normally
+empty; non-fatal render issues land there rather than throwing.
+
+## Use the tool schemas instead of hand-writing specs
+
+The recipes that back the tools are exported, so you can reuse their validation
+and defaults:
+
+```ts
+import { recipeByName, renderChart } from '@unovis/mcp'
+import { z } from 'zod'
+
+const recipe = recipeByName.get('generate_line_chart')!
+const input = z.object(recipe.inputShape).parse({
+  data: [{ m: 'Jan', sales: 10 }, { m: 'Feb', sales: 14 }],
+  x: 'm',
+  y: 'sales',
+})
+
+const { svg } = await renderChart(recipe.toSpec(input))
+```
+
+## `renderToSvg`
+
+The headless primitive underneath everything: it creates the DOM, drives the
+render to completion, and serializes standalone SVG. Use it when you want to
+write ordinary Unovis code — with real accessor functions and any config option
+— rather than a JSON spec.
+
+```ts
+import { renderToSvg } from '@unovis/mcp'
+
+interface Row { date: number; value: number }
+
+const { svg } = await renderToSvg({
+  width: 900,
+  height: 400,
+  theme: 'dark',
+  title: 'Latency p95',
+}, (ctx) => {
+  const line = new ctx.unovis.Line<Row>({
+    x: d => d.date,
+    y: d => d.value,
+    duration: 0,
+  })
+
+  return new ctx.unovis.XYContainer<Row>(ctx.container, {
+    components: [line],
+    xAxis: new ctx.unovis.Axis<Row>({ duration: 0, tickFormat: t => new Date(Number(t)).toISOString().slice(0, 10) }),
+    yAxis: new ctx.unovis.Axis<Row>({ duration: 0, label: 'ms' }),
+    width: ctx.width,
+    height: ctx.height,
+    duration: 0,
+    onRenderComplete: ctx.onRenderComplete,
+  }, rows)
+})
+```
+
+Three rules, all of which the API nudges you toward:
+
+1. **Use `ctx.unovis`, don't import `@unovis/ts` yourself.** The library captures
+   its environment when it loads — emotion inserts stylesheets, text measurement
+   grabs a canvas context — so it has to be imported *after* the shims are in
+   place. `ctx.unovis` is that already-initialised namespace.
+2. **Wire `ctx.onRenderComplete` into the container config.** It's how the
+   renderer knows drawing finished. Omit it and you get an explicit error rather
+   than a blank chart.
+3. **Pass `duration: 0`.** Animations are meaningless for a static render and
+   would leave transitions half-applied. (Components default to 600ms, so set it
+   on components too.)
+
+For components whose layout is asynchronous — `Graph` with a force layout —
+declare it so the render waits:
+
+```ts
+await renderToSvg({ width: 800, height: 600 }, (ctx) => {
+  ctx.requireComponentReady()
+  const graph = new ctx.unovis.Graph({
+    layoutType: 'force',
+    duration: 0,
+    onRenderComplete: ctx.onComponentReady,
+  })
+  return new ctx.unovis.SingleContainer(ctx.container, {
+    component: graph, width: ctx.width, height: ctx.height, duration: 0,
+    onRenderComplete: ctx.onRenderComplete,
+  }, { nodes, links })
+})
+```
+
+### Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `width`, `height` | required | Final image size |
+| `theme` | `light` | |
+| `title`, `legend` | — | Synthesized into the SVG header |
+| `colors` | — | Hex palette overriding `--vis-colorN` |
+| `padding` | 12/16/16/16 | Frame around the chart; pass zeros to disable |
+| `idPrefix` | random | Set a constant for byte-stable snapshots |
+| `keepClasses` | `false` | Keep emotion classes and skip style inlining (debug) |
+
+## PNG rasterization
+
+```ts
+import { renderToSvg, svgToPng, themeBackground } from '@unovis/mcp'
+
+const { svg, width } = await renderToSvg({ width: 800, height: 400 }, build)
+const png = await svgToPng(svg, { width, scale: 2, background: themeBackground('light') })
+await writeFile('chart.png', png)
+```
+
+`background` matters: CSS `background-color` isn't an SVG rendering attribute,
+so a rasterizer would otherwise give you a transparent backdrop.
+
+## Interactive HTML
+
+```ts
+import { buildChartDocument } from '@unovis/mcp'
+
+await writeFile('chart.html', buildChartDocument(spec, { duration: 400 }))
+```
+
+See [Interactive charts](./interactive.md) for the widget and iframe embedding.
+
+## Generate framework code
+
+```ts
+import { generateCode } from '@unovis/mcp'
+
+for (const file of generateCode(spec, 'react')) {
+  await writeFile(file.name, file.content)   // Chart.tsx
+}
+```
+
+Angular returns two files (template + component class).
+
+## Add these tools to your own MCP server
+
+If you already run an MCP server — say one that queries your warehouse — you can
+add charting to it instead of running a second process:
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { registerTools } from '@unovis/mcp'
+
+const server = new McpServer({ name: 'my-server', version: '1.0.0' })
+
+registerMyOwnTools(server)
+registerTools(server, { disabledTools: ['generate_choropleth_map'] })
+```
+
+Or take the whole prebuilt server and attach your own transport:
+
+```ts
+import { buildServer } from '@unovis/mcp'
+
+const server = buildServer({ enabledTools: ['generate_line_chart', 'generate_bar_chart'] })
+await server.connect(myTransport)
+```
+
+## Example: charts in CI
+
+A build step that regenerates documentation assets, in both themes:
+
+```ts
+import { renderChart, svgToPng, themeBackground } from '@unovis/mcp'
+import { writeFile } from 'node:fs/promises'
+
+const metrics = JSON.parse(await readFile('metrics.json', 'utf8'))
+
+for (const theme of ['light', 'dark'] as const) {
+  const { svg, width } = await renderChart({
+    container: 'xy',
+    width: 900,
+    height: 360,
+    theme,
+    title: 'Bundle size over time',
+    components: [{ type: 'Area', config: { x: { $field: 'commit', as: 'number' }, y: { $field: 'kb', as: 'number' } } }],
+    xAxis: { label: 'commit' },
+    yAxis: { label: 'kB', gridLine: true },
+    data: metrics,
+  })
+
+  await writeFile(`docs/bundle-size-${theme}.svg`, svg)
+  await writeFile(`docs/bundle-size-${theme}.png`,
+    await svgToPng(svg, { width, scale: 2, background: themeBackground(theme) }))
+}
+```
+
+No browser, no display server — this runs on any CI runner.
+
+## Performance notes
+
+- The first render initialises jsdom, imports `@unovis/ts` and provisions fonts
+  (roughly a second, plus a one-time font download). Later renders are
+  milliseconds.
+- Renders are **serialized** through a mutex: one shared jsdom document and one
+  animation-frame queue mean concurrent renders would interfere. Parallelise
+  across processes if you need throughput.
+- Data lives in memory as-is. Thousands of points are fine; millions are the
+  wrong tool.

package/docs/tools.md

@@ -0,0 +1,273 @@
+# Tools reference
+
+<!-- Generated by scripts/generate-tool-docs.mjs — run `pnpm docs:tools` after changing a recipe. -->
+
+Every chart tool takes `data` as an array of flat records plus field-name
+accessors, and shares the options documented in
+[Output types](./output-types.md#shared-options): `width`, `height`,
+`theme`, `title`, `colors`, `outputType`, `outputPath`, `scale`
+and `framework`.
+
+Tools can be hidden per deployment with `DISABLED_TOOLS` or `--tools`
+(see [Getting started](./getting-started.md#limiting-the-tool-surface)).
+
+## Chart tools
+
+### `generate_line_chart`
+
+Generate a line chart (single or multi-series) for trends over a continuous or time dimension. Data is an array of flat records; x and y reference field names. Example: data=[{"month":"2024-01","sales":120,"cost":80},...], x="month", xIsTime=true, y=["sales","cost"].
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `x` | string | **required** | Field for X values: numbers, or date strings when xIsTime is true, or category names |
+| `y` | string \| string[] | **required** | Field name(s) for Y values. Multiple field names render multiple lines |
+| `xIsTime` | boolean | `false` | Treat x values as dates/timestamps (time axis) |
+| `seriesLabels` | string[] | — | Display names for the y series (legend). Defaults to field names |
+| `lineWidth` | number | `2` | Line stroke width in pixels |
+| `curve` | `linear` \| `monotoneX` \| `basis` \| `natural` \| `step` \| `stepAfter` \| `stepBefore` | `"monotoneX"` | Line interpolation type |
+| `interpolateMissing` | boolean | `false` | Draw dashed interpolated segments across missing (null) values instead of gaps |
+| `yDomainMin` | number | — | Force the Y axis to start at this value |
+| `yDomainMax` | number | — | Force the Y axis to end at this value |
+| `referenceLines` | { axis, value, label, color, lineWidth, style }[] | — | Reference lines for thresholds/targets, e.g. an SLA or goal |
+| `referenceBands` | { axis, from, to, label, color }[] | — | Shaded ranges drawn behind the data, e.g. an acceptable range |
+| `xAxisLabel` | string | — | Label for the X axis |
+| `yAxisLabel` | string | — | Label for the Y axis |
+| `showGridLines` | boolean | `true` | Show horizontal/vertical grid lines |
+| `legend` | boolean | `true` | Show a legend (multi-series charts only) |
+
+### `generate_area_chart`
+
+Generate an area chart for volumes/magnitudes over a continuous or time dimension. Multiple y fields are stacked by default; set stacked=false to overlay them with transparency. Example: data=[{"month":"2024-01","mobile":120,"desktop":80},...], x="month", xIsTime=true, y=["mobile","desktop"].
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `x` | string | **required** | Field for X values: numbers, or date strings when xIsTime is true, or category names |
+| `y` | string \| string[] | **required** | Field name(s) for Y values. Multiple field names render multiple areas |
+| `stacked` | boolean | `true` | Stack multiple y series on top of each other. When false, series overlap with transparency |
+| `curve` | `linear` \| `monotoneX` \| `basis` \| `natural` \| `step` \| `stepAfter` \| `stepBefore` | `"monotoneX"` | Area interpolation type |
+| `xIsTime` | boolean | `false` | Treat x values as dates/timestamps (time axis) |
+| `seriesLabels` | string[] | — | Display names for the y series (legend). Defaults to field names |
+| `referenceLines` | { axis, value, label, color, lineWidth, style }[] | — | Reference lines for thresholds/targets, e.g. an SLA or goal |
+| `referenceBands` | { axis, from, to, label, color }[] | — | Shaded ranges drawn behind the data, e.g. an acceptable range |
+| `xAxisLabel` | string | — | Label for the X axis |
+| `yAxisLabel` | string | — | Label for the Y axis |
+| `showGridLines` | boolean | `true` | Show horizontal/vertical grid lines |
+| `legend` | boolean | `true` | Show a legend (multi-series charts only) |
+
+### `generate_bar_chart`
+
+Generate a bar chart: single-series, grouped, or stacked; vertical or horizontal. Use for comparing values across categories. Example: data=[{"country":"US","gold":9,"silver":8},...], x="country", y=["gold","silver"], type="stacked".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `x` | string | **required** | Field for the category dimension (names or numbers) |
+| `y` | string \| string[] | **required** | Field name(s) for bar values. Multiple field names render one bar (or stack segment) per series |
+| `type` | `grouped` \| `stacked` | `"grouped"` | How multiple series are arranged: side-by-side groups or stacks |
+| `orientation` | `vertical` \| `horizontal` | `"vertical"` | Bar direction. Horizontal puts categories on the Y axis |
+| `seriesLabels` | string[] | — | Display names for the series (legend). Defaults to field names |
+| `roundedCorners` | boolean | `true` | Round the outer bar corners |
+| `barPadding` | number | — | Padding between bars within a group, 0..0.9 |
+| `referenceLines` | { axis, value, label, color, lineWidth, style }[] | — | Reference lines for thresholds/targets, e.g. an SLA or goal |
+| `referenceBands` | { axis, from, to, label, color }[] | — | Shaded ranges drawn behind the data, e.g. an acceptable range |
+| `xAxisLabel` | string | — | Label for the X axis |
+| `yAxisLabel` | string | — | Label for the Y axis |
+| `showGridLines` | boolean | `true` | Show horizontal/vertical grid lines |
+| `legend` | boolean | `true` | Show a legend (multi-series charts only) |
+
+### `generate_scatter_plot`
+
+Generate a scatter plot (or bubble chart) showing the relationship between two numeric fields. Optional: size field for bubbles, colorBy category field for colored groups with a legend, label field for point labels. Example: data=[{"gdp":43000,"lifeExp":81.2,"pop":38.2,"region":"Europe","country":"..."},...], x="gdp", y="lifeExp", size="pop", colorBy="region", label="country".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `x` | string | **required** | Field for X values (numeric) |
+| `y` | string | **required** | Field for Y values (numeric) |
+| `size` | string | — | Numeric field mapped to point size (bubble chart). Values are scaled into sizeRange |
+| `sizeRange` | [number, number] | `[8,40]` | Point diameter range [min, max] in pixels, used when size is set |
+| `pointSize` | number | `10` | Fixed point diameter in pixels, used when size is not set |
+| `colorBy` | string | — | Categorical field: points are colored by its value and a legend is shown |
+| `label` | string | — | Field with point labels. Overlapping labels are hidden automatically |
+| `shape` | `circle` \| `cross` \| `diamond` \| `square` \| `star` \| `triangle` \| `wye` | `"circle"` | Point shape |
+| `referenceLines` | { axis, value, label, color, lineWidth, style }[] | — | Reference lines for thresholds/targets, e.g. an SLA or goal |
+| `referenceBands` | { axis, from, to, label, color }[] | — | Shaded ranges drawn behind the data, e.g. an acceptable range |
+| `xAxisLabel` | string | — | Label for the X axis |
+| `yAxisLabel` | string | — | Label for the Y axis |
+| `showGridLines` | boolean | `true` | Show horizontal/vertical grid lines |
+| `legend` | boolean | `true` | Show a legend (multi-series charts only) |
+
+### `generate_donut_chart`
+
+Generate a donut or pie chart showing parts of a whole. Example: data=[{"browser":"Chrome","share":65},{"browser":"Safari","share":19}], value="share", label="browser".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `value` | string | **required** | Field with the numeric value of each segment |
+| `label` | string | — | Field with the segment name (used for the legend) |
+| `variant` | `donut` \| `pie` | `"donut"` | Donut (ring) or full pie |
+| `arcWidth` | number | — | Ring thickness in pixels (donut variant only) |
+| `centralLabel` | string | — | Text in the middle of the donut |
+| `centralSubLabel` | string | — | Smaller text under the central label |
+| `padAngle` | number | `0` | Angular padding between segments, in radians |
+| `sortDescending` | boolean | `false` | Sort segments by value, largest first |
+| `showBackground` | boolean | `false` | Show a background ring behind the segments |
+| `legend` | boolean | `true` | Show a legend (requires the label field) |
+
+### `generate_timeline_chart`
+
+Generate a timeline (Gantt-style) chart of items with a start and an end (or duration), grouped into labeled rows. Use for schedules, project plans, traces, or event durations. Provide either an end field or a duration field. Example: data=[{"task":"Design","from":"2024-01-08","to":"2024-02-02"},...], row="task", start="from", end="to".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `row` | string | **required** | Field with the row (lane) name. Records sharing a row value are drawn in one lane |
+| `start` | string | **required** | Field with the item start: a number, or a date string (e.g. "2024-03-01") |
+| `end` | string | — | Field with the item end, same format as start. Provide either end or duration |
+| `duration` | string | — | Field with the item duration, in the same units as start (milliseconds when start is a date). Ignored when end is provided |
+| `timeIsDate` | boolean | — | Treat start/end values as dates (time axis). Auto-detected from the start field when omitted |
+| `showRowLabels` | boolean | `true` | Show the row names on the left |
+| `rowHeight` | number | `22` | Row height in pixels |
+| `lineWidth` | number | — | Thickness of the timeline bars in pixels. Defaults to a value derived from rowHeight |
+| `roundedEnds` | boolean | `false` | Draw the bars with rounded ends |
+| `alternatingRowColors` | boolean | `true` | Alternate the row background colors |
+| `xAxisLabel` | string | — | Label for the X axis |
+| `showGridLines` | boolean | `true` | Show horizontal/vertical grid lines |
+
+### `generate_boxplot`
+
+Generate a box-and-whisker plot comparing the distribution of a numeric value across groups. Pass raw (long-format) observations; quartiles, median, and Tukey whiskers (1.5×IQR, clamped to the data extent) are computed per group. Example: data=[{"service":"Auth","latency":132},{"service":"Auth","latency":89},{"service":"Search","latency":210},...], groupBy="service", value="latency".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `groupBy` | string | **required** | Field with the group/category of each observation (one box per distinct value) |
+| `value` | string | **required** | Field with the numeric value of each observation |
+| `boxPadding` | number | `0.25` | Fractional padding between boxes, 0..0.9 |
+| `boxMaxWidth` | number | — | Maximum box width in pixels |
+| `roundedCorners` | number | `2` | Corner radius of the boxes in pixels |
+| `xAxisLabel` | string | — | Label for the X axis |
+| `yAxisLabel` | string | — | Label for the Y axis |
+| `showGridLines` | boolean | `true` | Show horizontal/vertical grid lines |
+| `referenceLines` | { axis, value, label, color, lineWidth, style }[] | — | Reference lines for thresholds/targets, e.g. an SLA or goal |
+| `referenceBands` | { axis, from, to, label, color }[] | — | Shaded ranges drawn behind the data, e.g. an acceptable range |
+
+### `generate_sankey_diagram`
+
+Generate a Sankey diagram visualizing flows between stages/nodes (e.g. traffic, budgets, energy). Provide links as {source, target, value}; nodes are derived automatically. The graph must be acyclic. Example: links=[{"source":"Salary","target":"Budget","value":5000},{"source":"Budget","target":"Rent","value":2000}].
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `links` | { source, target, value }[] | **required** | Flows between nodes, e.g. [{"source":"A","target":"B","value":10}] |
+| `nodes` | { id, label }[] | — | Node definitions; derived from links when omitted |
+| `nodeWidth` | number | `25` | Node bar width in pixels |
+| `nodePadding` | number | `8` | Vertical padding between nodes |
+| `showValues` | boolean | `true` | Show node totals as sub-labels |
+| `valueSuffix` | string | `""` | Unit appended to node values, e.g. " GB" |
+
+### `generate_heatmap`
+
+Generate a heatmap: a grid of cells colored by value across two categorical dimensions (e.g. activity by weekday × hour). Missing row/column combinations render as empty cells. Example: data=[{"day":"Mon","hour":"9am","visits":34},{"day":"Mon","hour":"10am","visits":51}], row="day", column="hour", value="visits".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `row` | string | **required** | Field with the row category of each cell |
+| `column` | string | **required** | Field with the column category of each cell |
+| `value` | string | **required** | Field with the numeric cell value (drives the cell color) |
+| `colorRange` | [string, string] | — | [lowColor, highColor] hex pair; cell colors are interpolated between them. Defaults to a green sequence |
+| `cellPadding` | number | `2` | Gap between cells in pixels |
+| `cellCornerRadius` | number | `2` | Cell corner radius in pixels |
+
+### `generate_treemap`
+
+Generate a treemap of nested rectangles sized by value. Use for part-of-whole comparisons, optionally across hierarchy levels. Tiles are labeled "name: value". Example: data=[{"sector":"Tech","company":"Apple","cap":2900},{"sector":"Energy","company":"Shell","cap":210}], layers=["sector","company"], value="cap".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `layers` | string[] | **required** | Fields defining the hierarchy, top-level groups first, e.g. ["sector", "company"] |
+| `value` | string | **required** | Field with the numeric tile size |
+| `labelInternalNodes` | boolean | — | Show labels on the group (non-leaf) tiles. Defaults to true when there is more than one layer |
+| `tilePadding` | number | `2` | Padding between tiles in pixels |
+
+### `generate_chord_diagram`
+
+Generate a chord diagram visualizing weighted relationships within one set of entities (e.g. trade between countries, brand switching, team interactions). Provide links as {source, target, value}; nodes are derived automatically. Self-links (source === target) are not supported. Example: links=[{"source":"Apple","target":"Samsung","value":8},{"source":"Samsung","target":"Apple","value":14}].
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `links` | { source, target, value }[] | **required** | Weighted connections between nodes, e.g. [{"source":"A","target":"B","value":10}] |
+| `nodes` | { id, label }[] | — | Node definitions; derived from links when omitted |
+| `nodeWidth` | number | `15` | Thickness of the node arcs in pixels |
+| `padAngle` | number | `0.02` | Angular padding between nodes, in radians |
+| `cornerRadius` | number | `2` | Corner radius of the node arcs in pixels |
+| `labelAlignment` | `along` \| `perpendicular` | `"along"` | Node labels drawn along the arcs, or radiating outwards perpendicular to them |
+
+### `generate_nested_donut_chart`
+
+Generate a nested donut (sunburst) chart showing hierarchical part-of-whole data as concentric rings, innermost ring first. Segments are sized by the value field, or by record count when it is omitted. Example: data=[{"region":"EMEA","country":"Germany","sales":420},{"region":"EMEA","country":"France","sales":310}], layers=["region","country"], value="sales".
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `layers` | string[] | **required** | Fields defining the hierarchy rings, innermost ring first, e.g. ["region", "country"] |
+| `value` | string | — | Field with the numeric segment weight. Records are counted when omitted |
+| `centralLabel` | string | — | Text in the middle of the donut |
+| `centralSubLabel` | string | — | Smaller text under the central label |
+| `layerPadding` | number | `0` | Gap between rings in pixels |
+| `cornerRadius` | number | `0` | Segment corner radius in pixels |
+| `showSegmentLabels` | boolean | `true` | Show the category name on each segment (labels that do not fit are hidden) |
+
+### `generate_radial_bar_chart`
+
+Generate a radial bar chart (activity rings): one concentric ring per record, filled proportionally to its value. Good for progress toward goals or comparing a few values. Example: data=[{"metric":"Move","pct":84},{"metric":"Exercise","pct":62}], value="pct", label="metric", maxValue=100.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `data` | object[] | **required** | Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...] |
+| `value` | string | **required** | Field with the numeric value of each ring |
+| `label` | string | — | Field with the ring name (used for the legend) |
+| `maxValue` | number | — | Value at which a ring forms a full circle. Defaults to the largest value in the data |
+| `arcWidth` | number | `16` | Ring thickness in pixels |
+| `arcPadding` | number | `4` | Gap between rings in pixels |
+| `cornerRadius` | number | — | Rounded bar ends, in pixels. Defaults to half the ring thickness |
+| `centralLabel` | string | — | Text in the middle of the rings |
+| `centralSubLabel` | string | — | Smaller text under the central label |
+| `showBackground` | boolean | `true` | Show a faded full-circle track behind each ring |
+| `legend` | boolean | `true` | Show a legend (requires the label field) |
+
+### `generate_network_graph`
+
+Generate a network graph (node-link diagram) of relationships between entities — topologies, dependencies, hierarchies, social networks. Nodes are colored by their optional group. Use layout "force" for general networks, "circular"/"concentric" for symmetric views. Example: nodes=[{"id":"api","group":"service"},{"id":"db","group":"storage"}], links=[{"source":"api","target":"db"}].
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `nodes` | { id, label, group, size, subLabel }[] | **required** | Graph nodes, e.g. [{"id":"gw","label":"Gateway","group":"service"}] |
+| `links` | { source, target, label, width }[] | **required** | Edges between nodes by id, e.g. [{"source":"gw","target":"db"}] |
+| `layout` | `force` \| `circular` \| `concentric` | `"force"` | Node placement: force (organic, general networks), circular (single ring), concentric (one ring per group) |
+| `nodeSize` | number | `22` | Default node diameter in pixels |
+| `showLabels` | boolean | `true` | Show node labels |
+| `linkArrows` | boolean | `false` | Draw source → target arrowheads on links |
+| `linkWidth` | number | `1.5` | Default link stroke width in pixels |
+| `legend` | boolean | `true` | Show a legend when nodes have groups |
+
+### `generate_choropleth_map`
+
+Generate a choropleth map: geographic areas (countries, states, regions) shaded by value. Supports the world map plus USA, Germany, UK, France, India and China. Example: map="world", data=[{"id":"US","value":21},{"id":"BR","value":85},{"id":"Germany","value":46}].
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `map` | `world` \| `usa` \| `germany` \| `uk` \| `france` \| `india` \| `china` | `"world"` | Which map to draw. Area ids: world — ISO 3166-1 alpha-2 codes or country names; usa — state names, USPS abbreviations or FIPS codes; germany/france/india — ISO 3166-2 codes or names; uk — statistical regions by name; china — province names |
+| `data` | { id, value }[] | **required** | One entry per area, e.g. [{"id":"US","value":21},{"id":"Germany","value":46}] |
+| `colorRange` | [string, string] | — | [lowColor, highColor] hex pair; area colors are interpolated between them. Defaults to a blue ramp |
+| `valueLabel` | string | `""` | Unit for legend labels, e.g. "%" or " GWh" |
+
+## `get_unovis_info`
+
+Returns server capabilities: the active tool list, supported themes, output
+types, frameworks and the default color palette. Useful for a client (or an
+agent) to discover what this deployment can do before calling anything.

package/docs/troubleshooting.md

@@ -0,0 +1,140 @@
+# Troubleshooting
+
+## The first render is slow
+
+Expected. The first call initialises jsdom, imports `@unovis/ts`, and downloads
+Inter once (~34MB into `~/.cache/unovis-mcp/fonts/`). Later renders are
+milliseconds. To avoid the download entirely:
+
+```bash
+UNOVIS_MCP_NO_DOWNLOAD=1 unovis-mcp          # system fonts instead
+UNOVIS_MCP_FONTS_DIR=/path/to/fonts unovis-mcp   # your own fonts
+```
+
+If a client enforces a strict tool-call timeout, do one warm-up render after
+starting the server.
+
+## Text looks slightly wrong: clipped, trimmed, or oddly spaced
+
+Text measurement drives label trimming, wrapping and axis margins, so the font
+used for measuring must match the font used for drawing.
+
+- **In SVG/PNG output**, measurement uses the provisioned Inter. If you replaced
+  it via `UNOVIS_MCP_FONTS_DIR` with metrics that differ from the declared font
+  stack, labels can be trimmed too eagerly or overflow.
+- **In interactive HTML**, the viewer's machine supplies the font. Text may be a
+  few pixels different from the SVG. Nothing to fix — just don't expect them to
+  be pixel-identical.
+
+## A chart is blank
+
+Work through these in order:
+
+1. **Is it an interactive chart in a background tab?** Browsers pause
+   `requestAnimationFrame` for hidden pages, and Unovis renders through it. The
+   chart appears when the tab becomes visible. This also means automated
+   screenshots of hidden pages come out empty — make the page visible first.
+2. **Are you calling `renderToSvg` without wiring `onRenderComplete`?** The
+   render throws with that exact message; pass `ctx.onRenderComplete` into the
+   container config.
+3. **Is the data empty, or are the field names wrong?** The tools validate field
+   names and reply with the available fields; a hand-written spec does not.
+4. **Async layout?** A `Graph` with `layoutType: 'force'` needs
+   `ctx.requireComponentReady()` plus the component's `onRenderComplete`.
+
+## "Chart rendering did not complete"
+
+The container never reported finishing. Either `onRenderComplete` isn't wired
+(see above), or a component threw during a frame — the error message includes any
+frame errors that were captured.
+
+## Graph layouts
+
+`generate_network_graph` offers `force`, `circular`, `concentric` and `dagre`,
+and all four work in static output *and* interactive output.
+
+**ELK** is the exception. It renders fine in Node through a hand-written spec:
+
+```ts
+components: [{ type: 'Graph', config: { layoutType: 'elk', layoutElkSettings: { 'elk.algorithm': 'layered' } } }]
+```
+
+…but it isn't a tool option, because elkjs is a 1.4MB engine loaded through a
+dynamic import that the single-file widget bundle would have to inline. Offering
+it would mean `outputType: "html"` silently producing a broken chart.
+
+> Dagre required `@unovis/graphlibrary` ≥ 2.2.0-3 and
+> `@unovis/dagre-layout` ≥ 0.8.8-3. Earlier releases shipped extensionless ESM
+> imports that no standards-compliant Node loader could resolve.
+
+## The `tsx` loader can't load graph layouts
+
+Running this package's **source** through `tsx` fails on the dynamic imports
+inside Unovis's graph layouts: the layout promise never settles, so the render
+times out after 20 seconds with "component layout never completed". Plain Node
+and vitest both work.
+
+That's why `pnpm dev` and `pnpm samples` build first and run the compiled
+output. `pnpm dev:tsx` is available for fast iteration, with the caveat that
+graph charts will not render under it.
+
+## PNG has a transparent background
+
+Pass one. CSS `background-color` isn't an SVG rendering attribute, so rasterizers
+ignore it:
+
+```ts
+await svgToPng(svg, { width, scale: 2, background: themeBackground('dark') })
+```
+
+The `png` output type does this for you.
+
+## Interactive output doesn't render in my client
+
+`outputType: "interactive"` depends on MCP UI resource support, which is
+experimental and unevenly implemented. Use `outputType: "html"` — it works
+everywhere because it's just a file.
+
+## Large datasets
+
+Data arrives inside the tool call, so it passes through the model's context.
+Hundreds of rows are comfortable; tens of thousands are wasteful; millions are
+the wrong tool — aggregate first, or use the library directly
+([Programmatic use](./programmatic.md)) where data never touches a model.
+
+## Charts touch the image edges / I want no padding
+
+Static output frames the chart with 16px sides and bottom, 12px top. Via the
+library you can change it:
+
+```ts
+await renderToSvg({ width: 800, height: 400, padding: { top: 0, right: 0, bottom: 0, left: 0 } }, build)
+```
+
+## Multiple charts in one HTML document collide
+
+They shouldn't — ids are rewritten with a per-render prefix specifically to make
+that safe. If you need byte-stable output (snapshot tests), pass a constant
+`idPrefix`.
+
+## Something renders differently than in the browser
+
+Report it. The headless environment reimplements browser geometry, so a mismatch
+is a real bug in this package (or occasionally in Unovis, where several have
+already been found and fixed upstream). Useful details: the chart spec, the
+output, and what you expected.
+
+## What the tests don't cover
+
+Worth knowing before you trust a green suite:
+
+- **Real-browser rendering of interactive output.** The jsdom tests execute the
+  real widget bundle, but jsdom has no layout or paint: no pixel positions, no
+  transitions, and `ResizeObserver` is stubbed. A crosshair bug that jsdom passed
+  was found only by opening a real browser.
+- **MCP UI widget rendering** in an actual client.
+- **Visual regression.** Snapshots catch structural drift, not "this looks
+  wrong". `pnpm samples` exists for human review.
+- **Non-`ts` code targets aren't compiled.** The vanilla-TypeScript output is
+  type-checked against `@unovis/ts`; the JSX and template targets are checked
+  structurally only.

package/fonts/README.md

@@ -0,0 +1,19 @@
+# Fonts
+
+Text measurement drives label trimming, wrapping and axis margins, so the
+server measures with the same font the output declares (Unovis defaults to
+the Inter stack). Fonts are resolved in this order (see `src/env/fonts.ts`):
+
+1. `UNOVIS_MCP_FONTS_DIR` — an explicit directory of font files
+2. **this directory** — any `.ttf` / `.otf` / `.woff` files placed here are
+   registered at startup; the family name is derived from the file name
+   (`Inter-Regular.ttf` → `Inter`)
+3. a user-level cache (`~/.cache/unovis-mcp/fonts/`), populated automatically
+   on first start by downloading the official
+   [Inter release](https://github.com/rsms/inter) — pinned version, SHA-256
+   verified, licensed under the SIL Open Font License 1.1 (the license file
+   is stored alongside the fonts)
+
+Set `UNOVIS_MCP_NO_DOWNLOAD=1` to disable the download; the server then falls
+back to system fonts (metrics are close, but label trimming can differ by a
+few pixels from browser output).