@blueprint-chart/docs 0.1.18

package/src/guide/accessibility.md

@@ -0,0 +1,196 @@
+---
+title: Accessibility
+---
+
+# Accessibility
+
+> WCAG contrast checks, colour-vision-deficiency simulation, and palette-safety audits — built into the library.
+
+## Why this matters
+
+Around 8% of men and 0.5% of women have some form of colour vision deficiency. Many readers consume charts at thumbnail sizes, in dim rooms, or in dark mode. Blueprint Chart bakes the toolkit for these cases into `@blueprint-chart/lib`: WCAG contrast ratio + grading, automatic palette tuning for the actual background, programmatic CVD simulation, and an SVG filter you can drop on a live chart for instant preview.
+
+## Quickstart
+
+Audit a colour pair, then a whole palette:
+
+```ts
+import {
+  wcagContrastRatio,
+  wcagLevel,
+  resolvePalette,
+  checkCvdColors,
+} from '@blueprint-chart/lib'
+
+const ratio = wcagContrastRatio('#ffffff', '#2563A0')
+wcagLevel(ratio) // 'AA' — 4.5 ≤ ratio < 7
+
+const palette = resolvePalette('Egypt')!
+const issues = checkCvdColors(palette)
+// issues is empty if every pair stays distinguishable under
+// protanopia / deuteranopia / tritanopia (ΔE ≥ 10)
+```
+
+In the editor, the CVD toggle in the toolbar swaps in an SVG filter so authors can preview their chart through each dichromacy live. No layout shift; the chart stays interactive.
+
+## How it works
+
+Two toolkits ship from `packages/lib/src/charts/`:
+
+- **`contrast.ts`** — WCAG 2.1 contrast ratio (`wcagContrastRatio`) and grading (`wcagLevel` → `'AAA' | 'AA' | 'Fail'`). It also provides `resolveBackgroundColor(el)` which walks up the DOM until it finds a non-transparent background, and `adjustColorsForBackground(colors, bg)` which nudges palette lightness until every entry clears WCAG AA against the background **and** every adjacent pair has a CIE2000 deltaE of at least 12. Hue and saturation are preserved; only lightness moves.
+
+- **`colorblind.ts`** — Three Viénot dichromacy matrices (`protanopia`, `deuteranopia`, `tritanopia`) applied two ways: programmatically by `simulateCvdColor(hex, type)` (linearise sRGB → matrix multiply → companding) and at render time via `createCvdSvgFilter(type)`, which builds an `<feColorMatrix>` filter you apply through CSS `filter: url(#bc-cvd-deuteranopia)`. Both paths share the same matrices, so on-screen preview matches programmatic checks.
+
+`checkCvdColors(palette)` runs `simulateCvdColor` over every pair, for every dichromacy, and reports any pair whose simulated colours collapse below ΔE 10 — the threshold where chart marks start to read as "the same colour".
+
+> [!warning]
+> The `CvdType` union covers the three dichromacies only — `'protanopia' | 'deuteranopia' | 'tritanopia'`. The editor's UI toggle includes an "off" state, but the typed surface in `colorblind.ts` has three values.
+
+## Recipes
+
+### Audit a palette before publishing
+
+A common build-time check: pick a palette, validate it against the background you actually ship on, and flag CVD collisions.
+
+```ts
+import {
+  resolvePalette,
+  wcagContrastRatio,
+  wcagLevel,
+  checkCvdColors,
+} from '@blueprint-chart/lib'
+
+const palette = resolvePalette('Blueprint')!
+const bg = '#ffffff'
+
+const contrastReport = palette.map((color) => ({
+  color,
+  ratio: wcagContrastRatio(color, bg),
+  level: wcagLevel(wcagContrastRatio(color, bg)),
+}))
+
+const cvdIssues = checkCvdColors(palette)
+if (cvdIssues.length > 0) {
+  for (const issue of cvdIssues) {
+    console.warn(issue.label, issue.pairs)
+  }
+}
+```
+
+### Audit a sample chart's hand-picked colours
+
+The medal-count sample uses three hand-picked metallic colours — gold, silver, bronze. The same three colours are exactly the case where CVD audit matters: under deuteranopia, yellow and white-grey can pull close on the L* axis. Drop the inline `colors` list straight into the audit:
+
+```bpc
+chart bar-multi {
+  title = "USA tops Paris 2024 with 126 medals across all categories"
+  colors = "#eeca3b, #c0c0c0, #cd7f32"
+  legendPosition = "top"
+
+  data {
+    _series = "Gold","Silver","Bronze"
+    "USA" = 40,44,42
+    "China" = 38,32,18
+  }
+}
+```
+
+::: tip From the sample library
+Trimmed from `packages/lib/src/samples/medal-count.bpc` (the full sample lists the top six nations). The three hand-picked hex colours are the audit input — none of them resolve through `resolvePalette()`, so pull them straight from the DSL string.
+:::
+
+```ts
+import { checkCvdColors, wcagContrastRatio } from '@blueprint-chart/lib'
+
+const medalColors = ['#eeca3b', '#c0c0c0', '#cd7f32']
+
+const cvdIssues = checkCvdColors(medalColors)
+const onLight = medalColors.map((c) => wcagContrastRatio(c, '#ffffff'))
+// Silver (#c0c0c0) clears 1.6:1 on white — under WCAG AA it would fail for
+// thin marks. Pair it with a label or border, or substitute a CVD-safe
+// palette like `Blueprint` if you're not committed to medal colours.
+```
+
+The sample ships these colours because the semantic mapping (gold = 1st, bronze = 3rd) is part of the story. When that semantic mapping isn't worth defending, swap to a CVD-checked named palette via `colorPalette = "<name>"` instead.
+
+### Build a CVD-safe palette from scratch
+
+`checkCvdColors` returns the pairs that need attention. The cheapest fix is usually to vary lightness — keep the hues, but pull adjacent entries further apart on the L* axis. `adjustColorsForBackground` does exactly that for the WCAG dimension; you can apply it before running `checkCvdColors` to compress the failure surface:
+
+```ts
+import { adjustColorsForBackground, checkCvdColors } from '@blueprint-chart/lib'
+
+const tuned = adjustColorsForBackground(myCandidates, '#0a0a0a')
+const remainingIssues = checkCvdColors(tuned)
+```
+
+If a pair still collides, replace one entry or pair the encoding with a non-colour affordance (direct label, shape, pattern). The [accessibility handbook](/handbook/accessibility) calls this out as the most important rule: never encode information in a single visual channel.
+
+### Auto-tune chart marks to the actual background
+
+Opt a chart into automatic contrast adjustment by setting `autoContrast = true` in the DSL. At render time the engine calls `resolveBackgroundColor(container)` on the chart's frame and runs `adjustColorsForBackground` over the resolved palette before the chart-type renderer paints marks. Same `.bpc` source works in light and dark themes.
+
+### Preview a chart under CVD in a non-editor consumer
+
+The SVG filter pattern works in any DOM context — drop the filter into your page once, then toggle the `filter` style on the chart container.
+
+```ts
+import { createCvdSvgFilter, getCvdFilterId, type CvdType } from '@blueprint-chart/lib'
+
+function installCvdFilter(type: CvdType) {
+  const ns = 'http://www.w3.org/2000/svg'
+  let host = document.querySelector<SVGSVGElement>('#bc-cvd-host')
+  if (!host) {
+    host = document.createElementNS(ns, 'svg')
+    host.id = 'bc-cvd-host'
+    host.style.position = 'absolute'
+    host.style.width = '0'
+    host.style.height = '0'
+    document.body.appendChild(host)
+  }
+  host.appendChild(createCvdSvgFilter(type))
+}
+
+installCvdFilter('deuteranopia')
+chartContainer.style.filter = `url(#${getCvdFilterId('deuteranopia')})`
+```
+
+### Validate text contrast on titles, axes, and annotations
+
+WCAG AA wants 4.5:1 for body text, 3:1 for large text (18px+ bold or 24px+ regular). `wcagContrastRatio` accepts any chroma-parseable input — hex, named colours, `rgb(…)` — so it pairs well with `getComputedStyle()`:
+
+```ts
+import { wcagContrastRatio, wcagLevel } from '@blueprint-chart/lib'
+
+function checkLabel(labelEl: HTMLElement) {
+  const style = getComputedStyle(labelEl)
+  const ratio = wcagContrastRatio(style.color, style.backgroundColor || '#ffffff')
+  return { ratio, level: wcagLevel(ratio) }
+}
+```
+
+## API surface
+
+Exported from `@blueprint-chart/lib`:
+
+| Symbol | One-liner |
+| --- | --- |
+| `wcagContrastRatio(fg, bg)` | WCAG 2.1 relative-luminance ratio between two colours (1–21). |
+| `wcagLevel(ratio)` | Maps a ratio to `'AAA' \| 'AA' \| 'Fail'`. |
+| `resolveBackgroundColor(el)` | Walks ancestors until it finds a non-transparent background; falls back to `#fff`. |
+| `adjustColorsForBackground(colors, bg)` | Returns a copy of `colors` tuned for WCAG ≥ 4.5 and adjacent ΔE ≥ 12 against `bg`. |
+| `simulateCvdColor(hex, type)` | Returns the perceived hex under a given dichromacy. |
+| `createCvdSvgFilter(type)` | Builds an `<feColorMatrix>` filter element, applied via CSS `filter: url(#…)`. |
+| `getCvdFilterId(type)` | Deterministic filter id, e.g. `'bc-cvd-deuteranopia'`. |
+| `checkCvdColors(colors)` | Returns `CvdIssue[]` for every dichromacy where any pair collapses (ΔE < 10). |
+| `CvdType` (type) | `'protanopia' \| 'deuteranopia' \| 'tritanopia'`. |
+| `CvdIssue` (type) | `{ type, label, pairs: { a, b, deltaE }[] }`. |
+
+See [the API reference](/reference/api/#color-and-accessibility) for the full export list.
+
+## See also
+
+- [Accessibility handbook](/handbook/accessibility) — CVD, contrast, alt text, keyboard, multi-channel encoding.
+- [Palettes guide](/guide/palettes) — picking and overriding palettes.
+- [Colour handbook](/handbook/color) — the lightness-variance and blue-orange rules.
+- [BPC DSL — Properties](/reference/dsl/properties#properties) for `autoContrast`.

package/src/guide/data-transforms.md

@@ -0,0 +1,191 @@
+---
+title: Data Transforms
+---
+
+# Data Transforms
+
+> A composable pipeline that shapes raw tabular data into the rows the chart actually renders.
+
+## Why this matters
+
+Raw data is rarely chart-ready. Columns have the wrong types, rows need filtering, groups need aggregating, the table is the wrong way around. Blueprint Chart bakes a small **transform pipeline** into the editor so you can clean and reshape data inside the chart rather than juggling external spreadsheets. The same pipeline can also be expressed in the `.bpc` DSL via `transform` nodes, which means the cleaning step travels with the chart source.
+
+## Quickstart
+
+A `.bpc` chart with a single sort transform — the canonical example. The transform runs **before** the chart-type renderer paints marks:
+
+```bpc
+chart bar-vertical {
+  title = "Brazil produces more coffee than the next three countries combined"
+  description = "Million 60-kg bags, 2023/24 crop year"
+  colorPalette = "Harvey"
+  valueLabels = true
+
+  data {
+    "Brazil" = 66.4
+    "Vietnam" = 29
+    "Colombia" = 11.4
+    "Indonesia" = 9.9
+    "Ethiopia" = 8.7
+    "Honduras" = 6.3
+  }
+
+  colorize "Brazil" {
+    color = "#a4432d"
+  }
+
+  transform sort {
+    column = "value"
+    direction = descending
+  }
+}
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/coffee-production.bpc` — the only sample currently shipping with a `transform` block. The data is authored in arbitrary order on disk; `transform sort` flips it to descending before the bar-vertical renderer reads it.
+:::
+
+In the editor, the same pipeline is built interactively in the Data panel — each step appears as a card, can be reordered by drag, and is re-applied on every keystroke.
+
+## How it works
+
+The editor's pipeline lives in `packages/editor/src/stores/dataTransforms.ts` as a `dataTransforms` Pinia store. It holds an ordered array of `TransformStep` objects:
+
+```ts
+interface TransformStep {
+  id: string
+  type: TransformType   // 'sort' | 'filter' | 'hide-columns' | …
+  config: Record<string, string>
+}
+```
+
+A `TransformResult` (`{ columns, rows, columnTypes }`) flows through the pipeline. Each step is a pure function from `(result, config) → result`. The store exposes `applyTransforms(columns, rows, columnTypes)` which folds every step over the input, and `getColumnsAtStep(stepIndex, …)` which lets the UI show what the table will look like at any point in the chain — handy when configuring downstream steps that need the columns produced upstream.
+
+Eight transform types are recognised today (`Computed` is reserved but not implemented):
+
+| Type | Effect |
+| --- | --- |
+| `Sort` | Sort rows by one or more columns, ascending or descending. |
+| `Filter` | Keep rows matching a condition on a single column. |
+| `HideColumns` | Drop columns from the result. |
+| `Transpose` | Swap rows and columns. |
+| `Parse` | Re-type or reformat a column (e.g. parse numbers, normalise strings). |
+| `Rename` | Rename a column. |
+| `GroupBy` | Group rows by one or more columns and aggregate the rest. |
+| `Computed` | Reserved — not yet implemented. |
+
+When the chart is serialised back to `.bpc`, transform steps emit as `transform <name> { … }` blocks, parsed back into the AST as `TransformNode`s on the round-trip.
+
+## Recipes
+
+### Sort the data shown on the chart
+
+The cheapest cleanup. `transform sort` runs before the chart renders, so the bar order on disk doesn't need to match the visual order:
+
+```bpc
+transform sort {
+  column = "value"
+  direction = descending
+}
+```
+
+::: tip From the sample library
+Excerpted from `packages/lib/src/samples/coffee-production.bpc` (also the [quickstart](#quickstart) above). Drop a Sort step into the editor's Data panel and pick a column — it serialises to this same `transform sort` block on save.
+:::
+
+### Filter rows by a condition
+
+`Filter` supports five conditions (see `FilterCondition` in `packages/editor/src/enums.ts`):
+
+| Condition | Match |
+| --- | --- |
+| `equals` | Exact match (string compare). |
+| `not-equals` | Inverse of `equals`. |
+| `contains` | Substring, case-insensitive. |
+| `greater-than` | Numeric `>`; currency symbols and commas in the cell are stripped. |
+| `less-than` | Numeric `<`; same stripping. |
+
+The serialised form pairs a condition with a target column and value:
+
+```bpc
+transform filter {
+  column = "year"
+  condition = greater-than
+  value = "2000"
+}
+```
+
+::: warning No sample uses `transform filter` today
+The block above is synthesized from `packages/editor/src/utils/transforms/applyFilter.ts` rather than copied from a `.bpc` file — none of the 38 shipped samples filter their data on render. Treat the syntax as canonical (it round-trips through the editor) but expect to author it by hand for now.
+:::
+
+If the target value is empty for any condition other than `equals` / `not-equals`, the filter is a no-op (the row is kept).
+
+### Group rows and aggregate
+
+`GroupBy` collapses rows that share one or more group columns and folds the rest with an aggregate function. The `aggregates` config field is a comma-separated list of `column:fn` pairs — `fn` is one of `sum`, `avg`, `min`, `max`, `count`. For `count` the `column` is ignored.
+
+```bpc
+transform group-by {
+  groupColumns = "country"
+  aggregates   = "exports:sum,population:avg,exports:count"
+}
+```
+
+::: warning No sample uses `transform group-by` today
+Synthesized from `packages/editor/src/utils/transforms/applyGroupBy.ts` and `packages/editor/src/enums.ts` (`TransformType.GroupBy = 'group-by'`). Build the step in the editor's Data panel and copy the serialised output if you want a verified starting point.
+:::
+
+### Use the pipeline outside the editor
+
+The whole store is a plain Pinia composable. If you're building your own Vue app on top of `@blueprint-chart/editor` internals, import it directly and feed it any table:
+
+```ts
+import { useDataTransforms } from '@/composables/useDataTransforms'
+
+const { addStep, applyTransforms, snapshot, hydrate } = useDataTransforms()
+
+addStep(TransformType.Sort, { column: 'value', direction: 'descending' })
+addStep(TransformType.Filter, { column: 'year', condition: 'greater-than', value: '2000' })
+
+const { columns, rows, columnTypes } = applyTransforms(
+  inputColumns,
+  inputRows,
+  inputColumnTypes,
+)
+```
+
+`snapshot()` returns a serialisable copy of the pipeline; `hydrate(steps)` replaces it. The store also persists to local storage in the editor, so reload-survival is automatic in that context.
+
+### Validate a step before adding it
+
+`validateStep(step, columns, columnTypes)` returns either `null` (valid) or a human-readable string explaining why the step is misconfigured — column not found, missing required field, incompatible type for a `Parse` operation. The Data panel calls this on every config change to disable the Apply button.
+
+## API surface
+
+The transform pipeline lives in `@blueprint-chart/editor` rather than `@blueprint-chart/lib`. The `lib` half is the DSL representation:
+
+| Symbol (from `@blueprint-chart/lib`) | One-liner |
+| --- | --- |
+| `TransformNode` (type) | AST node for a `transform <name> { … }` block. |
+| `DslNodeType.Transform` (enum value) | Discriminator on the AST union. |
+
+The `editor` half (used internally by the editor app):
+
+| Symbol (from the editor) | One-liner |
+| --- | --- |
+| `useDataTransforms()` / `useDataTransformsStore()` | Pipeline composable + raw store. |
+| `TransformStep` (type) | `{ id, type, config }` — one row in the pipeline. |
+| `TransformType` (enum) | `Sort \| Filter \| HideColumns \| Transpose \| Parse \| Rename \| GroupBy \| Computed`. |
+| `TransformResult` (type) | `{ columns, rows, columnTypes }` — the value flowing through the chain. |
+| `ParseOperation` / `parseOperations` | Catalogue of `Parse` operations and their accepted input types. |
+| `NULL_VALUE` | Sentinel returned by `Parse` when a cell can't be coerced. |
+
+> [!info] Public-API status
+> The transform pipeline is currently shipped inside `@blueprint-chart/editor` and is consumed by the editor app. It is not re-exported from `@blueprint-chart/lib` today; if you need it in a non-editor consumer, copy `packages/editor/src/utils/transforms/*` or watch for a future move into `lib`.
+
+## See also
+
+- [BPC DSL — Transforms](/reference/dsl/scenes-and-transforms#transforms) for the source-level grammar.
+- [Scenes guide](/guide/scenes) — scenes can replace a chart's data wholesale; transforms operate before that swap.
+- [API reference](/reference/api/#dsl) for `TransformNode` and the converter helpers.

package/src/guide/dsl-editor.md

@@ -0,0 +1,218 @@
+---
+title: DSL Editor
+---
+
+# DSL Editor
+
+> The BPC source editor — CodeMirror 6, a Lezer-generated grammar, syntax highlighting tuned for prose-shaped charts, and two-way sync with the visual panels.
+
+## Why this matters
+
+Blueprint Chart is text-first. Every chart in the editor has a `.bpc` source under the hood, and any change you make through the visual panels — picking a palette, dragging an annotation, reordering scenes — is reflected back in that source. The DSL editor is the surface where authors who prefer code can stay in code, and the surface where a journalist swapping numbers can do it without ever opening a panel. CodeMirror 6 powers the editor; a separate Lezer grammar drives the syntax highlighting.
+
+## Quickstart
+
+Type `.bpc` directly in the editor's left pane. The right pane re-renders on every parse-clean keystroke:
+
+```bpc
+chart line {
+  title = "2024 was the hottest year on record"
+  description = "Deviation from the 1951–1980 average, in °C"
+  source = "NASA GISS"
+  sourceUrl = "https://data.giss.nasa.gov/gistemp/"
+  colors = "#e15759"
+  autoContrast = false
+  allowDarkMode = true
+  interpolation = "monotoneX"
+  lineSymbols = true
+  lineSymbolShape = "circle"
+  lineSymbolShowOn = "firstLast"
+
+  data {
+    "1980" = 0.26
+    "1985" = 0.12
+    "1990" = 0.45
+    "1995" = 0.45
+    "2000" = 0.42
+    "2005" = 0.68
+    "2010" = 0.72
+    "2015" = 0.9
+    "2020" = 1.02
+    "2024" = 1.29
+  }
+
+  annotation "2015" {
+    id = "2o3cx"
+    text = "2015 Paris Agreement to limit global warming to 1.5°C "
+    maxWidth = 224
+    showLine = true
+    lineStyle = curve-right
+    showArrow = true
+    showCircle = true
+  }
+}
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/temperature-anomaly.bpc` — a good stress test for the highlighter because it mixes every common token class: keywords (`chart`, `data`, `annotation`), identifiers (`autoContrast`, `lineSymbolShape`), strings, numbers, enum values (`monotoneX`, `firstLast`, `curve-right`), and booleans. The fold ranges align with each top-level block.
+:::
+
+Line comments use `//` and stop at end-of-line. There are no block comments.
+
+## How it works
+
+The editor runs **two parsers** for the same DSL surface, and the trade-off is deliberate:
+
+| Parser | Package | Job | Generation |
+| --- | --- | --- | --- |
+| Peggy | `@blueprint-chart/lib` | AST for chart computation at runtime — full semantics. | `make build-parser` |
+| Lezer | `@blueprint-chart/editor` | Incremental parse tree for syntax highlighting. | `pnpm --filter @blueprint-chart/editor build:parser` |
+
+Both grammars describe the same language. The Peggy one is the source of truth for correctness (parses, validates, round-trips); the Lezer one is built for fast incremental re-parse on every keystroke so the editor never blocks.
+
+The CodeMirror 6 stack pulls in `@codemirror/view`, `@codemirror/state`, `@codemirror/language`, and `@lezer/highlight`. The DSL language module lives at `packages/editor/src/dsl-lang/` and exposes three entry points:
+
+- `bpcLanguage()` — returns a CodeMirror `LanguageSupport` you install on the editor instance.
+- `bpcHighlighter` — a `syntaxHighlighting` extension pre-wired to the class-based highlighter.
+- `highlightDsl(code)` — one-shot server-style highlight, used by read-only previews; returns HTML.
+
+The Lezer parser tags DSL keywords (`chart`, `data`, `colorize`, `highlight`, `areafill`, `annotation`, `range`, `note`, `series`, `scene`, `step`, `transform`) and lexical tokens (`Identifier`, `String`, `Number`, `Percentage`, `Equals`, `LineComment`, braces). Each tag maps to a token class in `packages/editor/src/dsl-lang/highlight.scss`, with separate light- and dark-mode rules driven by the `--bc-syn-*` CSS custom properties.
+
+## Two-way sync between DSL and panels
+
+The editor keeps the DSL text and the visual panels in lockstep through two composables:
+
+- **`useDslSync`** — DSL → config and config → DSL. On every keystroke, a debounced parse runs; on success, the resulting AST is diffed against the `chartConfig` store and applied. The reverse direction kicks in when a user edits via a panel: the chart state is serialised back to DSL and pushed into the editor with a cursor-preserving patch.
+- **`useDslOutput`** — formats the current chart state into its canonical DSL string. This is what the "Copy as DSL" button and the export panel consume.
+
+Because the grammar round-trips cleanly (`parse(serialize(parse(x)))` is structurally equal to `parse(x)`), the sync loop is stable — a panel-driven change does not surprise the user with reformatted whitespace, and a DSL-driven change does not lose unknown property keys.
+
+## Recipes
+
+### Embed the BPC language in your own CodeMirror editor
+
+`bpcLanguage()` and `bpcHighlighter` are plain CodeMirror 6 extensions — they fit into any consumer that already builds a CodeMirror view:
+
+```ts
+import { EditorView, basicSetup } from 'codemirror'
+import { bpcLanguage, bpcHighlighter } from '@/dsl-lang'
+
+const view = new EditorView({
+  doc: '',
+  extensions: [
+    basicSetup,
+    bpcLanguage(),
+    bpcHighlighter,
+  ],
+  parent: document.querySelector('#editor')!,
+})
+```
+
+### Highlight a read-only DSL block
+
+For a docs page, a "view source" tab, or a tooltip preview, `highlightDsl(code)` returns ready-to-inject HTML:
+
+```ts
+import { highlightDsl } from '@/dsl-lang'
+
+const html = highlightDsl(`chart line-multi {
+  title = "Germany stagnated while the US and China bounced back"
+  description = "Annual percentage change in real GDP"
+  source = "IMF World Economic Outlook"
+  colorPalette = "SolLeWitt"
+  legend = false
+  tooltips = true
+
+  annotation "2020" {
+    text = "COVID-19 recession"
+    dy = -10
+    showArrow = true
+  }
+
+  data {
+    _series = "United States","China","Germany"
+    "2018" = 2.9,6.7,1.0
+    "2020" = -2.8,2.2,-3.7
+    "2024" = 2.8,5.0,-0.2
+  }
+}`)
+
+document.querySelector('#preview')!.innerHTML = html
+```
+
+::: tip From the sample library
+The DSL string is trimmed from `packages/lib/src/samples/gdp-growth.bpc` (full sample has the 2018–2024 yearly series). Good stress-case for the highlighter — multi-series data, palette name, a negative number, an annotation block.
+:::
+
+This skips the editor surface entirely and is the right tool when the user shouldn't be able to type.
+
+### Parse the editor's content programmatically
+
+To act on the DSL outside the editor — validate, transform, or feed it to a renderer — pair `bpcLanguage()` with the lib's `parse()`:
+
+```ts
+import { parse } from '@blueprint-chart/lib'
+
+try {
+  const ast = parse(view.state.doc.toString())
+  // ast.chartType, ast.properties, ast.data, ast.scenes …
+} catch (err) {
+  // SyntaxError with 1-indexed location { line, column }
+}
+```
+
+Errors are `SyntaxError` instances with a 1-indexed `location` field. CodeMirror's `lintGutter` extension is the natural place to surface them.
+
+### Read the Lezer tree directly
+
+Autocomplete is not exposed by default, but the Lezer parse tree is available if you want to write a completion source, a custom folding range provider, or any other syntax-driven feature:
+
+```ts
+import { syntaxTree } from '@codemirror/language'
+
+const tree = syntaxTree(view.state)
+tree.iterate({
+  enter(node) {
+    if (node.name === 'Property') {
+      // … node.from / node.to give you the document range
+    }
+  },
+})
+```
+
+## Files in the package
+
+The DSL language module ships inside `@blueprint-chart/editor`:
+
+- `packages/editor/src/dsl-lang/bpc.grammar` — Lezer grammar source.
+- `packages/editor/src/dsl-lang/bpc-parser.js` — generated Lezer parser (committed to the repo).
+- `packages/editor/src/dsl-lang/build.mjs` — grammar build script.
+- `packages/editor/src/dsl-lang/index.ts` — exports `bpcLanguage()`, `bpcHighlighter`, `highlightDsl()`.
+- `packages/editor/src/dsl-lang/highlight.scss` — token-class colour definitions, driven by `--bc-syn-*` CSS variables.
+
+## API surface
+
+The DSL editor entry points live in `@blueprint-chart/editor`, not in `@blueprint-chart/lib`. From the lib side, the parsing surface is:
+
+| Symbol (from `@blueprint-chart/lib`) | One-liner |
+| --- | --- |
+| `parse(source)` | BPC text → AST. Throws `SyntaxError` with `location`. |
+| `serialize(ast)` | AST → BPC text (pretty-printed). |
+| `compactSerialize(ast)` | AST → BPC text (whitespace-minimised). |
+| `propertyMap` | Catalogue of recognised property keys per chart type. |
+| `ChartNode`, `PropertyNode`, `DataNode`, … | AST node types — see [the API reference](/reference/api/#dsl). |
+
+From the editor side:
+
+| Symbol (from the editor's `@/dsl-lang`) | One-liner |
+| --- | --- |
+| `bpcLanguage()` | CodeMirror `LanguageSupport` for `.bpc`. |
+| `bpcHighlighter` | `syntaxHighlighting` extension. |
+| `highlightDsl(code)` | One-shot HTML highlight for read-only previews. |
+
+## See also
+
+- [BPC DSL specification](/reference/dsl/) — the canonical language reference.
+- [Scenes guide](/guide/scenes) — scene syntax inside the DSL.
+- [Data transforms guide](/guide/data-transforms) — transforms inside the DSL.
+- [API reference](/reference/api/#dsl) for the lib's `parse` / `serialize` / converter helpers.