For LLMs

Agents should treat ChartBuddy as a render-and-verify tool, not a config-only abstraction.

Required import path

import { Insight, getInsights, snapshotInsights } from 'https://unpkg.com/@chartbuddy.io/embed';

Rules:

• Create charts with new Insight(target, options) — this is the only entry point
• Prefer the single-file build (package root resolves there)
• Always pass a stable instanceId when you will observe or persist (duplicates throw)
• Do not pass assetBase on this path
• Do not expect a spreadsheet UI

Canonical agent doc

Fetch and follow:

• https://unpkg.com/@chartbuddy.io/embed/llms.txt
• https://cb-acc.xyz/llms.txt
• https://cb-acc.xyz/embed/docs/

Visual QA / observation loop

1. Mount with realistic container size (e.g. 800×480 for slides) and a stable instanceId
2. await insight.ready (or insight.on('ready', …))
3. Observe (preferred — no Save dialog):

const insight = window.__CHARTBUDDY_INSIGHTS__['revenue'];
const cd = insight.getChartData();
const png = await insight.toPngBase64(); // raw base64; default background #ffffff
// or: await insight.toPngBase64({ background: '#0f172a' })

4. Fix chartData from what you see (orientation, ticks, subtitle clutter)
5. Apply a partial update — you do not need a full payload:

insight.setData([['', 'Q1'], ['Revenue', 120]]); // data only
insight.update({ title: { text: 'FY26' } });     // any partial

6. Write deck.charts.json / exports/*.png into the workspace yourself — ChartBuddy does not rewrite HTML

Prefer toPngBase64 / getChartData over screenshots or downloadPng(). Pass background on PNG helpers for visual QA — chartData.backgroundColor is not baked into exports.

Check before you mount

Do not use a blank chart as your error signal. Validate the config you generated and repair it from the structured issues:

import { validateChartData } from 'https://unpkg.com/@chartbuddy.io/embed';

const { valid, errors, warnings } = validateChartData(candidate);
// errors[i] = { path, code, message, expected?, received?, allowed?, suggestion? }

Branch on code, never on message:

code	What to do
unknown-chart-type, not-in-enum	Use issue.suggestion, or pick from issue.allowed
wrong-type, out-of-range	Coerce / clamp to issue.expected
series-data-shape	Reshape the grid; expected names the row/column minimum
ragged-series-data	Warning — pad the short rows
foreign-option-bag	Move the options into the bag named in suggestion

If you mount without checking, the same problems throw a ChartDataValidationError whose .errors holds the identical issue objects — so either path gives you a machine-readable repair. Full reference: Validation.

Better still, constrain generation up front with @chartbuddy.io/embed/chart-schema.json, which describes every field the validator checks.

See Visual QA for AI.

Checklist

• subtitle: { visible: false, text: '' } unless you want a subtitle
• isDataTransposed: true for bar / line / area layouts in the docs
• Horizontal bars need orientation: 'horizontal'
• persist: false in fixtures so localStorage does not hide bugs
• Unique instanceId when using multi-mount, persist, or agent CDP hooks
• Prefer setData / update for refreshes — chartType is optional on partials
• Run validateChartData() on generated configs before mounting, and repair from issue.code / issue.suggestion