# Chartbuddy Embed

> Embed Chartbuddy charts in HTML via `new Insight()`. Pass `chartData` with a 2D `seriesData` grid. Spreadsheet UI is not included.

Start here, then follow links. Do not load `llms-full.txt` by default.

Hard rules:
- Create with **new Insight()** (not createChart / renderChart / mountChart).
- Prefer the package root import: `import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed'`.
- Mount elements need a definite width and height (prefer aspect-ratio or fixed px).
- `chartData` is `{ chartType, seriesData, ... }`. `seriesData` is a 2D array of string/number cells (spreadsheet grid), not `{ name, data }` series objects.
- `chartType` is camelCase (`clusteredBar`, not `clustered-bar`). Copy this shell; do not invent datasets:

```js
{
  chartType: 'clusteredBar',
  isDataTransposed: true,
  seriesData: [
    ['', 'Q1', 'Q2'],
    ['Revenue', 100, 120],
  ],
}
```

- Use the correct option bag for the chart type (`bar` on a `pie` throws).
- Hide bar/stack numbers with `annotations.totals.visible: false`. Do not invent `showTotalLabels` or `dataLabels.showTotal`. See [Labels](https://chartbuddy.io/embed/docs/configuration/labels.md).
- Validate with `validateChartData(cd)` and branch on issue `code`, never message text.
- PNG underlay: `toPngBase64({ background })` – do not rely on `chartData.backgroundColor` alone.
- Before generating more than this shell, fetch [Quick start](https://chartbuddy.io/embed/docs/getting-started/quick-start.md) and [chartData schema](https://chartbuddy.io/embed/docs/api/chart-data.md); add the chart-type and axes `.md` pages you need.

## Must read

- [chart-schema.json](https://unpkg.com/@chartbuddy.io/embed/chart-schema.json): Machine-readable chartData contract (types, enums, ranges)
- [Package README](https://unpkg.com/@chartbuddy.io/embed/README.md): Human package overview + public API surface
- [Quick start](https://chartbuddy.io/embed/docs/getting-started/quick-start.md): Create your first chart with `new Insight()`
- [chartData schema](https://chartbuddy.io/embed/docs/api/chart-data.md): Fields, seriesData layouts, option bags, pitfalls
- [Labels](https://chartbuddy.io/embed/docs/configuration/labels.md): Totals vs data labels vs series names (`annotations.totals.visible`)
- [Validation](https://chartbuddy.io/embed/docs/quality-assurance/validation.md): Check `chartData` before mount; fix by issue `code`
- [Docs index](https://chartbuddy.io/embed/docs/llms.txt): Hosted twin of this index (same content)

## Getting Started

- [Introduction](https://chartbuddy.io/embed/docs/getting-started.md): What Embed is and where to start
- [Installation](https://chartbuddy.io/embed/docs/getting-started/installation.md): npm, CDN, single-file vs multi-file
- [Quick start](https://chartbuddy.io/embed/docs/getting-started/quick-start.md): Create your first chart with `new Insight()`
- [View vs edit mode](https://chartbuddy.io/embed/docs/getting-started/view-vs-edit.md): Display-only chart vs interactive formatting (`editable`, `allowEdit`, `editSession`)

## Chart with AI

- [Overview](https://chartbuddy.io/embed/docs/connect-ai.md): Which docs agents should load first (and what to skip)
- [Cursor](https://chartbuddy.io/embed/docs/connect-ai/cursor.md): How to brief Cursor agents to build Embed pages
- [Claude](https://chartbuddy.io/embed/docs/connect-ai/claude.md): How to use Chartbuddy inside Claude HTML outputs
- [Claude Code](https://chartbuddy.io/embed/docs/connect-ai/claude-code.md): How Claude Code agents should fetch docs and mount charts
- [OpenCode](https://chartbuddy.io/embed/docs/connect-ai/opencode.md): How OpenCode agents should use Embed docs and mount charts
- [ChatGPT / Codex](https://chartbuddy.io/embed/docs/connect-ai/chatgpt-codex.md): How Codex / ChatGPT agents should fetch docs and mount charts

## Chart types

- [Overview](https://chartbuddy.io/embed/docs/chart-types.md): Canonical types and which option bag each reads
- [Clustered bar](https://chartbuddy.io/embed/docs/chart-types/clustered-bar.md): Side-by-side bars; `cd.bar`
- [Stacked bar](https://chartbuddy.io/embed/docs/chart-types/stacked-bar.md): Absolute and 100% stacks; `cd.bar`
- [Line](https://chartbuddy.io/embed/docs/chart-types/line.md): Lines, dual-axis, markers; `cd.line`
- [Stacked area](https://chartbuddy.io/embed/docs/chart-types/stacked-area.md): Filled stacked areas; options live in `area`
- [Pie / donut](https://chartbuddy.io/embed/docs/chart-types/pie.md): Category shares; `donut` is a pie with a hole
- [Scatter / bubble](https://chartbuddy.io/embed/docs/chart-types/scatter.md): X/Y point charts; `bubble` adds marker size
- [Waterfall](https://chartbuddy.io/embed/docs/chart-types/waterfall.md): Running-total contribution charts; mark totals, don't type closing values
- [Marimekko](https://chartbuddy.io/embed/docs/chart-types/mekko.md): 100% stacked columns with variable category widths
- [Bar Mekko](https://chartbuddy.io/embed/docs/chart-types/bar-mekko.md): Variable-width columns with absolute (not %) heights
- [Combo](https://chartbuddy.io/embed/docs/chart-types/combo.md): Mixed series via `combo.seriesTypes`

## Axes

- [Overview](https://chartbuddy.io/embed/docs/axes.md): Which axis does what, and how that changes when the chart flips
- [Value axis](https://chartbuddy.io/embed/docs/axes/value-axis.md): `customMin` / `customMax`, ticks, number formats
- [Domain axis](https://chartbuddy.io/embed/docs/axes/domain.md): Categories or linear X (scatter / mekko width)
- [Titles & chrome](https://chartbuddy.io/embed/docs/axes/titles-and-chrome.md): Axis titles, tick marks, and axis line styling
- [Secondary / dual axis](https://chartbuddy.io/embed/docs/axes/secondary.md): Two value scales on one chart (`boundSeries`)
- [Axis breaks](https://chartbuddy.io/embed/docs/axes/breaks.md): Collapse a gap on the value axis
- [By chart type](https://chartbuddy.io/embed/docs/axes/by-chart-type.md): Which axes each chart type exposes or hides

## API / schema

- [Insight API](https://chartbuddy.io/embed/docs/api.md): `new Insight`, update, events, PNG helpers
- [chartData schema](https://chartbuddy.io/embed/docs/api/chart-data.md): Full field and layout reference
- [Helpers](https://chartbuddy.io/embed/docs/api/helpers.md): Look up live Insights and export a multi-chart snapshot
- [Single vs multi mounts](https://chartbuddy.io/embed/docs/api/multi-mount.md): Several charts on one page vs one self-contained script; stable `instanceId`
- [Validation](https://chartbuddy.io/embed/docs/quality-assurance/validation.md): Check `chartData` before mount; fix by issue `code`
- [Visual QA](https://chartbuddy.io/embed/docs/quality-assurance/visual-qa.md): Mount, check layout, export PNG/JSON, then fix config

## Samples

- [Gallery](https://chartbuddy.io/embed/docs/samples.md): Live sample index
- [Clustered bar](https://chartbuddy.io/embed/docs/samples/clustered-bar.md): Minimal ready-to-paste HTML for clustered bar
- [Line](https://chartbuddy.io/embed/docs/samples/line.md): Minimal ready-to-paste HTML for line
- [Dual-axis line](https://chartbuddy.io/embed/docs/samples/dual-axis-line.md): Secondary axis with `boundSeries`
- [Combo](https://chartbuddy.io/embed/docs/samples/combo.md): Bar + line on one chart
- [Dashboard](https://chartbuddy.io/embed/docs/samples/dashboard.md): Multiple Insights with `instanceId`

## Optional

- [Full docs bundle](https://chartbuddy.io/embed/docs/llms-full.txt): Entire docs site in one file – skip unless you need a single blob
- [Configuration](https://chartbuddy.io/embed/docs/configuration.md): Titles, legend, labels, difference/CAGR arrows, level lines, number formats
- [Labels](https://chartbuddy.io/embed/docs/configuration/labels.md): Hide bar/stack totals; do not invent `showTotalLabels`
- [React](https://chartbuddy.io/embed/docs/guides/react.md): `@chartbuddy.io/embed/react` binding
- [Vue](https://chartbuddy.io/embed/docs/guides/vue.md): `@chartbuddy.io/embed/vue` binding
- [Angular & web components](https://chartbuddy.io/embed/docs/guides/angular.md): `<chartbuddy-insight>` custom element