@blueprint-chart/docs 0.3.0 → 1.0.0

package/dist/manifest.json

@@ -126,6 +126,13 @@
       "blurb": "> 50+ curated categorical palettes, plus the helpers to resolve, audit, and adjust them for the background you render against.",
       "mdPath": "guide/palettes.md"
     },
+    {
+      "slug": "rendering",
+      "group": "guide",
+      "title": "rendering",
+      "blurb": "The `render()` function is the primary programmatic entry point for `@blueprint-chart/lib`. It accepts a BPC source string and returns a **chart handle** — an object with methods to produce SVG, PNG, ",
+      "mdPath": "guide/rendering.md"
+    },
     {
       "slug": "scenes",
       "group": "guide",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-chart/docs",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Public documentation for Blueprint Chart — handbook, guide, BPC DSL spec, and lib API reference.",
   "type": "module",
   "license": "MIT",
@@ -49,8 +49,8 @@
     "vitepress": "^1.5.0",
     "vitest": "^3.2.4",
     "vue": "^3.5",
-    "@blueprint-chart/lib": "0.3.0",
-    "@blueprint-chart/ui": "0.3.0"
+    "@blueprint-chart/lib": "1.0.0",
+    "@blueprint-chart/ui": "1.0.0"
   },
   "scripts": {
     "dev": "vitepress dev src --host 0.0.0.0 --port 4445",

package/src/charts/bar-vertical.md

@@ -26,19 +26,19 @@ title: Vertical bar chart
 chart bar-vertical {
   title = "Brazil produces more coffee than the next three countries combined"
   description = "Million 60-kg bags, 2023/24 crop year"
-  source = "International Coffee Organization"
-  sourceUrl = "https://ico.org"
+  source = "USDA Foreign Agricultural Service"
+  sourceUrl = "https://www.fas.usda.gov/data/coffee-world-markets-and-trade"
   colorPalette = "Harvey"
   valueLabels = true
   valueLabelPosition = "auto"
 
   data {
     "Brazil" = 66.4
-    "Vietnam" = 29
-    "Colombia" = 11.4
-    "Indonesia" = 9.9
-    "Ethiopia" = 8.7
-    "Honduras" = 6.3
+    "Vietnam" = 27.5
+    "Colombia" = 12.76
+    "Ethiopia" = 9.13
+    "Indonesia" = 7.65
+    "Honduras" = 5.5
   }
 
   colorize "Brazil" {

package/src/guide/data-transforms.md

@@ -23,11 +23,11 @@ chart bar-vertical {
 
   data {
     "Brazil" = 66.4
-    "Vietnam" = 29
-    "Colombia" = 11.4
-    "Indonesia" = 9.9
-    "Ethiopia" = 8.7
-    "Honduras" = 6.3
+    "Colombia" = 12.76
+    "Ethiopia" = 9.13
+    "Honduras" = 5.5
+    "Indonesia" = 7.65
+    "Vietnam" = 27.5
   }
 
   colorize "Brazil" {
@@ -42,7 +42,7 @@ chart bar-vertical {
 ```
 
 ::: 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.
+Adapted from `packages/lib/src/samples/coffee-production.bpc`, the only sample currently shipping with a `transform` block. The rows are shown here unsorted; `transform sort` reorders them to descending before the bar-vertical renderer reads them.
 :::
 
 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.

package/src/guide/getting-started.md

@@ -152,9 +152,9 @@ make dev-docs     # these docs at http://localhost:4445
 The lib ships ~40 ready-to-run `.bpc` files under `packages/lib/src/samples/`. They double as canonical examples and as integration-test fixtures. A handful worth opening first:
 
 - `bitcoin-price.bpc` — single-series line with a brand colour, year-by-year diamond symbols, and an annotation on the 2021 peak.
-- `co2-emissions-story.bpc` — a bar chart with three scenes, each highlighting a different country to walk a reader through the same data.
-- `farm-compass.bpc` — a multi-scene narrative where later scenes swap the chart type (area → line → area-stacked) without rewriting the source.
-- `browser-market.bpc` — a donut driven by the named `Heep` palette, with right-anchored legend and percentage display.
+- `co2-emissions-story.bpc` — a bar chart with four scenes, each highlighting a different country to walk a reader through the same data.
+- `farm-compass.bpc` — a multi-scene narrative where later scenes swap the chart type (area-stacked → line → area → line-multi) without rewriting the source.
+- `browser-market.bpc` — a donut driven by the named `Imperator` palette, with right-anchored legend and percentage display.
 - `medal-count.bpc` — `bar-multi` with a gold / silver / bronze custom palette, sorted descending, top-anchored legend.
 - `temperature-anomaly.bpc` — single-series line tuned for dark mode (`autoContrast = false`, `allowDarkMode = true`) with a curved annotation calling out the 2015 Paris Agreement.
 

package/src/guide/palettes.md

@@ -16,28 +16,26 @@ Pick a palette by name in a `.bpc` document:
 
 ```bpc
 chart donut {
-  title = "Chrome dominates with two-thirds of the desktop browser market"
-  description = "Worldwide, January 2025"
-  source = "StatCounter"
-  sourceUrl = "https://gs.statcounter.com"
-  colorPalette = "Heep"
+  title = "The richest 1% own more wealth than the entire bottom 90% combined"
+  description = "Share of global wealth by group, 2021"
+  source = "World Inequality Report 2022"
+  sourceUrl = "https://wir2022.wid.world"
+  colorPalette = "Imperator"
   legendPosition = "right"
-  tooltips = true
   displayAsPercentage = true
+  tooltips = true
 
   data {
-    "Chrome" = 65.7
-    "Edge" = 13.1
-    "Safari" = 8.9
-    "Firefox" = 6.3
-    "Opera" = 3.1
-    "Others" = 2.9
+    "Top 1%" = 38
+    "Next 9%" = 38
+    "Middle 40%" = 22
+    "Bottom 50%" = 2
   }
 }
 ```
 
 ::: tip From the sample library
-This is `packages/lib/src/samples/browser-market.bpc` — a donut chart driven entirely by the named `Heep` palette. Each slice picks up the next colour from the resolved palette array.
+Excerpted from `packages/lib/src/samples/browser-market.bpc` — a donut chart driven entirely by the named `Imperator` palette. Each slice picks up the next colour from the resolved palette array.
 :::
 
 Or pull the colours into TypeScript:

package/src/guide/rendering.md

@@ -0,0 +1,56 @@
+# Rendering in code
+
+The `render()` function is the primary programmatic entry point for `@blueprint-chart/lib`. It accepts a BPC source string and returns a **chart handle** — an object with methods to produce SVG, PNG, or a live DOM mount.
+
+## Node — write SVG and PNG to disk
+
+```ts
+import { render } from '@blueprint-chart/lib'
+import { writeFile } from 'node:fs/promises'
+
+const chart = await render(bpc)
+await writeFile('chart.svg', await chart.toSvg())
+await writeFile('chart.png', await chart.toPng({ width: 1200 }))
+```
+
+PNG export and headless SVG in Node require optional native deps (`jsdom`, `@napi-rs/canvas`, `@resvg/resvg-js`). These are installed automatically as `optionalDependencies`. If a binary failed to install, the Node methods throw `MissingNodeRenderDepsError` naming what to reinstall.
+
+## Browser — mount and step scenes
+
+```ts
+const { mount, scene } = await render(bpc)
+mount('#chart')   // element or selector
+scene(2)          // advance to scene index 2
+```
+
+`mount` accepts an `HTMLElement` or a CSS selector string and returns the handle for chaining. `scene(n)` steps to scene index `n` and is also chainable.
+
+## Options
+
+Pass a second argument to `render()` to control the output:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `theme` | system | `'light'` or `'dark'` |
+| `scene` | `0` | Initial scene index |
+| `width` | `640` | Output width in px (headless only) |
+| `height` | `400` | Output height in px (headless only) |
+| `frame` | `true` | `false` renders frameless (no title/source/etc.) |
+
+```ts
+const chart = await render(bpc, { theme: 'dark', width: 1200, height: 630 })
+```
+
+## The handle
+
+`render()` resolves to a `ChartHandle`. Its methods are **bound** — destructure freely — and `mount`/`scene` are **chainable**.
+
+| Method | Browser | Node | Returns |
+| --- | --- | --- | --- |
+| `toSvg(opts?)` | ✅ | ✅ | `Promise<string>` |
+| `toHtml(opts?)` | ✅ | ✅ | `Promise<string>` |
+| `toPng(opts?)` | ❌ throws `PngBrowserUnsupportedError` | ✅ | `Promise<Uint8Array>` |
+| `mount(target)` | ✅ | no-op (warns) | `ChartHandle` |
+| `scene(n)` | ✅ | ✅ | `ChartHandle` |
+
+See the [API reference](/reference/api/) for the full surface of `@blueprint-chart/lib`, including low-level rendering primitives and the chart-type registry.

package/src/guide/scenes.md

@@ -12,58 +12,64 @@ Journalism rarely sits still on a single chart. A finding has a build-up, a turn
 
 ## Quickstart
 
-A bar chart with three narrative beats — each one highlights a different country:
+A bar chart with four narrative beats — the first three re-spotlight a different country, and the last reframes the same story per capita:
 
 ```bpc
 chart bar-horizontal {
-  title = "Five nations produce 80% of global CO₂"
+  title = "China emits more CO₂ than the US and India combined"
   description = "Annual emissions in billion tonnes, 2023"
-  source = "Global Carbon Project"
-  sourceUrl = "https://globalcarbonproject.org"
-  sort = descending
-  valueLabels = true
-  horizontalGridStyle = none
-  showVerticalAxis = true
-  showVerticalTicks = false
-  verticalGridStyle = none
+  source = "Our World in Data"
+  sourceUrl = "https://ourworldindata.org/co2-emissions"
+  byline = "Pierre Romera"
 
   data {
-    "China" = 11.90
-    "United States" = 4.78
-    "India" = 2.88
-    "Russia" = 1.78
-    "Japan" = 1.02
+    "China" = 12.17
+    "United States" = 4.92
+    "India" = 3.06
+    "Russia" = 1.73
+    "Japan" = 0.99
+    "Germany" = 0.59
   }
 
   scene "China spotlight" {
-    title = "China emits more than the US and India combined"
-
+    title = "China alone emits more than the US and India together"
     highlight "China"
   }
 
   scene "India rising" {
-    title = "India surpassed the EU in 2023"
-
+    title = "India passed the EU to become the third-largest emitter"
     highlight "India"
   }
 
   scene "Japan declining" {
-    title = "Japan's emissions fell 20% from their peak"
-
+    title = "Japan's emissions have fallen since their 2013 peak"
     highlight "Japan"
   }
+
+  scene "Per capita reframe" {
+    title = "Per person, Gulf states dwarf the biggest emitters"
+    description = "CO₂ emissions per capita, tonnes per person, 2023"
+    highlight "Qatar"
+    data {
+      "Qatar" = 40.13
+      "United Arab Emirates" = 19.77
+      "United States" = 14.32
+      "China" = 8.56
+      "India" = 2.13
+    }
+  }
 }
 ```
 
 ::: tip From the sample library
-This is `packages/lib/src/samples/co2-emissions-story.bpc` verbatim — three scenes, each one re-titling the chart and shifting the highlight to a new country. The base data stays the same; only the framing changes.
+This is `packages/lib/src/samples/co2-emissions-story.bpc` verbatim. The first three scenes keep the same base data and only shift the title and highlight; the fourth swaps in per-capita data for a closing reframe.
 :::
 
 Open this in the editor to see the scene timeline appear automatically; embed it on a page and readers get a Previous / Next nav.
 
 ## How it works
 
-A scene block accepts the same member set as the top-level chart, **plus** annotation-visibility verbs. At parse time, each `scene` becomes a `SceneNode` in the AST. The DSL converter merges scene members on top of the base chart to produce the **effective** `ChartData` and `ChartOptions` for that scene.
+A scene block accepts the same member set as the top-level chart. At parse time, each `scene` becomes a `SceneNode` in the AST. The DSL converter merges scene members on top of the base chart to produce the **effective** `ChartData` and `ChartOptions` for that scene.
 
 At render time:
 
@@ -82,13 +88,13 @@ The short-form `highlight "<name>"` is the workhorse. Drop one per scene and the
 
 ```bpc
 scene "China spotlight" {
-  title = "China emits more than the US and India combined"
+  title = "China alone emits more than the US and India together"
 
   highlight "China"
 }
 
 scene "India rising" {
-  title = "India surpassed the EU in 2023"
+  title = "India passed the EU to become the third-largest emitter"
 
   highlight "India"
 }
@@ -104,8 +110,8 @@ Any scene can carry its own `data` block, which **replaces** the base data for t
 
 ```bpc
 scene "Bulgaria: subsidies explode" {
-  title = "Subsidies to Bulgarian farmers, million euros"
-  description = "85% of Bulgarian subsidies are direct payments — the highest share among new members"
+  title = "Bulgarian farmers received almost nothing before 2007 accession"
+  description = "More than three-quarters of Bulgarian subsidies are direct payments — the highest share among new members"
 
   data {
     series = "Indirect subsidies","Direct subsidies"
@@ -145,25 +151,43 @@ scene "Bulgarian farms grew" {
 ```
 
 ::: tip From the sample library
-Scene #5 of `packages/lib/src/samples/farm-compass.bpc`. The story changes chart type three times across nine scenes — `area-stacked` → `line` → `area` → `area-stacked` → bar — all from one document.
+Scene #4 of `packages/lib/src/samples/farm-compass.bpc`. The story changes chart type four times across its nine scenes — `area-stacked` → `line` → `area` → `area-stacked` → `line-multi` — all from one document.
 :::
 
-### Hide an annotation in a later scene
+### Control how long an annotation stays
 
-Use `hide-annotation`, `hide-range`, or `hide-note` with the annotation's id to peel things back as the story progresses:
+By default an annotation shows only in the scene where it is declared. Use
+`repeat` to carry it into later scenes:
 
 ```bpc
-annotation "2015" {
-  id = "paris"
-  text = "Paris Agreement"
+scene "Crash" {
+  range {
+    start = 2008
+    end = 2009
+    text = "Financial crisis"
+    repeat = 1         // this scene plus the next one (2 scenes total)
+  }
 }
 
-scene "Without Paris callout" {
-  hide-annotation "paris"
+scene "Recovery" {
+  annotation "2015" {
+    text = "Paris Agreement"
+    repeat = true      // this scene and every scene after it
+  }
 }
 ```
 
-To bring it back later, use `show-annotation "paris"` in a subsequent scene.
+`repeat` accepts three forms:
+
+- `false` or omitted (the default): show only in this scene.
+- a positive integer `N`: show in this scene plus the next `N` scenes, so
+  `repeat = 1` spans 2 scenes and `repeat = 3` spans 4.
+- `true`: show in this scene and every scene after it.
+
+A top-level annotation (declared on the chart itself, outside any scene)
+anchors at the base chart frame, the first thing a reader sees. With no
+`repeat` it appears only there; `repeat` carries it forward into the scenes
+that follow.
 
 ### Drive playback from your own UI
 

package/src/handbook/accessibility.md

@@ -82,9 +82,9 @@ chart bar-vertical {
 
   data {
     "Brazil" = 66.4
-    "Vietnam" = 29
-    "Colombia" = 11.4
-    "Indonesia" = 9.9
+    "Vietnam" = 27.5
+    "Colombia" = 12.76
+    "Indonesia" = 7.65
   }
 
   colorize "Brazil" {
@@ -93,7 +93,7 @@ chart bar-vertical {
 }
 ```
 
-::: info From `packages/lib/src/samples/coffee-production.bpc`
+::: info Adapted from `packages/lib/src/samples/coffee-production.bpc`
 Coffee uses two encodings for the highlighted bar: a distinct hue (`#a4432d` red-brown vs. the muted Harvey palette) and clear *lightness* contrast against its neighbours. Convert the chart to greyscale and Brazil still reads as the darkest bar — the second encoding (lightness) carries the story even when CVD removes the first (hue). Compare with `valueLabels = true`, which adds a *third* encoding (the literal number).
 :::
 

package/src/handbook/axes.md

@@ -27,6 +27,18 @@ Truncating the y-axis on a bar or area chart visually exaggerates differences. T
 - Remove grid lines entirely when value labels are shown directly on data
 - Grid lines are reference aids, not primary content — they should never compete with data
 
+## Bar charts default to no value axis
+
+Bar charts label each bar directly, so the value axis is redundant. Every bar
+variant — vertical, horizontal, grouped, stacked, split — defaults to **no
+value-axis line, no value ticks/numbers, and no value gridlines**. Only the zero
+baseline and the category names remain.
+
+When a segment is too small to hold its label legibly, the label is suppressed
+and the value falls back to the tooltip. To restore a value axis, set
+`showVerticalAxis` / `showHorizontalAxis`, `verticalGridStyle` /
+`horizontalGridStyle`, or turn `valueLabels` off explicitly.
+
 ## Tick marks
 
 - Subtle or no ticks are preferred in modern chart design
@@ -63,6 +75,8 @@ A trend that looks alarming at 3:1 can look flat at 3:4. When showing rate of ch
 
 Blueprint Chart's `AxisOptions` exposes scale type (linear / log), tick count, tick format, and baseline behavior. D3 scales drive the tick layout, and a shared number formatter is used by the axis, tooltip, and direct labels so the same value is rendered identically wherever it appears.
 
+Bar charts ship with the value axis suppressed by default — direct value labels replace it. The category axis always remains. See [Bar charts default to no value axis](#bar-charts-default-to-no-value-axis) above for the complete rule.
+
 See the [API reference](/reference/api/) for the public options that toggle grid lines, tick density, and baseline zero.
 
 ## Worked example: number format on the axis

package/src/handbook/choosing.md

@@ -108,7 +108,7 @@ chart donut {
 }
 ```
 
-::: info From `packages/lib/src/samples/browser-market.bpc`
+::: info When a donut fits
 Six categories summing to 100 % — the question is "how big a slice does Chrome own?" A donut answers it directly; a line chart cannot.
 :::
 

package/src/handbook/color.md

@@ -106,7 +106,7 @@ chart donut {
 }
 ```
 
-::: info From `packages/lib/src/samples/browser-market.bpc`
+::: info A categorical palette at the 7-color limit
 Six unordered categories, so a categorical palette ("Heep") is the right tool — its hues vary in lightness, which means the donut survives a grayscale conversion. The rule "maximum 7 categorical colors" is exactly at the limit here.
 :::
 

package/src/handbook/design-principles.md

@@ -71,17 +71,14 @@ chart bar-vertical {
   description = "Million 60-kg bags, 2023/24 crop year"
   source = "International Coffee Organization"
   colorPalette = "Harvey"
-  valueLabels = true
-  verticalGridStyle = "none"
-  horizontalGridStyle = "none"
 
   data {
     "Brazil" = 66.4
-    "Vietnam" = 29
-    "Colombia" = 11.4
-    "Indonesia" = 9.9
-    "Ethiopia" = 8.7
-    "Honduras" = 6.3
+    "Vietnam" = 27.5
+    "Colombia" = 12.76
+    "Ethiopia" = 9.13
+    "Indonesia" = 7.65
+    "Honduras" = 5.5
   }
 
   colorize "Brazil" {
@@ -95,8 +92,8 @@ chart bar-vertical {
 }
 ```
 
-::: info From `packages/lib/src/samples/coffee-production.bpc`
-Five bars stay in muted neutrals; the `colorize "Brazil"` block lifts the one bar the title is about. `valueLabels = true` removes the need for a y-axis altogether — direct labels carry the precise numbers, and gridlines drop out entirely. Restraint, purposefulness, and "start with grey" applied in a single chart.
+::: info Adapted from `packages/lib/src/samples/coffee-production.bpc`
+Five bars stay in muted neutrals; the `colorize "Brazil"` block lifts the one bar the title is about. Direct labels carry the precise numbers by default, removing the need for a y-axis altogether, and gridlines drop out entirely. Restraint, purposefulness, and "start with grey" applied in a single chart.
 :::
 
 ## How Blueprint Chart applies these principles

package/src/handbook/labels.md

@@ -36,8 +36,10 @@ Place labels directly on or adjacent to data elements instead of using a separat
 
 ## Value labels
 
-- Show value labels when precision matters to the reader
-- On bar charts: inside the bar (if wide enough) or at the end
+For bar charts, value labels are **on by default** — they replace the value axis entirely, so each bar carries its number directly. The renderer uses an "auto: label if it fits" rule: when a bar or stack segment is too narrow to hold its label legibly, the label is suppressed and the value falls back to the tooltip instead. See [Axes & Grid Lines](/handbook/axes) for the no-value-axis default.
+
+For other chart types:
+
 - On line charts: at key data points only, not every point
 - On pie / donut charts: outside for small slices, inside for large ones
 - Position labels to avoid overlap; use tooltips as a fallback for dense data
@@ -65,9 +67,6 @@ chart bar-vertical {
   title = "E is the most frequent letter in English"
   description = "How often each letter appears in typical English text"
   sort = descending
-  valueLabels = true
-  verticalLabelPosition = off
-  verticalGridStyle = none
 
   data {
     "E" = 12.70
@@ -80,7 +79,7 @@ chart bar-vertical {
 ```
 
 ::: info From `packages/lib/src/samples/letter-frequency.bpc`
-`valueLabels = true` puts the precise number at the end of every bar, so the y-axis label position can be set to `off` and the gridlines removed entirely. Direct labelling replaces both the legend and the axis labels — a clean application of the data-ink rule.
+Value labels appear at the end of every bar by default, so the y-axis label position can be set to `off` and the gridlines removed entirely. Direct labelling replaces both the legend and the axis labels — a clean application of the data-ink rule.
 :::
 
 ## Worked example: legend at the top, direct value labels at the bar end
@@ -91,9 +90,6 @@ chart bar-multi {
   description = "2024 Paris Summer Games — top six nations"
   colors = "#eeca3b, #c0c0c0, #cd7f32"
   legendPosition = "top"
-  valueLabels = true
-  verticalGridStyle = none
-  verticalLabelPosition = off
   sort = descending
 
   data {
@@ -106,7 +102,7 @@ chart bar-multi {
 ```
 
 ::: info From `packages/lib/src/samples/medal-count.bpc`
-A multi-series bar chart needs a legend to map the three hues to Gold / Silver / Bronze — placed at the top so the eye reaches it before scanning the bars. Inside each bar, `valueLabels = true` prints the exact count, eliminating the need to read against a vertical scale.
+A multi-series bar chart needs a legend to map the three hues to Gold / Silver / Bronze — placed at the top so the eye reaches it before scanning the bars. Inside each bar, value labels print the exact count by default, eliminating the need to read against a vertical scale.
 :::
 
 ## See also

package/src/handbook/tooltips.md

@@ -86,7 +86,7 @@ chart line-multi {
 }
 ```
 
-::: info From `packages/lib/src/samples/unemployment-rates.bpc`
+::: info Progressive disclosure without hiding the story
 The annotation carries the headline (`"Great Recession peak"`) so the chart stands on its own. `tooltips = true` plus `crosshair = true` then layer progressive disclosure on top: hover anywhere on the x-axis and a dashed vertical line aligns the cursor with all four series at once, while the tooltip shows the four percentages for that year. The essential story is never trapped behind a hover.
 :::
 

package/src/handbook/typography.md

@@ -68,7 +68,6 @@ chart bar-vertical {
   source = "Lewand, Cryptological Mathematics"
   note = "Based on analysis of 40,000 words from English prose"
   valueLabels = true
-  verticalLabelPosition = off
   verticalGridStyle = none
 
   data {

package/src/reference/api/index.md

@@ -6,6 +6,59 @@ Public surface of [`@blueprint-chart/lib`](https://www.npmjs.com/package/@bluepr
 This page mirrors [`packages/lib/src/index.ts`](https://github.com/blueprint-chart/blueprint-chart/blob/main/packages/lib/src/index.ts). It will be progressively replaced by automatically-generated TypeDoc output; for now, treat the source file as canonical when a symbol is missing here.
 :::
 
+## Rendering a chart
+
+The fastest path: one function returns a chart **handle**.
+
+```ts
+import { render } from '@blueprint-chart/lib'
+
+const chart = await render(bpcSource, { theme: 'dark' })
+```
+
+### Node — write SVG and PNG to disk
+
+```ts
+import { render } from '@blueprint-chart/lib'
+import { writeFile } from 'node:fs/promises'
+
+const chart = await render(bpc)
+await writeFile('chart.svg', await chart.toSvg())
+await writeFile('chart.png', await chart.toPng({ width: 1200 }))
+```
+
+### Browser — mount and step scenes
+
+```ts
+const { mount, scene } = await render(bpc)
+mount('#chart')   // element or selector
+scene(2)          // advance to scene index 2
+```
+
+### The handle
+
+`render(source, options?)` resolves to a `ChartHandle`. Its methods are **bound** — destructure them freely (`const { toSvg } = await render(bpc)`) — and `mount`/`scene` are **chainable** (`(await render(bpc)).scene(1).toSvg()`).
+
+| Method | Browser | Node | Returns |
+| --- | --- | --- | --- |
+| `toSvg(opts?)` | ✅ | ✅ | `Promise<string>` |
+| `toHtml(opts?)` | ✅ | ✅ | `Promise<string>` |
+| `toPng(opts?)` | ❌ throws `PngBrowserUnsupportedError` | ✅ | `Promise<Uint8Array>` |
+| `mount(target)` | ✅ | no-op (warns) | `ChartHandle` |
+| `scene(n)` | ✅ | ✅ | `ChartHandle` |
+
+`toHtml()` returns the `.bc-frame` outerHTML (the complete framed chart markup). When `frame: false` was passed to `render()`, it falls back to the bare chart SVG.
+
+`RenderApiOptions`: `theme?`, `scene?` (initial scene), `width?`/`height?` (default `640×400`, used for headless output only), `frame?` (default `true`; `false` renders frameless). `OutputOptions` on `toSvg`/`toPng`: `width?`, `height?`.
+
+### Node dependencies
+
+PNG export and headless SVG in Node require optional native deps (`jsdom`, `@napi-rs/canvas`, `@resvg/resvg-js`), installed automatically as `optionalDependencies`. If a binary failed to install, the Node methods throw `MissingNodeRenderDepsError` naming what to reinstall. Browser bundles never include these.
+
+> SVG produced headlessly carries inline data colors and renders fonts via bundled DejaVu during PNG rasterization. It does not inline the full `charts.scss` theme; opening the bare `.svg` outside an app with that stylesheet may lack some structural styling.
+
+## Low-level surface
+
 ## Entrypoints
 
 | Entrypoint | Purpose |

package/src/reference/dsl/annotations.md

@@ -41,19 +41,19 @@ The short form `highlight "<name>"` (no body) is the common case — useful insi
 
 ```bpc
 scene "China spotlight" {
-  title = "China emits more than the US and India combined"
+  title = "China alone emits more than the US and India together"
 
   highlight "China"
 }
 
 scene "India rising" {
-  title = "India surpassed the EU in 2023"
+  title = "India passed the EU to become the third-largest emitter"
 
   highlight "India"
 }
 
 scene "Japan declining" {
-  title = "Japan's emissions fell 20% from their peak"
+  title = "Japan's emissions have fallen since their 2013 peak"
 
   highlight "Japan"
 }

package/src/reference/dsl/scenes-and-transforms.md

@@ -1,6 +1,6 @@
 # DSL — Scenes & transforms
 
-Story-level constructs: **scenes** compose multiple visualisation states into a stepable narrative, and **transforms** describe data-pipeline operations applied before rendering. Scenes can override almost any chart member — including chart `type` and `data` — and add their own annotation-visibility verbs.
+Story-level constructs: **scenes** compose multiple visualisation states into a stepable narrative, and **transforms** describe data-pipeline operations applied before rendering. Scenes can override almost any chart member, including chart `type` and `data`. Annotation lifetime is controlled with the `repeat` property on the annotation itself.
 
 ## Scenes
 
@@ -10,26 +10,26 @@ A simple "highlight tour" — each scene swaps the title and emphasises one bar:
 
 ```bpc
 scene "China spotlight" {
-  title = "China emits more than the US and India combined"
+  title = "China alone emits more than the US and India together"
 
   highlight "China"
 }
 
 scene "India rising" {
-  title = "India surpassed the EU in 2023"
+  title = "India passed the EU to become the third-largest emitter"
 
   highlight "India"
 }
 
 scene "Japan declining" {
-  title = "Japan's emissions fell 20% from their peak"
+  title = "Japan's emissions have fallen since their 2013 peak"
 
   highlight "Japan"
 }
 ```
 
 ::: info From `packages/lib/src/samples/co2-emissions-story.bpc`
-Three scenes on a `bar-horizontal` chart. Each scene inherits the chart's data and styling, and only overrides what changes — `title` plus a `highlight` target.
+Three scenes from a `bar-horizontal` story. Each scene inherits the chart's data and styling, and only overrides what changes — `title` plus a `highlight` target.
 :::
 
 Scenes can also override the chart's **type** and **data** wholesale, switching from one visualisation to another mid-story:
@@ -68,14 +68,17 @@ scene "Cash crops replaced vegetables" {
 A "story" can transition between chart types — here from a stacked area to a single-series line, then to a different stacked area — by setting `type` and supplying fresh `data` inside the scene.
 :::
 
-Scenes accept the same member set as the top-level chart, **plus** annotation-visibility verbs:
+Scenes accept the same member set as the top-level chart.
 
-| Verb | Effect |
+Annotation lifetime is governed by the `repeat` property on each annotation, not by scene-level verbs:
+
+| Value | Meaning |
 | --- | --- |
-| `hide-annotation "<id>"` | Hide a point annotation set on the chart. |
-| `hide-range "<id>"` | Hide a range annotation. |
-| `hide-note "<id>"` | Hide a free / note annotation. |
-| `show-annotation "<id>"` / `show-range "<id>"` / `show-note "<id>"` | Re-show one previously hidden by an earlier scene. |
+| `repeat = false` (or omitted) | Show only in the scene where the annotation is declared (default). |
+| `repeat = N` | Show in the declaring scene plus the next `N` scenes, so `repeat = 1` spans 2 scenes and `repeat = 3` spans 4. `N` must be a positive integer. |
+| `repeat = true` | Show in the declaring scene and every scene after it. |
+
+A top-level annotation (declared on the chart, outside any scene) anchors at the base chart frame: with no `repeat` it shows only on that first frame, and `repeat` carries it forward into the following scenes.
 
 ## Transforms