@blueprint-chart/docs 0.1.29 → 0.1.30

package/dist/manifest.json

@@ -228,7 +228,7 @@
       "slug": "annotations",
       "group": "reference/dsl",
       "title": "annotations",
-      "blurb": "Two families of named blocks that target specific data values to draw the eye: **color directives** (`colorize`, `highlight`, `areafill`) recolor or emphasize parts of the chart, and **annotations** (",
+      "blurb": "Two families of named blocks that target specific data values to draw the eye: **color directives** (`colorize`, `highlight`, `area-fill`) recolor or emphasize parts of the chart, and **annotations** ",
       "mdPath": "reference/dsl/annotations.md"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-chart/docs",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Public documentation for Blueprint Chart — handbook, guide, BPC DSL spec, and lib API reference.",
   "type": "module",
   "license": "MIT",
@@ -33,11 +33,12 @@
     "provenance": true
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@fontsource-variable/geist-mono": "^5.2.7",
     "@fontsource/dm-serif-display": "^5.2.8",
     "@iconify-json/ph": "^1.2.2",
+    "@types/node": "^22.10.0",
+    "@vitejs/plugin-vue": "^5.2.4",
     "@vue/test-utils": "^2.4.6",
     "@vueuse/core": "^14.2.1",
     "gray-matter": "^4.0.3",
@@ -48,8 +49,8 @@
     "vitepress": "^1.5.0",
     "vitest": "^3.2.4",
     "vue": "^3.5",
-    "@blueprint-chart/lib": "0.1.29",
-    "@blueprint-chart/ui": "0.1.29"
+    "@blueprint-chart/lib": "0.1.30",
+    "@blueprint-chart/ui": "0.1.30"
   },
   "scripts": {
     "dev": "vitepress dev src --host 0.0.0.0 --port 4445",

package/src/charts/area-stacked.md

@@ -34,7 +34,7 @@ chart area-stacked {
   areaFillOpacity = 0.85
 
   data {
-    _series = "Coal","Oil","Gas","Renewables"
+    series = "Coal","Oil","Gas","Renewables"
     "2000" = 25,36,21,18
     "2005" = 27,35,22,16
     "2010" = 29,33,23,15

package/src/charts/bar-grouped.md

@@ -31,7 +31,7 @@ chart bar-grouped {
   valueLabels = true
 
   data {
-    _series = "Solar","Wind","Hydro"
+    series = "Solar","Wind","Hydro"
     "Asia Pacific"  = 680,540,840
     "Europe"        = 250,300,200
     "North America" = 200,180,190

package/src/charts/bar-multi.md

@@ -34,7 +34,7 @@ chart bar-multi {
   sort = descending
 
   data {
-    _series = "Gold","Silver","Bronze"
+    series = "Gold","Silver","Bronze"
     "USA" = 40,44,42
     "China" = 38,32,18
     "Japan" = 27,14,17

package/src/charts/bar-split.md

@@ -31,7 +31,7 @@ chart bar-split {
   valueLabels = true
 
   data {
-    _series = "Winter (Jan)","Spring (Apr)","Summer (Jul)"
+    series = "Winter (Jan)","Spring (Apr)","Summer (Jul)"
     "Miami"       = 20,26,29
     "Los Angeles" = 14,17,23
     "Phoenix"     = 13,24,37

package/src/charts/bar-stacked.md

@@ -33,7 +33,7 @@ chart bar-stacked {
   horizontalLabelPosition = off
 
   data {
-    _series = "0-14","15-64","65+"
+    series = "0-14","15-64","65+"
     "China" = 249,987,191
     "India" = 365,948,100
     "USA" = 60,215,58

package/src/charts/column-stacked.md

@@ -29,7 +29,7 @@ chart column-stacked {
   source = "Annual report"
 
   data {
-    _series = "Hardware","Software","Services"
+    series = "Hardware","Software","Services"
     "Q1" = 120,85,45
     "Q2" = 135,92,48
     "Q3" = 128,98,52

package/src/charts/line-multi.md

@@ -33,7 +33,7 @@ chart line-multi {
   tooltips = true
 
   data {
-    _series = "United States","China","Germany"
+    series = "United States","China","Germany"
     "2018" = 2.9,6.7,1.0
     "2019" = 2.3,6.0,1.1
     "2020" = -2.8,2.2,-3.7

package/src/guide/accessibility.md

@@ -88,7 +88,7 @@ chart bar-multi {
   legendPosition = "top"
 
   data {
-    _series = "Gold","Silver","Bronze"
+    series = "Gold","Silver","Bronze"
     "USA" = 40,44,42
     "China" = 38,32,18
   }

package/src/guide/dsl-editor.md

@@ -76,7 +76,7 @@ The CodeMirror 6 stack pulls in `@codemirror/view`, `@codemirror/state`, `@codem
 - `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.
+The Lezer parser tags DSL keywords (`chart`, `data`, `colorize`, `highlight`, `area-fill`, `annotation`, `range`, `note`, `series`, `scene`, `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
 
@@ -130,7 +130,7 @@ const html = highlightDsl(`chart line-multi {
   }
 
   data {
-    _series = "United States","China","Germany"
+    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
@@ -140,8 +140,8 @@ const html = highlightDsl(`chart line-multi {
 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.
+::: tip Inline example
+The DSL string is an abbreviated GDP series (the 2018, 2020, and 2024 rows). 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.

package/src/guide/embed.md

@@ -26,7 +26,7 @@ The simplest path. Load the standalone runtime once per page, then add one `<scr
     tooltips = true
 
     data {
-      _series = "Hydro","Wind","Solar"
+      series = "Hydro","Wind","Solar"
       "2010" = 16.0,1.6,0.3
       "2012" = 16.2,2.4,0.6
       "2014" = 16.3,3.3,1.1
@@ -40,8 +40,8 @@ The simplest path. Load the standalone runtime once per page, then add one `<scr
 </script>
 ```
 
-::: tip From the sample library
-This is `packages/lib/src/samples/renewable-energy.bpc` — a multi-series line with explicit per-series colours and a single trailing symbol on the last datapoint of each series. Pasted verbatim into a page, it renders to a self-contained iframe with no extra wiring.
+::: tip Inline example
+A multi-series line with explicit per-series colours and a single trailing symbol on the last datapoint of each series. Pasted verbatim into a page, it renders to a self-contained iframe with no extra wiring.
 :::
 
 The runtime auto-runs on `DOMContentLoaded`, finds every chart script tag, and replaces it with a sandboxed iframe (`sandbox="allow-scripts"`) sized via `postMessage` to match the rendered chart.
@@ -144,8 +144,8 @@ Two end-to-end examples drawn straight from the lib's sample library — paste e
 </script>
 ```
 
-::: tip From the sample library
-This is `packages/lib/src/samples/energy-sources.bpc` — a donut chart with an explicit categorical palette, right-anchored legend, and percentage display.
+::: tip Inline example
+A donut chart with an explicit categorical palette, right-anchored legend, and percentage display.
 :::
 
 ### Line: a single-series time series with an annotation
@@ -185,8 +185,8 @@ This is `packages/lib/src/samples/energy-sources.bpc` — a donut chart with an
 </script>
 ```
 
-::: tip From the sample library
-This is `packages/lib/src/samples/inflation-rate.bpc` — a single-series line with circular symbols on every datapoint, a pinned annotation on the peak, and a one-decimal vertical number format.
+::: tip Inline example
+A single-series line with circular symbols on every datapoint, a pinned annotation on the peak, and a one-decimal vertical number format.
 :::
 
 ## Security model

package/src/guide/getting-started.md

@@ -115,8 +115,8 @@ If you don't need the programmatic API, use the bundled runtime. It picks up eve
 </script>
 ```
 
-::: tip From the sample library
-This is `packages/lib/src/samples/energy-sources.bpc` — a donut chart with a hand-picked categorical palette, percentage display, and a right-anchored legend.
+::: tip Inline example
+A donut chart with a hand-picked categorical palette, percentage display, and a right-anchored legend.
 :::
 
 See the [embedding guide](/guide/embed) for static sites, CMS integrations, and the base64 iframe pattern.

package/src/guide/mcp.md

@@ -129,6 +129,7 @@ The handbook, DSL grammar, guides, chart-type docs, and canonical samples are al
 > **Your assistant:** *(calls `list_chart_types` and `get_example`, writes the `.bpc`, calls
 > `validate_dsl` to confirm it parses, then `render` and shows you the image and the source)*
 
+<!-- bpc-no-parse -->
 ```bpc
 chart bar-horizontal {
   title = "E is the most frequent letter in English"

package/src/guide/palettes.md

@@ -203,5 +203,5 @@ For the accessibility helpers (`wcagContrastRatio`, `wcagLevel`, `checkCvdColors
 
 - [Accessibility](/guide/accessibility) — WCAG and CVD utilities.
 - [Colour handbook](/handbook/color) — palette theory and reduction techniques.
-- [BPC DSL — Color directives](/reference/dsl/annotations#color-directives) for `colorize`, `highlight`, `areafill`.
+- [BPC DSL — Color directives](/reference/dsl/annotations#color-directives) for `colorize`, `highlight`, `area-fill`.
 - [API reference](/reference/api/#palettes) for the full export list.

package/src/guide/scenes.md

@@ -108,7 +108,7 @@ scene "Bulgaria: subsidies explode" {
   description = "85% of Bulgarian subsidies are direct payments — the highest share among new members"
 
   data {
-    _series = "Indirect subsidies","Direct subsidies"
+    series = "Indirect subsidies","Direct subsidies"
     "2000" = 0,5
     "2004" = 0,67
     "2007" = 59,250
@@ -150,7 +150,7 @@ Scene #5 of `packages/lib/src/samples/farm-compass.bpc`. The story changes chart
 
 ### Hide an annotation in a later scene
 
-Use `hide_annotation`, `hide_range`, or `hide_note` with the annotation's id to peel things back as the story progresses:
+Use `hide-annotation`, `hide-range`, or `hide-note` with the annotation's id to peel things back as the story progresses:
 
 ```bpc
 annotation "2015" {
@@ -159,11 +159,11 @@ annotation "2015" {
 }
 
 scene "Without Paris callout" {
-  hide_annotation "paris"
+  hide-annotation "paris"
 }
 ```
 
-To bring it back later, use `show_annotation "paris"` in a subsequent scene.
+To bring it back later, use `show-annotation "paris"` in a subsequent scene.
 
 ### Drive playback from your own UI
 

package/src/handbook/annotations.md

@@ -62,9 +62,9 @@ chart line {
     "May" = 2420
   }
 
-  annotation point {
-    at    = "Mar"
-    label = "New packaging launched March 3"
+  annotation "Mar" {
+    text = "New packaging launched March 3"
+    showArrow = true
   }
 }
 ```

package/src/handbook/anti-patterns.md

@@ -56,7 +56,7 @@ chart bar-split {
   sharedScale = true
 
   data {
-    _series = "Mathematics","Reading","Science"
+    series = "Mathematics","Reading","Science"
     "Singapore" = 575,543,561
     "Japan"     = 536,516,547
     "Korea"     = 527,515,528
@@ -68,7 +68,7 @@ chart bar-split {
 ```
 
 ::: tip Done right
-`sharedScale = true` forces every panel onto the same baseline-zero axis, so the eye can compare Mathematics directly against Reading directly against Science. `valueLabels = true` then exposes the exact number, removing any temptation to truncate the axis for visual drama. This is the corrective pattern for the "truncated y-axis", "dual y-axes", and "missing context" rows above. From `packages/lib/src/samples/pisa-scores.bpc`.
+`sharedScale = true` forces every panel onto the same baseline-zero axis, so the eye can compare Mathematics directly against Reading directly against Science. `valueLabels = true` then exposes the exact number, removing any temptation to truncate the axis for visual drama. This is the corrective pattern for the "truncated y-axis", "dual y-axes", and "missing context" rows above.
 :::
 
 ## The meta-rule

package/src/handbook/frame-elements.md

@@ -86,7 +86,7 @@ chart line {
 }
 ```
 
-::: info From `packages/lib/src/samples/inflation-rate.bpc`
+::: info Worked example
 A declarative title carries the insight (`"…peaked at 9.1% before retreating to near 3%"`), `description` fixes the unit and time period, `note` confines the methodology footnote to the bottom, `source` plus `sourceUrl` form the attribution pair, and `byline` is the credit slot. Each field maps one-to-one onto `FrameOptions`.
 :::
 

package/src/handbook/labels.md

@@ -97,7 +97,7 @@ chart bar-multi {
   sort = descending
 
   data {
-    _series = "Gold","Silver","Bronze"
+    series = "Gold","Silver","Bronze"
     "USA" = 40,44,42
     "China" = 38,32,18
     "Japan" = 27,14,17

package/src/handbook/tooltips.md

@@ -78,7 +78,7 @@ chart line-multi {
   }
 
   data {
-    _series = "New York","Los Angeles","Chicago","Detroit"
+    series = "New York","Los Angeles","Chicago","Detroit"
     "2000" = 5.0,5.6,4.5,3.8
     "2009" = 9.5,12.4,11.2,16.2
     "2014" = 6.5,8.0,7.1,8.2

package/src/reference/api/index.md

@@ -141,7 +141,7 @@ The `parse → mutate → serialize` cycle is **round-trip safe**: re-parsing th
 
 ### AST node types
 
-`ChartNode` · `DataNode` · `PropertyNode` · `SeriesNode` · `SceneNode` · `StepNode` · `TransformNode` · `ColorizeNode` · `HighlightNode` · `AreaFillNode` · `AnnotationNode` · `PointAnnotationNode` · `RangeAnnotationNode` · `FreeAnnotationNode` · `AnnotationVisibilityNode`
+`ChartNode` · `DataNode` · `PropertyNode` · `SeriesNode` · `SceneNode` · `TransformNode` · `ColorizeNode` · `HighlightNode` · `AreaFillNode` · `AnnotationNode` · `PointAnnotationNode` · `RangeAnnotationNode` · `FreeAnnotationNode` · `AnnotationVisibilityNode`
 
 See [the DSL spec](/reference/dsl/) for the corresponding source-level grammar.
 

package/src/reference/dsl/annotations.md

@@ -1,6 +1,6 @@
 # DSL — Color directives & annotations
 
-Two families of named blocks that target specific data values to draw the eye: **color directives** (`colorize`, `highlight`, `areafill`) recolor or emphasize parts of the chart, and **annotations** (`annotation`, `range`, `note`) attach text and shapes to data points, ranges, or absolute positions. Both share the same "named block with a body" shape, and `highlight` is the verb scenes use to switch emphasis — see [Scenes & transforms](/reference/dsl/scenes-and-transforms).
+Two families of named blocks that target specific data values to draw the eye: **color directives** (`colorize`, `highlight`, `area-fill`) recolor or emphasize parts of the chart, and **annotations** (`annotation`, `range`, `note`) attach text and shapes to data points, ranges, or absolute positions. Both share the same "named block with a body" shape, and `highlight` is the verb scenes use to switch emphasis — see [Scenes & transforms](/reference/dsl/scenes-and-transforms).
 
 ## Color directives
 
@@ -8,7 +8,7 @@ Two families of named blocks that target specific data values to draw the eye: *
 | --- | --- |
 | `colorize "<target>" { … }` | Apply a color rule to a target (axis label, value label, etc.). |
 | `highlight "<target>" { … }` or `highlight "<target>"` | Emphasize a data point or series. The short form has no body. |
-| `areafill "<from>" "<to>" { … }` | Fill the area between two series with a color (line / area charts). |
+| `area-fill "<from>" "<to>" { … }` | Fill the area between two series with a color (line / area charts). |
 
 ### `colorize`
 
@@ -63,17 +63,17 @@ scene "Japan declining" {
 Three scenes share the same data and successively highlight one country each — the canonical "guided tour" pattern.
 :::
 
-### `areafill`
+### `area-fill`
 
 ```bpc
-areafill "Lower bound" "Upper bound" {
+area-fill "Lower bound" "Upper bound" {
   color = "#94a3b8"
   opacity = 0.2
 }
 ```
 
 ::: tip
-No bundled sample currently uses `areafill`. The grammar is documented and parser-tested; the example above is illustrative.
+No bundled sample currently uses `area-fill`. The grammar is documented and parser-tested; the example above is illustrative.
 :::
 
 ## Annotations
@@ -115,13 +115,14 @@ Demonstrates `showLine` + `lineStyle = curve-right` for a labelled callout that
 ### Range and free annotations
 
 ```bpc
-range {                    # range: spans a domain/value window
-  fromX = "2020"
-  toX = "2022"
+range {                    // range: spans a domain/value window
+  orientation = vertical
+  start = "2020"
+  end = "2022"
   text = "Pandemic rally"
 }
 
-note {                     # free: absolutely positioned
+note {                     // free: absolutely positioned
   text = "Methodology footnote"
   x = "10%"
   y = "90%"

package/src/reference/dsl/index.md

@@ -5,7 +5,7 @@ The Blueprint Chart format (`.bpc`) is a declarative text DSL for describing a c
 The canonical grammar lives in [`packages/lib/src/dsl/grammar.peggy`](https://github.com/blueprint-chart/blueprint-chart/blob/main/packages/lib/src/dsl/grammar.peggy). This page is the human-readable specification.
 
 ::: tip Stability
-The DSL is **round-trip safe**: `parse(source)` → `serialize(ast)` → `parse(...)` produces an equivalent AST. Backward-compatible grammar changes ship as minor releases; breaking changes will require a major bump.
+The DSL is **AST round-trip safe**: `parse(source)` → `serialize(ast)` → `parse(...)` produces an equivalent AST. The round trip is over the AST, not the source text. Comments are parsed as whitespace and are **not** preserved through `serialize`, so a re-serialized document drops any `//` or `/* */` comments the author wrote. Comment attachment is tracked on the [roadmap](https://github.com/blueprint-chart/blueprint-chart/blob/main/ROADMAP.md).
 :::
 
 ## A minimal example
@@ -51,12 +51,13 @@ A single-series line chart with a brand color, custom symbol shape, vertical-axi
 
 A BPC document is exactly one `chart` block:
 
+<!-- bpc-no-parse -->
 ```bpc
 chart <chartType> {
   <properties>
   <data block>
   <series>
-  <colorize / highlight / areafill / annotation / range / note>
+  <colorize / highlight / area-fill / annotation / range / note>
   <scenes>
   <transforms>
 }
@@ -80,20 +81,20 @@ Used for chart-type names, property keys, and transform names.
 String ← '"' StringChar* '"'
 ```
 
-Strings are double-quoted. Supported escapes: `\\`, `\"`, `\n`, `\t`, `\r`.
+Strings are double-quoted. Supported escapes: `\\`, `\"`, `\n`, `\t`, `\r`, and `\uXXXX` (four hex digits, decoded to the matching code point). Any other escape sequence is a parse error.
 
 ### Numbers
 
 ```
-Number  ← '-'? Digit+ ('.' Digit+)?
+Number  ← '-'? ('.' Digit+ / Digit+ ('.' Digit*)?) ([eE] [+-]? Digit+)?
 Percent ← Number '%'
 ```
 
-A trailing `%` marks the value as a percentage; the parser preserves `isPercentage: true` on the AST node so downstream code can distinguish `25` from `25%`.
+Numbers accept an optional leading minus, a fractional part (including a leading-dot form such as `.5`), and an optional scientific-notation exponent (`1e3`, `2.5E-4`). A trailing `%` marks the value as a percentage; the parser preserves `isPercentage: true` on the AST node so downstream code can distinguish `25` from `25%`.
 
 ### Comments
 
-Line comments start with `//` and run to end-of-line. There are no block comments.
+Two comment forms exist. Line comments start with `//` and run to end-of-line. Block comments are delimited by `/*` and `*/` and may span multiple lines. Both are treated as whitespace and carry no meaning in the AST.
 
 ## Working with the AST
 
@@ -105,14 +106,14 @@ const text = serialize(ast)      // AST → BPC text (pretty)
 const tight = compactSerialize(ast) // AST → BPC text (compact)
 ```
 
-Round-trip identity is guaranteed for any value the grammar accepts — `parse(serialize(parse(x)))` is structurally equal to `parse(x)`. This invariant is enforced by the test suite.
+For any value the grammar accepts, `parse(serialize(parse(x)))` is structurally equal to `parse(x)`, and the test suite enforces it. The guarantee covers AST structure only: because comments are consumed as whitespace during parsing, `serialize` cannot reproduce them, so the emitted text will differ from a comment-bearing original.
 
 ## Stability and versioning
 
 - `parse` errors throw `SyntaxError` with a 1-indexed `location` (line / column) for tooling.
 - Unknown property keys are preserved on the AST; renderers may ignore them.
 - Unknown top-level statements are a parse error — by design.
-- The grammar version tracks the lib's `MAJOR.MINOR`; patch releases never change the language.
+- While Blueprint Chart is pre-1.0, the grammar may change in any release. Every DSL change is called out in the [CHANGELOG](https://github.com/blueprint-chart/blueprint-chart/blob/main/CHANGELOG.md) under a dedicated **DSL** heading. From 1.0 onward, a breaking grammar change requires a major version bump.
 
 ## See it in action
 
@@ -121,7 +122,7 @@ Every snippet across these DSL pages is taken verbatim from a runnable sample in
 | Feature shown | Sample file | Chart-type page |
 | --- | --- | --- |
 | Minimal example, point annotation | `bitcoin-price.bpc` | [Line chart](/charts/line) |
-| Multi-series data, `_series` row | `medal-count.bpc` | [Bar multi](/charts/bar-multi) |
+| Multi-series data, `series` meta-row | `medal-count.bpc` | [Bar multi](/charts/bar-multi) |
 | `colorize` single category | `letter-frequency.bpc` | [Bar vertical](/charts/bar-vertical) |
 | Curved-leader annotation | `temperature-anomaly.bpc` | [Line chart](/charts/line) |
 | Scene-by-scene `highlight` tour | `co2-emissions-story.bpc` | [Bar horizontal](/charts/bar-horizontal) |
@@ -133,5 +134,5 @@ Every snippet across these DSL pages is taken verbatim from a runnable sample in
 The rest of the DSL specification is split across three chapter pages:
 
 - [Properties & data](/reference/dsl/properties) — value-bearing constructs.
-- [Color directives & annotations](/reference/dsl/annotations) — `colorize`, `highlight`, `areafill`, and the three annotation kinds.
+- [Color directives & annotations](/reference/dsl/annotations) — `colorize`, `highlight`, `area-fill`, and the three annotation kinds.
 - [Scenes & transforms](/reference/dsl/scenes-and-transforms) — story-level constructs and data-pipeline operations.

package/src/reference/dsl/properties.md

@@ -16,7 +16,7 @@ lineSymbolShape = "diamond"
 | Value kind | Example | Notes |
 | --- | --- | --- |
 | String | `"Chrome"` | Double-quoted. |
-| Number | `42`, `3.14`, `-1.2` | Optional minus, optional decimal part. |
+| Number | `42`, `3.14`, `-1.2`, `.5`, `2.5e-4` | Optional minus, optional decimal (leading-dot allowed), optional `e`/`E` exponent. |
 | Percentage | `35%` | Number suffixed with `%`. |
 | Identifier | `true`, `false`, `right` | Used for enum-valued properties. |
 
@@ -36,11 +36,11 @@ data {
 }
 ```
 
-For multi-series data, comma-separated values map positionally to series. A leading `_series = "A","B",…` row labels each column:
+For multi-series data, comma-separated values map positionally to series. A leading `series = "A","B",…` row labels each column. The unquoted key `series` inside a `data` block is reserved for this meta-row; quote your labels (`"series" = …`) if you ever need a real data row by that name:
 
 ```bpc
 data {
-  _series = "Gold","Silver","Bronze"
+  series = "Gold","Silver","Bronze"
   "USA" = 40,44,42
   "China" = 38,32,18
   "Japan" = 27,14,17
@@ -51,7 +51,7 @@ data {
 ```
 
 ::: info From `packages/lib/src/samples/medal-count.bpc`
-A `bar-multi` chart driven by three positional columns. The `_series` row supplies legend labels; each subsequent row's comma-separated values map to those columns in order.
+A `bar-multi` chart driven by three positional columns. The `series` meta-row supplies legend labels; each subsequent row's comma-separated values map to those columns in order.
 :::
 
 A **tabular** form is also accepted — keys and values separated by a literal tab character — for pasting CSV-like input:
@@ -75,5 +75,5 @@ series "Renewables" {
 ```
 
 ::: tip
-None of the bundled `packages/lib/src/samples/*.bpc` files currently exercise top-level `series` overrides — the samples lean on `_series` legends inside `data` plus `colors`, `colorPalette`, and `colorize` directives. The example above is illustrative; the grammar is exercised by parser tests.
+None of the bundled `packages/lib/src/samples/*.bpc` files currently exercise top-level `series` overrides. The samples lean on the `series` meta-row inside `data` plus `colors`, `colorPalette`, and `colorize` directives. The example above is illustrative; the grammar is exercised by parser tests.
 :::

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

@@ -54,7 +54,7 @@ scene "Cash crops replaced vegetables" {
   type = area-stacked
 
   data {
-    _series = "Vegetables","Cash crops","Other production"
+    series = "Vegetables","Cash crops","Other production"
     "2000" = 464,615,1854
     "2008" = 541,2045,1563
     "2015" = 144,2986,785
@@ -72,12 +72,10 @@ Scenes accept the same member set as the top-level chart, **plus** annotation-vi
 
 | Verb | Effect |
 | --- | --- |
-| `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. |
-
-`step` is accepted as an alias for `scene`.
+| `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. |
 
 ## Transforms