apexcharts-skill 1.2.2 → 2.0.1

package/.cursorrules

@@ -1,10 +1,12 @@
 # ApexCharts.js — AI Coding Rules
 
-You are working with ApexCharts.js, a JavaScript charting library.
+You are working with ApexCharts.js (v6), a JavaScript charting library.
 Documentation: https://apexcharts.com/docs/
 NPM: apexcharts
 GitHub: https://github.com/apexcharts/apexcharts.js
 
+v6 is backward compatible: existing v5 configs keep working. New chart types (violin, funnel, pyramid, gauge) and the feature platform (plugins, canvas renderer, custom series, undo/redo, shareable views, themes, crossfilter, annotation authoring, storyboard, streaming, drilldown) are opt-in and tree-shakeable. Two behaviors changed on by default (both respect prefers-reduced-motion): coherent add/remove data-transition animations, and mobile pinch-zoom / two-finger pan.
+
 ## Framework wrapper detection — check `package.json` first
 
 - `react` → use **`react-apexcharts`** instead of the core API.
@@ -27,6 +29,9 @@ Wrappers handle `destroy()` automatically on unmount, accept reactive props, and
 10. **RadialBar values must be 0–100** (percentages).
 11. **Color hex values must include `#`** (e.g., `'#FF5733'`).
 12. **Tree-shaking**: `apexcharts/core` requires separate chart-type + feature imports.
+13. **v6 aliases**: `funnel`/`pyramid` render through bar, `gauge` through radialBar. Use them as `chart.type` directly (no `plotOptions.bar.isFunnel`); covered by `apexcharts/bar` and `apexcharts/radialBar`.
+14. **`violin`** points use a density profile: `data: [{ x, y: { density: [[value, weight], ...], points?: [num] } }]`.
+15. **`render()` is idempotent (v6)**: a repeated `render()` returns the same promise; still `destroy()` before a new instance on the same element.
 
 ---
 
@@ -45,9 +50,12 @@ Wrappers handle `destroy()` automatically on unmount, accept reactive props, and
 | Range Bar | `'rangeBar'` | `[{ data: [{ x, y: [start, end] }] }]` | `[{ data: [{ x: 'Task', y: [1, 5] }] }]` |
 | Candlestick | `'candlestick'` | `[{ data: [{ x, y: [O,H,L,C] }] }]` — 4 values | `[{ data: [{ x: new Date(), y: [51,56,48,53] }] }]` |
 | Box Plot | `'boxPlot'` | `[{ data: [{ x, y: [min,Q1,med,Q3,max] }] }]` — 5 values | `[{ data: [{ x: 'A', y: [10,20,30,40,50] }] }]` |
+| Violin *(v6)* | `'violin'` | `[{ name, data: [{ x, y: { density: [[value,weight],...], points?: [num] } }] }]` | `[{ data: [{ x: 'A', y: { density: [[20,0.1],[30,0.2]], points: [21,29] } }] }]` |
 | Heatmap | `'heatmap'` | `[{ name, data: [{ x, y: number }] }]` — y is intensity | `[{ name: 'Mon', data: [{ x: '10am', y: 45 }] }]` |
 | Treemap | `'treemap'` | `[{ data: [{ x, y: number }] }]` — y is area value | `[{ data: [{ x: 'Item', y: 100 }] }]` |
 | Radar | `'radar'` | `[{ name, data: [num] }]` + `xaxis.categories` | `[{ data: [80, 50, 30] }]` |
+| Funnel *(v6)* | `'funnel'` | `[{ name, data: [num] }]` + `xaxis.categories`; order largest→smallest | `[{ data: [1380, 990, 548, 200] }]` |
+| Pyramid *(v6)* | `'pyramid'` | Same as funnel; order smallest→largest | `[{ data: [200, 548, 990, 1380] }]` |
 
 ### Non-Axis Charts (flat number array — NOT object format)
 
@@ -57,6 +65,9 @@ Wrappers handle `destroy()` automatically on unmount, accept reactive props, and
 
 // Radial Bar (values 0–100)
 { chart: { type: 'radialBar' }, series: [76, 67, 61], labels: ['X', 'Y', 'Z'] }
+
+// Gauge (v6): single value; domain via plotOptions.radialBar.min/max
+{ chart: { type: 'gauge' }, series: [72], labels: ['Progress'] }
 ```
 
 ---
@@ -86,10 +97,11 @@ chart.destroy()                                         // cleanup
 apexcharts              # Full bundle (all types + features)
 apexcharts/core         # Bare core (must register types + features manually)
 apexcharts/line         # line, area, scatter, bubble, rangeArea
-apexcharts/bar          # bar, column, rangeBar
+apexcharts/bar          # bar, column, rangeBar, funnel, pyramid (v6 aliases)
 apexcharts/candlestick  # candlestick, boxPlot
+apexcharts/violin       # violin (v6)
 apexcharts/pie          # pie, donut, polarArea
-apexcharts/radialBar    # radialBar
+apexcharts/radialBar    # radialBar, gauge (v6 alias)
 apexcharts/radar        # radar
 apexcharts/heatmap      # heatmap
 apexcharts/treemap      # treemap
@@ -97,13 +109,28 @@ apexcharts/ssr          # Server-side rendering (Node.js)
 apexcharts/client       # Explicit browser import
 
 # Optional features (side-effect imports)
-apexcharts/features/exports      # dataURI(), exportToCSV()
-apexcharts/features/legend       # Legend component
-apexcharts/features/toolbar      # Zoom, pan, download
-apexcharts/features/annotations  # X/Y/point annotations
-apexcharts/features/keyboard     # Keyboard navigation
-apexcharts/features/all          # All features
+apexcharts/features/exports         # dataURI(), exportToCSV()
+apexcharts/features/legend          # Legend component
+apexcharts/features/toolbar         # Zoom, pan, download
+apexcharts/features/annotations     # X/Y/point annotations
+apexcharts/features/keyboard        # Keyboard navigation
+# v6 feature platform (all opt-in):
+apexcharts/features/morph           # animated chart-type morphs
+apexcharts/features/drilldown       # hierarchical drill-down
+apexcharts/features/history         # undo/redo (Rewind)
+apexcharts/features/perspectives    # shareable view state
+apexcharts/features/storyboard      # scrollytelling
+apexcharts/features/facet           # design tokens + OS themes
+apexcharts/features/weave           # plugin platform
+apexcharts/features/renderer-canvas # hybrid SVG + canvas renderer (Strata)
+apexcharts/features/marks           # custom series types (registerSeriesType)
+apexcharts/features/link            # crossfilter / linked views
+apexcharts/features/ink             # on-chart annotation authoring
+apexcharts/features/measure         # measure / delta ruler
+apexcharts/features/context-menu    # right-click context menu
+apexcharts/features/all             # All features
 ```
+(Cadence easing and real-time streaming are core: no feature import needed.)
 
 ---
 
@@ -223,10 +250,10 @@ apexcharts/features/all          # All features
 
 | Method | Description |
 |---|---|
-| `ApexCharts.renderToString(opts)` | SVG string (server). |
-| `ApexCharts.renderToHTML(opts)` | HTML wrapper + SVG (server). |
-| `ApexCharts.hydrate(el)` | Hydrate SSR chart (client). |
-| `ApexCharts.hydrateAll()` | Hydrate all SSR charts. |
+| `ApexCharts.renderToString(opts, { width, height })` | SVG string (server). |
+| `ApexCharts.renderToHTML(opts, { width, height })` | HTML wrapper + SVG (server). |
+| `ApexCharts.hydrate(el, clientOpts?)` | Hydrate SSR chart (client). |
+| `ApexCharts.hydrateAll(selector?)` | Hydrate all SSR charts. |
 
 ---
 

package/README.md

@@ -16,11 +16,14 @@ AI coding skill for building [ApexCharts.js](https://apexcharts.com/) charts and
 
 AI models frequently generate incorrect ApexCharts code — wrong series data formats, missing `render()` calls, broken formatter signatures, etc. This skill provides structured reference files that help AI assistants generate correct ApexCharts code on the first try.
 
+This skill targets **ApexCharts v6** (backward compatible with v5 configs).
+
 ### Coverage
 
-- **16 chart types**: line, area, bar, pie, donut, radialBar, scatter, bubble, heatmap, candlestick, boxPlot, radar, polarArea, rangeBar, rangeArea, treemap
+- **20 chart types**: line, area, bar, pie, donut, radialBar, scatter, bubble, heatmap, candlestick, boxPlot, violin, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge
 - **Correct data formats** for every chart type
-- **16 common pitfalls** with wrong/correct code examples
+- **Common pitfalls** with wrong/correct code examples
+- **v6 feature platform**: plugins (Weave), canvas renderer (Strata), custom series (Marks), undo/redo (Rewind), shareable views (Perspectives), themes (Facet), easing (Cadence), crossfilter (Link), annotation authoring (Ink), measure ruler, context menu, storyboard, streaming, drilldown
 - **Tree-shaking** and bundle optimization patterns
 - **SSR** (server-side rendering) and hydration
 - **Framework integration**: React, Vue 3, Angular
@@ -76,11 +79,12 @@ const barCharts = await readFile(referencePath('bar-charts.md'), 'utf8');
 ├── .cursorrules                # Self-contained version for Cursor/Windsurf
 ├── references/
 │   ├── cartesian-charts.md     # line, area, scatter, bubble, rangeArea
-│   ├── bar-charts.md           # bar, column, rangeBar, timeline/Gantt
-│   ├── financial-charts.md     # candlestick, boxPlot
-│   ├── circular-charts.md      # pie, donut, polarArea, radialBar
+│   ├── bar-charts.md           # bar, column, rangeBar, timeline/Gantt, funnel, pyramid
+│   ├── financial-charts.md     # candlestick, boxPlot, violin
+│   ├── circular-charts.md      # pie, donut, polarArea, radialBar, gauge
 │   ├── grid-charts.md          # heatmap, treemap
 │   ├── radar-charts.md         # radar
+│   ├── v6-features.md          # v6 feature platform (plugins, canvas, undo/redo, themes, ...)
 │   ├── tree-shaking.md         # bundle optimization
 │   ├── ssr.md                  # server-side rendering
 │   └── framework-wrappers.md   # React, Vue, Angular

package/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: apexcharts
 description: >
-  AI skill for building ApexCharts.js charts and data visualizations.
+  AI skill for building ApexCharts.js charts and data visualizations (targets v6).
   Use when the user asks to create, configure, or troubleshoot any chart using ApexCharts
   (line, area, bar, pie, donut, radialBar, scatter, bubble, heatmap, candlestick, boxPlot,
-  radar, polarArea, rangeBar, rangeArea, treemap). Covers correct data formats, lifecycle,
-  formatters, tree-shaking, SSR, and framework integration. In React /
+  violin, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge). Covers
+  correct data formats, lifecycle, formatters, tree-shaking, SSR, and the v6 feature
+  platform (plugins, canvas renderer, custom series, undo/redo, shareable views, themes,
+  crossfilter, annotation authoring, storyboard, streaming, drilldown). In React /
   Vue / Angular projects, prefer the framework wrapper packages
   (`react-apexcharts`, `vue3-apexcharts`, `ng-apexcharts`) over the core API.
 metadata:
   author: ApexCharts
-  version: "1.2.1"
-  library_version: "5.15.2"
+  version: "2.0.1"
+  library_version: "6.2.0"
   category: data-visualization
   tags: [charts, visualization, javascript, typescript, svg, apexcharts]
   docs: https://apexcharts.com/docs/
@@ -28,6 +30,8 @@ metadata:
 >
 > Wrappers handle `destroy()` automatically on unmount, accept reactive props, and forward events as idiomatic framework events. Use the core API directly only when no framework is detected, or when the user explicitly asks for vanilla. See `references/framework-wrappers.md`.
 
+> **Targets ApexCharts v6.** v6 is backward compatible: existing v5 configs keep working unchanged. Everything new (the plugin platform, canvas renderer, custom series, undo/redo, shareable views, themes, crossfilter, annotation authoring, storyboard, streaming, drilldown) is opt-in and tree-shakeable. Two behaviors changed *on by default* (both respect `prefers-reduced-motion`): (1) data updates that add/remove points now animate coherently, and (2) mobile pinch-zoom / two-finger pan gestures are enabled. See `references/v6-features.md` for the full v6 surface.
+
 ## 1. Critical Rules
 
 1. **Always call `chart.render()`** after `new ApexCharts(el, options)`. The constructor does not render.
@@ -42,6 +46,9 @@ metadata:
 10. **RadialBar values must be 0–100** (they represent percentages).
 11. **Color hex values must include the `#` prefix** (e.g., `'#FF5733'`, not `'FF5733'`).
 12. **Tree-shaking**: importing `apexcharts/core` gives you a bare class — you must also import chart-type entries and feature entries separately.
+13. **v6 first-class aliases**: `funnel` and `pyramid` render through the bar engine; `gauge` renders through radialBar. Use them as `chart.type` directly (no `plotOptions.bar.isFunnel` needed). They are covered by the `apexcharts/bar` and `apexcharts/radialBar` tree-shaking entries respectively.
+14. **`violin` (v6, statistical)** uses a per-point density profile: `data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }]`, not a plain number.
+15. **`render()` is idempotent (v6)**: calling `render()` twice on the same instance returns the same promise instead of building a duplicate chart. You still must `destroy()` before creating a *new* instance on the same element.
 
 ---
 
@@ -62,23 +69,28 @@ This is the most critical reference. Using the wrong data format is the #1 cause
 | Range Bar | `'rangeBar'` | `[{ name, data: [{ x, y: [start, end] }] }]` — for timeline/Gantt, use timestamps | `series: [{ name: 'Tasks', data: [{ x: 'Design', y: [1, 5] }] }]` |
 | Candlestick | `'candlestick'` | `[{ data: [{ x, y: [O, H, L, C] }] }]` — array of 4: Open, High, Low, Close | `series: [{ data: [{ x: new Date('2024-01-01'), y: [51, 56, 48, 53] }] }]` |
 | Box Plot | `'boxPlot'` | `[{ data: [{ x, y: [min, Q1, median, Q3, max] }] }]` — array of 5 | `series: [{ data: [{ x: 'Group A', y: [10, 20, 30, 40, 50] }] }]` |
+| Violin *(v6)* | `'violin'` | `[{ name, data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }] }]` | `series: [{ name: 'Sessions', data: [{ x: 'A', y: { density: [[20, 0.1], [30, 0.2]], points: [21, 29] } }] }]` |
 | Heatmap | `'heatmap'` | `[{ name, data: [{ x, y: number }] }]` — y is the intensity value | `series: [{ name: 'Mon', data: [{ x: '10am', y: 45 }] }]` |
 | Treemap | `'treemap'` | `[{ data: [{ x, y: number }] }]` — y is the area/value | `series: [{ data: [{ x: 'Item A', y: 100 }, { x: 'Item B', y: 60 }] }]` |
 | Radar | `'radar'` | `[{ name, data: [number] }]` + `xaxis: { categories: [...] }` | `series: [{ name: 'Skill', data: [80, 50, 30, 40, 100] }]` |
+| Funnel *(v6)* | `'funnel'` | `[{ name, data: [number] }]` + `xaxis: { categories: [...] }`. Order values **largest→smallest**. | `series: [{ data: [1380, 990, 548, 200] }]` |
+| Pyramid *(v6)* | `'pyramid'` | Same as funnel; order values **smallest→largest** (wide base at bottom). | `series: [{ data: [200, 548, 990, 1380] }]` |
 
-### Non-Axis Charts (pie, donut, radialBar, polarArea)
+### Non-Axis Charts (pie, donut, radialBar, polarArea, gauge)
 
 These use a **flat number array** for `series`, NOT the object format:
 
 ```js
 // CORRECT — flat number array + labels
 {
-  chart: { type: 'pie' },  // or 'donut', 'polarArea', 'radialBar'
+  chart: { type: 'pie' },  // or 'donut', 'polarArea', 'radialBar', 'gauge'
   series: [44, 55, 13, 43, 22],
   labels: ['Team A', 'Team B', 'Team C', 'Team D', 'Team E']
 }
 ```
 
+**Gauge *(v6)*** is a single-value radialBar alias: `series: [72]`, `labels: ['Progress']`. Configure the arc/needle, colored bands, ticks, and `min`/`max` domain through `plotOptions.radialBar` (see `references/circular-charts.md`).
+
 ---
 
 ## 3. Package / Module Map
@@ -101,21 +113,37 @@ import ApexCharts from 'apexcharts/column'        # same as /bar
 import ApexCharts from 'apexcharts/rangeBar'      # same as /bar
 import ApexCharts from 'apexcharts/candlestick'   # candlestick, boxPlot
 import ApexCharts from 'apexcharts/boxPlot'       # same as /candlestick
+import ApexCharts from 'apexcharts/violin'        # violin (v6)
 import ApexCharts from 'apexcharts/pie'           # pie, donut, polarArea
 import ApexCharts from 'apexcharts/donut'         # same as /pie
 import ApexCharts from 'apexcharts/polarArea'     # same as /pie
-import ApexCharts from 'apexcharts/radialBar'     # radialBar only
+import ApexCharts from 'apexcharts/radialBar'     # radialBar + gauge (v6)
 import ApexCharts from 'apexcharts/radar'         # radar only
 import ApexCharts from 'apexcharts/heatmap'       # heatmap only
 import ApexCharts from 'apexcharts/treemap'       # treemap only
+# funnel + pyramid (v6) render through the bar engine; use apexcharts/bar
 
 # Optional features (side-effect imports — just import, no default export needed)
-import 'apexcharts/features/exports'      # PNG/SVG/CSV export methods
-import 'apexcharts/features/legend'       # Interactive legend component
-import 'apexcharts/features/toolbar'      # Toolbar (zoom, pan, download buttons)
-import 'apexcharts/features/annotations'  # X/Y/point/text/image annotations
-import 'apexcharts/features/keyboard'     # Keyboard navigation (accessibility)
-import 'apexcharts/features/all'          # All features at once
+import 'apexcharts/features/exports'         # PNG/SVG/CSV export methods
+import 'apexcharts/features/legend'          # Interactive legend component
+import 'apexcharts/features/toolbar'         # Toolbar (zoom, pan, download buttons)
+import 'apexcharts/features/annotations'     # X/Y/point/text/image annotations
+import 'apexcharts/features/keyboard'        # Keyboard navigation (accessibility)
+# v6 feature platform (all opt-in, all tree-shakeable)
+import 'apexcharts/features/morph'           # Animated chart-type morphs
+import 'apexcharts/features/drilldown'       # Hierarchical drill-down
+import 'apexcharts/features/history'         # Undo/redo (Rewind)
+import 'apexcharts/features/perspectives'    # Shareable view state
+import 'apexcharts/features/storyboard'      # Scrollytelling (includes perspectives)
+import 'apexcharts/features/facet'           # Design tokens + OS-aware themes
+import 'apexcharts/features/weave'           # Public plugin platform
+import 'apexcharts/features/renderer-canvas' # Hybrid SVG + canvas renderer (Strata)
+import 'apexcharts/features/marks'           # Custom series types (registerSeriesType)
+import 'apexcharts/features/link'            # Crossfilter / linked views
+import 'apexcharts/features/ink'             # On-chart annotation authoring
+import 'apexcharts/features/measure'         # Measure / delta ruler
+import 'apexcharts/features/context-menu'    # Right-click / long-press context menu
+import 'apexcharts/features/all'             # All features at once
 
 # SSR (server-side rendering)
 import ApexCharts from 'apexcharts/ssr'    # Node.js: renderToString, renderToHTML
@@ -484,6 +512,19 @@ await chart.updateOptions({ title: { text: 'New Title' } })
 | `addEventListener(name, handler)` | Subscribe to chart event. |
 | `removeEventListener(name, handler)` | Unsubscribe from chart event. |
 
+### v6 Instance Methods (require the matching feature import)
+
+| Method | Feature | Description |
+|---|---|---|
+| `chart.history.undo() / redo() / jump(id) / transaction(fn)` | history | Undo/redo over the command journal. |
+| `chart.perspectives.capture() / toURL() / apply(token)` | perspectives | Serialize / restore the exact view. |
+| `chart.getActiveRenderer()` | renderer-canvas | Returns `'svg' \| 'canvas'` currently in use. |
+| `chart.refreshTokens()` | facet | Re-read `--apx-*` CSS custom properties. |
+| `chart.startMeasure() / stopMeasure() / clearMeasures()` | measure | Drive the measure ruler from code. |
+| `chart.storyboard.bind({ beats }) / goTo() / unbind()` | storyboard | Scroll-driven choreography. |
+| `chart.drillDown(id) / drillUp() / drillToRoot()` | drilldown | Navigate the drill-down hierarchy. |
+| `chart.clearCrossfilter()` | link | Clear active crossfilter selections. |
+
 ### Static Methods
 
 | Method | Description |
@@ -493,15 +534,21 @@ await chart.updateOptions({ title: { text: 'New Title' } })
 | `ApexCharts.merge(target, source)` | Deep-merge objects. |
 | `ApexCharts.use(typeMap)` | Register chart type constructors (tree-shaking). |
 | `ApexCharts.registerFeatures(featureMap)` | Register optional feature modules. |
+| `ApexCharts.registerPlugin(def) / unregisterPlugin(name)` | *(v6, Weave)* Register a reusable plugin. |
+| `ApexCharts.registerSeriesType(name, def) / unregisterSeriesType(name)` | *(v6, Marks)* Register a custom series type. |
+| `ApexCharts.registerTheme(name, def) / unregisterTheme(name)` | *(v6, Facet)* Register a named brand theme. |
+| `ApexCharts.registerEasing(name, fn)` | *(v6, Cadence)* Register a custom easing curve. |
+| `ApexCharts.crossfilter({ id, records }) / getCrossfilter(id)` | *(v6, Link)* Create / fetch a crossfilter engine. |
+| `ApexCharts.perspectives.fromURL(href)` | *(v6)* Decode a perspective token from a URL. |
 
 ### SSR Static Methods (available with `apexcharts/ssr`)
 
 | Method | Description |
 |---|---|
-| `ApexCharts.renderToString(options)` | Render chart to SVG string (Node.js). |
-| `ApexCharts.renderToHTML(options)` | Render chart to HTML string with wrapper (Node.js). |
-| `ApexCharts.hydrate(element)` | Hydrate server-rendered chart (browser). |
-| `ApexCharts.hydrateAll()` | Hydrate all server-rendered charts on page. |
+| `ApexCharts.renderToString(options, { width, height, scale })` | Render chart to raw SVG string (Node.js). |
+| `ApexCharts.renderToHTML(options, { width, height, scale, className })` | Render hydration-ready HTML string (Node.js). |
+| `ApexCharts.hydrate(element, clientOptions?)` | Hydrate a server-rendered chart (browser). |
+| `ApexCharts.hydrateAll(selector?, clientOptions?)` | Hydrate all server-rendered charts on page. |
 | `ApexCharts.isHydrated(element)` | Check if element is already hydrated. |
 
 ---
@@ -537,6 +584,17 @@ await chart.updateOptions({ title: { text: 'New Title' } })
       beforeResetZoom: (chart, options) => {},    // return false to cancel
       scrolled: (chart, { xaxis }) => {},
       selection: (chart, { xaxis, yaxis }) => {},
+
+      // v6 feature events (fire only when the matching feature is enabled)
+      annotationDragged: (chart, options) => {},  // ink
+      annotationEdited: (chart, options) => {},    // ink
+      annotationStyled: (chart, options) => {},    // ink
+      annotationDeleted: (chart, options) => {},   // ink
+      measured: (chart, { from, to, dx, dy, percentChange, slope }) => {}, // measure
+      beatChange: (chart, beatInfo) => {},         // storyboard
+      drillDownStart: (info, chart, options) => {},// drilldown
+      drillDownEnd: (info, chart, options) => {},  // drilldown
+      drillUp: (info, chart, options) => {},       // drilldown
     }
   }
 }
@@ -544,18 +602,40 @@ await chart.updateOptions({ title: { text: 'New Title' } })
 
 ---
 
-## 9. Reference Routing Table
+## 9. v6 Feature Platform (opt-in, tree-shakeable)
+
+All of the following are new in v6, off by default, and each ships as a `apexcharts/features/*` entry. Full config shapes, APIs, and examples are in `references/v6-features.md`. Quick map:
+
+| Feature | Opt-in | One-liner |
+|---|---|---|
+| **Weave** (plugins) | `apexcharts/features/weave` | Publish reusable chart plugins against a stable `ApexCharts.registerPlugin({ name, setup })` API; activate per chart with `plugins: [{ name }]`. |
+| **Strata** (canvas) | `apexcharts/features/renderer-canvas` | `chart: { renderer: 'auto', rendererThreshold }` paints the dense series layer to canvas while axes/tooltips/exports stay SVG. |
+| **Marks** (custom series) | `apexcharts/features/marks` | `ApexCharts.registerSeriesType(name, { renderItem })` for first-class custom marks (lollipop, dumbbell, bullet). Baseline is `scales.y(0)`, **not** `api.zeroY`. |
+| **Rewind** (undo/redo) | `apexcharts/features/history` | `chart: { history: { enabled: true } }`, then `chart.history.undo()/redo()/jump()/transaction()`. |
+| **Perspectives** (view state) | `apexcharts/features/perspectives` | `chart.perspectives.capture()/toURL()/apply()` to serialize and restore the exact view. |
+| **Facet** (themes/tokens) | `apexcharts/features/facet` | `theme: { follow: 'os', name }`, `--apx-*` CSS custom props, `ApexCharts.registerTheme`. |
+| **Cadence** (easing) | core | `chart.animations.easing` accepts a named curve, cubic-bezier array, or function; `ApexCharts.registerEasing`. |
+| **Link** (crossfilter) | `apexcharts/features/link` | `chart: { group, link: { enabled, mode } }` for highlight linking; `ApexCharts.crossfilter({ id, records })` for a filter engine. |
+| **Ink** (annotation authoring) | `apexcharts/features/ink` | `chart: { ink: { enabled: true } }` makes annotations draggable/resizable with a floating editor. |
+| **Measure** (ruler) | `apexcharts/features/measure` | `chart: { measure: { enabled, mode } }`; hold a key and drag to read change/percent/slope. v6.1 adds a toolbar tool (`toolbar.tools.measure`, `toolbar.autoSelected: 'measure'`). |
+| **Context menu** | `apexcharts/features/context-menu` | `chart: { contextMenu: { enabled, items } }` for point-specific right-click actions. |
+| **Storyboard** (scrollytelling) | `apexcharts/features/storyboard` | `chart.storyboard.bind({ beats })` pairs prose sections with saved views. |
+| **Streaming** | core | `chart: { streaming: { enabled, maxPoints } }` for constant-velocity rolling-window scroll. |
+| **Drilldown** | `apexcharts/features/drilldown` | `drilldown: { enabled, series }` + a `drilldown` id on data points; `chart.drillDown()/drillUp()`. |
+
+## 10. Reference Routing Table
 
 For detailed chart-family-specific options, data format variants, and full working examples, refer to:
 
 | Topic | Reference File |
 |---|---|
 | Line, Area, Scatter, Bubble, Range Area | `references/cartesian-charts.md` |
-| Bar, Column, Range Bar, Timeline/Gantt | `references/bar-charts.md` |
-| Candlestick, Box Plot | `references/financial-charts.md` |
-| Pie, Donut, Polar Area, Radial Bar | `references/circular-charts.md` |
+| Bar, Column, Range Bar, Timeline/Gantt, Funnel, Pyramid | `references/bar-charts.md` |
+| Candlestick, Box Plot, Violin | `references/financial-charts.md` |
+| Pie, Donut, Polar Area, Radial Bar, Gauge | `references/circular-charts.md` |
 | Heatmap, Treemap | `references/grid-charts.md` |
 | Radar | `references/radar-charts.md` |
+| v6 feature platform (plugins, canvas, undo/redo, themes, crossfilter, storyboard, ...) | `references/v6-features.md` |
 | Tree-shaking, Bundle optimization | `references/tree-shaking.md` |
 | Server-side rendering, Hydration | `references/ssr.md` |
 | React, Vue, Angular integration | `references/framework-wrappers.md` |

package/index.js

@@ -26,6 +26,7 @@ export const referenceFiles = [
   'radar-charts.md',
   'ssr.md',
   'tree-shaking.md',
+  'v6-features.md',
 ];
 
 /** Resolve a reference file by its filename. Throws if not in the known list. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apexcharts-skill",
-  "version": "1.2.2",
+  "version": "2.0.1",
   "description": "AI coding skill for ApexCharts.js — structured reference docs that help AI assistants (Claude, Cursor, Copilot, etc.) generate correct ApexCharts code.",
   "keywords": [
     "apexcharts",

package/references/bar-charts.md

@@ -5,6 +5,8 @@
 - **Column** (`'bar'`) — Vertical column chart (the default for `type: 'bar'`)
 - **Bar** (`'bar'` + `plotOptions.bar.horizontal: true`) — Horizontal bar chart
 - **Range Bar** (`'rangeBar'`) — Bars with start/end values (used for timelines, Gantt charts)
+- **Funnel** (`'funnel'`, **new in v6**): Stage-by-stage drop-off chart
+- **Pyramid** (`'pyramid'`, **new in v6**): A funnel with the wide base at the bottom
 
 ## Tree-Shakeable Import
 
@@ -12,8 +14,11 @@
 import ApexCharts from 'apexcharts/bar'
 // Registers: bar, column, rangeBar
 // Aliases: apexcharts/column, apexcharts/rangeBar
+// Also covers funnel + pyramid (they normalize to the bar engine in v6)
 ```
 
+**v6 note:** `funnel` and `pyramid` are first-class `chart.type` aliases that render through the bar engine. Use them directly as `chart.type`; you do **not** need `plotOptions.bar.isFunnel`. `plotOptions.funnel` carries the funnel-specific shape options.
+
 ---
 
 ## Data Formats
@@ -140,6 +145,43 @@ import ApexCharts from 'apexcharts/bar'
 }
 ```
 
+### Funnel (v6)
+
+Values are a flat number array in the standard `[{ name, data }]` wrapper; stage labels go in `xaxis.categories`. Order values **largest → smallest**.
+
+```js
+{
+  chart: { type: 'funnel', height: 350 },
+  series: [{ name: 'Recruitment', data: [1380, 1100, 990, 880, 740, 548, 330, 200] }],
+  xaxis: { categories: ['Sourced', 'Screened', 'Assessed', 'HR', 'Technical', 'Verify', 'Offered', 'Hired'] },
+  plotOptions: {
+    // shape: 'rectangle' (default, centered rectangles) | 'trapezoid' (continuous sloped sides)
+    funnel: { shape: 'trapezoid', lastShape: 'flat' },  // lastShape: 'flat' | 'taper' (trapezoid only)
+    bar: { borderRadius: 0, barHeight: '80%' }           // cosmetic bar props still apply
+  },
+  dataLabels: {
+    enabled: true,
+    formatter: (val, opt) => opt.w.globals.labels[opt.dataPointIndex] + ':  ' + val
+  },
+  legend: { show: false }
+}
+```
+
+### Pyramid (v6)
+
+Same shape as funnel, but order values **smallest → largest** so the wide base sits at the bottom.
+
+```js
+{
+  chart: { type: 'pyramid', height: 350 },
+  series: [{ name: '', data: [200, 330, 548, 740, 880, 990, 1100, 1380] }],
+  xaxis: { categories: ['Sweets', 'Processed', 'Fats', 'Meat', 'Legumes', 'Dairy', 'Produce', 'Grains'] },
+  plotOptions: { bar: { distributed: true } },  // one color per stage
+  dataLabels: { enabled: true, formatter: (val, opt) => opt.w.globals.labels[opt.dataPointIndex] },
+  legend: { show: false }
+}
+```
+
 ---
 
 ## Key plotOptions.bar Options
@@ -242,3 +284,5 @@ series: [{
 3. **Range Bar with single value instead of array** — `y` must be `[start, end]`, not a single number.
 4. **Timeline without `xaxis.type: 'datetime'`** — date-based range bars need `xaxis: { type: 'datetime' }` to render correctly.
 5. **`distributed: true` with multiple series** — distributed coloring applies to each data point independently. With multiple series, each point gets a unique color which is usually not desired. Use `distributed: true` only with single-series charts.
+6. **Funnel/pyramid value ordering**: funnel expects values ordered largest-to-smallest and pyramid smallest-to-largest. The renderer does not sort for you; unsorted data produces a jagged shape. Stage labels come from `xaxis.categories`, and per-stage labels in `dataLabels.formatter` are read via `opt.w.globals.labels[opt.dataPointIndex]`.
+7. **Reaching for `plotOptions.bar.isFunnel` in v6**: unnecessary. Set `chart.type: 'funnel'` (or `'pyramid'`) and use `plotOptions.funnel` for shape options.

package/references/circular-charts.md

@@ -5,7 +5,8 @@
 - **Pie** (`'pie'`) — Standard pie chart
 - **Donut** (`'donut'`) — Pie chart with hollow center
 - **Polar Area** (`'polarArea'`) — Radial segments with equal angles, varying radius
-- **Radial Bar** (`'radialBar'`) — Circular progress/gauge chart
+- **Radial Bar** (`'radialBar'`): Circular progress chart (one or more concentric tracks)
+- **Gauge** (`'gauge'`, **new in v6**): Single-value gauge with arc/needle shapes, colored bands, and ticks
 
 ## Tree-Shakeable Import
 
@@ -16,6 +17,7 @@ import ApexCharts from 'apexcharts/pie'
 
 import ApexCharts from 'apexcharts/radialBar'
 // Registers: radialBar (separate entry point)
+// Also covers gauge (it normalizes to the radialBar engine in v6)
 ```
 
 ---
@@ -46,6 +48,52 @@ import ApexCharts from 'apexcharts/radialBar'
 
 **Important:** RadialBar values represent percentages (0–100). Values above 100 will overflow the track.
 
+### Gauge (v6)
+
+A gauge is a single-value `radialBar` alias. Series is a flat one-element array; the value maps to the `min..max` domain (defaults 0-100). All configuration lives under `plotOptions.radialBar`; there is **no `plotOptions.gauge`**.
+
+```js
+// Minimal gauge:
+{
+  chart: { type: 'gauge', height: 350 },
+  series: [72],
+  labels: ['Progress']
+}
+```
+
+```js
+// Needle gauge with colored bands and ticks:
+{
+  chart: { type: 'gauge', height: 360 },
+  series: [68],
+  labels: ['Speed'],
+  plotOptions: {
+    radialBar: {
+      shape: 'needle',          // 'arc' (default, filled value-arc) | 'needle' (rotating pointer)
+      startAngle: -135, endAngle: 135,
+      min: 0, max: 100,          // value-to-angle domain
+      bands: [                   // colored threshold segments in the min..max domain
+        { from: 0, to: 30, color: '#FF4560' },
+        { from: 30, to: 70, color: '#FEB019' },
+        { from: 70, to: 100, color: '#00E396' }
+      ],
+      bandsStyle: { strokeWidth: '50%', gap: 1 },
+      ticks: {
+        show: true,
+        major: { count: 11, length: 8, width: 2, color: '#334155', placement: 'outside' },
+        minor: { count: 1, length: 4, width: 1, color: '#94A3B8', placement: 'outside' },
+        labels: { show: true, offset: 6, fontSize: '11px' }
+      },
+      needle: { color: '#0F172A', length: '60%', baseWidth: 6, tipWidth: 1 },
+      hollow: { size: '70%' },
+      dataLabels: { name: { show: false }, value: { offsetY: 32, fontSize: '28px', fontWeight: 700 } }
+    }
+  }
+}
+```
+
+A plain radialBar is effectively a gauge with `shape: 'arc'`. A semi-circle gauge is `startAngle: -90, endAngle: 90`.
+
 ---
 
 ## Key plotOptions
@@ -216,3 +264,5 @@ plotOptions: {
 4. **Donut center labels not showing** — must set `plotOptions.pie.donut.labels.show: true` explicitly.
 5. **`total.formatter` signature** — receives `w` (the full chart config object), NOT a simple value. Access `w.globals.seriesTotals` for the array of current values.
 6. **Polar Area confused with Radar** — polar area uses `series: [num]` (flat), radar uses `series: [{ data: [num] }]` (axis format). They look similar but have different data shapes.
+7. **Looking for `plotOptions.gauge`**: it does not exist. Gauge is a `radialBar` alias; configure `shape`, `bands`, `ticks`, `needle`, and `min`/`max` under `plotOptions.radialBar`.
+8. **Gauge value outside `min`/`max`**: unlike a plain radialBar (fixed 0-100), a gauge maps its value to the `min..max` domain you set. A value beyond that domain saturates at the arc ends.

package/references/financial-charts.md

@@ -1,9 +1,10 @@
-# Financial Charts Reference — ApexCharts
+# Financial & Statistical Charts Reference — ApexCharts
 
 ## Chart Types Covered
 
 - **Candlestick** (`'candlestick'`) — OHLC (Open, High, Low, Close) financial chart
 - **Box Plot** (`'boxPlot'`) — Statistical distribution chart showing min, Q1, median, Q3, max
+- **Violin** (`'violin'`, **new in v6**): Statistical distribution chart showing a density curve per category, optionally with the raw sample points overlaid as jitter
 
 ## Tree-Shakeable Import
 
@@ -11,6 +12,9 @@
 import ApexCharts from 'apexcharts/candlestick'
 // Registers: candlestick, boxPlot
 // Alias: apexcharts/boxPlot
+
+import ApexCharts from 'apexcharts/violin'
+// Registers: violin (separate entry point, new in v6)
 ```
 
 ---
@@ -68,6 +72,57 @@ The `y` value must be an array of exactly 5 numbers: `[min, Q1, median, Q3, max]
 }
 ```
 
+### Violin: Density Profile (v6)
+
+Each point is `{ x, y: { density, points } }`:
+
+- `density` (**required**): an array of `[value, weight]` pairs describing the precomputed density/KDE profile.
+- `points` (optional): a flat array of raw observations, rendered as jitter dots.
+
+```js
+{
+  chart: { type: 'violin', height: 420 },
+  series: [{
+    name: 'Session duration',
+    data: [
+      {
+        x: 'Direct',
+        y: {
+          density: [[20, 0.02], [30, 0.08], [40, 0.18], [50, 0.10], [60, 0.03]], // [value, weight]
+          points: [22, 31, 38, 41, 47, 52, 58]                                    // raw observations
+        }
+      },
+      {
+        x: 'Referral',
+        y: {
+          density: [[25, 0.03], [35, 0.12], [45, 0.20], [55, 0.09], [65, 0.02]],
+          points: [27, 34, 44, 48, 53, 61]
+        }
+      }
+    ]
+  }],
+  plotOptions: {
+    violin: {
+      bandwidthScale: 1,          // multiplies the density-derived half-width
+      normalize: 'individual',     // 'individual' (each violin to its own peak) | 'group' (shared scale)
+      points: { show: false }      // set show:true to overlay the raw points as jitter
+    }
+  }
+}
+```
+
+**Orientation and per-category color come from `plotOptions.bar`** (violin reuses the bar renderer):
+
+```js
+plotOptions: {
+  bar: { horizontal: true, distributed: true },  // horizontal violins, one color each
+  violin: {
+    normalize: 'group',
+    points: { show: true, shape: 'circle', size: 3, jitter: 0.9, strokeWidth: 0 }
+  }
+}
+```
+
 ---
 
 ## Key plotOptions
@@ -155,3 +210,5 @@ plotOptions: {
 3. **Using simple numeric array** — `data: [10, 20, 30]` does NOT work for candlestick/boxPlot. Each point requires an array in `y`.
 4. **Missing `xaxis.type: 'datetime'`** — candlestick charts with date x-values need `xaxis: { type: 'datetime' }` to format dates correctly.
 5. **Confusing candlestick with boxPlot** — candlestick is 4 values (OHLC), boxPlot is 5 values (five-number summary). They share the same entry point but have different data shapes.
+6. **Violin with a plain numeric `y`**: violin points need `y: { density: [[value, weight], ...] }`, not a number. The `density` profile is precomputed (ApexCharts does not run a KDE for you); `points` for the raw-sample jitter overlay is optional.
+7. **Violin orientation set on the wrong namespace**: horizontal violins and per-violin colors come from `plotOptions.bar` (`horizontal`, `distributed`), while `bandwidthScale`, `normalize`, and `points` live under `plotOptions.violin`.

package/references/ssr.md

@@ -22,37 +22,43 @@ import ApexCharts from 'apexcharts/client'
 
 ## Server-Side API
 
-### renderToString(options)
+### renderToString(options, ssrOptions?)
 
-Returns a raw SVG string suitable for embedding:
+Returns a raw SVG string suitable for embedding. Pass width/height in the **second** argument (SSR has no DOM to measure).
 
 ```js
 import ApexCharts from 'apexcharts/ssr'
 
-const svgString = await ApexCharts.renderToString({
-  chart: { type: 'line', height: 350, width: 600 },
-  series: [{ name: 'Sales', data: [30, 40, 35, 50] }],
-  xaxis: { categories: ['Q1', 'Q2', 'Q3', 'Q4'] }
-})
+// renderToString(options, { width?, height?, scale? })
+const svgString = await ApexCharts.renderToString(
+  {
+    chart: { type: 'line' },
+    series: [{ name: 'Sales', data: [30, 40, 35, 50] }],
+    xaxis: { categories: ['Q1', 'Q2', 'Q3', 'Q4'] }
+  },
+  { width: 600, height: 350 }
+)
 
 // svgString is raw <svg>...</svg> markup
 ```
 
-### renderToHTML(options)
+### renderToHTML(options, ssrOptions?)
 
 Returns an HTML string with a wrapper `<div>` containing the SVG, ready for hydration:
 
 ```js
-const htmlString = await ApexCharts.renderToHTML({
-  chart: {
-    type: 'bar',
-    height: 350,
-    width: 600,
-    id: 'my-chart'   // id is important for hydration targeting
+// renderToHTML(options, { width?, height?, scale?, className? })
+const htmlString = await ApexCharts.renderToHTML(
+  {
+    chart: {
+      type: 'bar',
+      id: 'my-chart'   // id is important for hydration targeting
+    },
+    series: [{ data: [44, 55, 41, 67] }],
+    xaxis: { categories: ['A', 'B', 'C', 'D'] }
   },
-  series: [{ data: [44, 55, 41, 67] }],
-  xaxis: { categories: ['A', 'B', 'C', 'D'] }
-})
+  { width: 600, height: 350 }
+)
 
 // htmlString is <div id="my-chart" data-apexcharts>...<svg>...</svg></div>
 ```
@@ -63,19 +69,19 @@ const htmlString = await ApexCharts.renderToHTML({
 
 After the server-rendered HTML is in the DOM, hydrate it to make it interactive:
 
-### hydrate(element)
+### hydrate(element, clientOptions?)
 
 ```js
 import ApexCharts from 'apexcharts'
 
-// Hydrate a specific chart element
+// Hydrate a specific chart element (optionally merge client-only options)
 const chart = ApexCharts.hydrate(document.querySelector('#my-chart'))
 ```
 
-### hydrateAll()
+### hydrateAll(selector?, clientOptions?)
 
 ```js
-// Hydrate all server-rendered charts on the page
+// Hydrate all server-rendered charts on the page (optionally scope by selector)
 ApexCharts.hydrateAll()
 ```
 
@@ -101,11 +107,14 @@ import ApexCharts from 'apexcharts/ssr'
 const app = express()
 
 app.get('/', async (req, res) => {
-  const chartHTML = await ApexCharts.renderToHTML({
-    chart: { type: 'line', height: 350, width: 600, id: 'sales-chart' },
-    series: [{ name: 'Sales', data: [30, 40, 35, 50, 49, 60] }],
-    xaxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] }
-  })
+  const chartHTML = await ApexCharts.renderToHTML(
+    {
+      chart: { type: 'line', id: 'sales-chart' },
+      series: [{ name: 'Sales', data: [30, 40, 35, 50, 49, 60] }],
+      xaxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] }
+    },
+    { width: 600, height: 350 }
+  )
 
   res.send(`
     <!DOCTYPE html>
@@ -136,11 +145,14 @@ app.listen(3000)
 import ApexCharts from 'apexcharts/ssr'
 
 export default async function Page() {
-  const chartHTML = await ApexCharts.renderToHTML({
-    chart: { type: 'line', height: 350, id: 'my-chart' },
-    series: [{ data: [10, 20, 30] }],
-    xaxis: { categories: ['A', 'B', 'C'] }
-  })
+  const chartHTML = await ApexCharts.renderToHTML(
+    {
+      chart: { type: 'line', id: 'my-chart' },
+      series: [{ data: [10, 20, 30] }],
+      xaxis: { categories: ['A', 'B', 'C'] }
+    },
+    { width: 600, height: 350 }
+  )
 
   return (
     <>
@@ -176,11 +188,14 @@ export default function HydrateCharts() {
 // Server-side
 const chartHTML = await useAsyncData('chart', async () => {
   const ApexCharts = (await import('apexcharts/ssr')).default
-  return await ApexCharts.renderToHTML({
-    chart: { type: 'bar', height: 350, id: 'my-chart' },
-    series: [{ data: [44, 55, 41] }],
-    xaxis: { categories: ['A', 'B', 'C'] }
-  })
+  return await ApexCharts.renderToHTML(
+    {
+      chart: { type: 'bar', id: 'my-chart' },
+      series: [{ data: [44, 55, 41] }],
+      xaxis: { categories: ['A', 'B', 'C'] }
+    },
+    { width: 600, height: 350 }
+  )
 })
 
 // Client-side hydration
@@ -197,5 +212,5 @@ onMounted(async () => {
 
 1. **Using `apexcharts` in Node.js without SSR methods** — the default export auto-resolves based on environment, but `renderToString` is only available via `apexcharts/ssr`.
 2. **Forgetting to hydrate on the client** — server-rendered charts are static SVGs. Without `hydrate()`, they have no interactivity (no tooltips, zoom, click events).
-3. **Missing `chart.width`** — SSR has no DOM to measure container width. Always provide explicit `width` for server rendering.
+3. **Missing width/height**: SSR has no DOM to measure. Pass explicit dimensions in the **second** argument: `renderToString(options, { width, height })` / `renderToHTML(options, { width, height })`.
 4. **Hydrating before DOM is ready** — call `hydrate()` after the server-rendered HTML is in the DOM (use `onMounted`, `useEffect`, or `DOMContentLoaded`).

package/references/tree-shaking.md

@@ -6,7 +6,7 @@ ApexCharts supports three import strategies with different bundle sizes:
 
 | Strategy | Import | Includes |
 |---|---|---|
-| Full bundle | `import ApexCharts from 'apexcharts'` | All 16 chart types + all features |
+| Full bundle | `import ApexCharts from 'apexcharts'` | All chart types + all features |
 | Per-type entry | `import ApexCharts from 'apexcharts/line'` | Specific chart family + core (no optional features) |
 | Bare core | `import ApexCharts from 'apexcharts/core'` | Core class only — must manually register everything |
 
@@ -28,14 +28,17 @@ Each entry point registers a family of related chart types:
 | `apexcharts/rangeBar` | same as /bar |
 | `apexcharts/candlestick` | candlestick, boxPlot |
 | `apexcharts/boxPlot` | same as /candlestick |
+| `apexcharts/violin` | violin *(new in v6)* |
 | `apexcharts/pie` | pie, donut, polarArea |
 | `apexcharts/donut` | same as /pie |
 | `apexcharts/polarArea` | same as /pie |
-| `apexcharts/radialBar` | radialBar |
+| `apexcharts/radialBar` | radialBar, **gauge** *(v6 alias)* |
 | `apexcharts/radar` | radar |
 | `apexcharts/heatmap` | heatmap |
 | `apexcharts/treemap` | treemap |
 
+**v6 first-class aliases:** `funnel` and `pyramid` render through the bar engine, so `apexcharts/bar` covers them. `gauge` renders through radialBar, so `apexcharts/radialBar` covers it. There is no separate `apexcharts/funnel`, `apexcharts/pyramid`, or `apexcharts/gauge` entry.
+
 ### Using Multiple Chart Types
 
 ```js
@@ -57,9 +60,22 @@ Features are optional modules that add functionality. When using per-type entrie
 | Annotations | `import 'apexcharts/features/annotations'` | X/Y/point/text/image annotations |
 | Exports | `import 'apexcharts/features/exports'` | `dataURI()`, `getSvgString()`, `exportToCSV()` |
 | Keyboard | `import 'apexcharts/features/keyboard'` | Keyboard navigation (accessibility) |
+| Morph *(v6)* | `import 'apexcharts/features/morph'` | Animated chart-type morphs |
+| Drilldown *(v6)* | `import 'apexcharts/features/drilldown'` | Hierarchical drill-down |
+| History / Rewind *(v6)* | `import 'apexcharts/features/history'` | Undo/redo (`chart.history`) |
+| Perspectives *(v6)* | `import 'apexcharts/features/perspectives'` | Shareable view state |
+| Storyboard *(v6)* | `import 'apexcharts/features/storyboard'` | Scrollytelling (includes perspectives) |
+| Facet *(v6)* | `import 'apexcharts/features/facet'` | Design tokens + OS-aware themes |
+| Weave *(v6)* | `import 'apexcharts/features/weave'` | Public plugin platform |
+| Renderer / Strata *(v6)* | `import 'apexcharts/features/renderer-canvas'` | Hybrid SVG + canvas renderer |
+| Marks *(v6)* | `import 'apexcharts/features/marks'` | Custom series types (`registerSeriesType`) |
+| Link *(v6)* | `import 'apexcharts/features/link'` | Crossfilter / linked views |
+| Ink *(v6)* | `import 'apexcharts/features/ink'` | On-chart annotation authoring |
+| Measure *(v6)* | `import 'apexcharts/features/measure'` | Measure / delta ruler |
+| Context menu *(v6)* | `import 'apexcharts/features/context-menu'` | Right-click / long-press context menu |
 | All | `import 'apexcharts/features/all'` | All of the above |
 
-**Important:** Tooltip is always included in core — it cannot be tree-shaken.
+**Important:** Tooltip is always included in core (it cannot be tree-shaken). Easing (Cadence) and real-time streaming are also core, so they need no feature import. See `v6-features.md` for the config and API of each v6 feature.
 
 ### What Happens If You Forget a Feature
 

package/references/v6-features.md

@@ -0,0 +1,432 @@
+# v6 Feature Platform: ApexCharts
+
+ApexCharts v6 adds an opt-in, tree-shakeable feature platform on top of the v5 core. **Every v5 config keeps working unchanged.** Each feature below is off by default and ships as its own `apexcharts/features/*` entry, so it only enters your bundle when you import it. When using the full `apexcharts` bundle, all features are already present.
+
+Two behaviors changed *on by default* (both respect `prefers-reduced-motion`):
+
+1. **Coherent variable-length data transitions**: updates that add/remove data points animate as one coordinated motion instead of popping. Appended bars grow from the baseline, removed bars shrink and fade, line/area fills reshape over the union of old and new points, and markers/bubbles/axis labels ride along. Scatter and bubble now animate on dynamic updates for the first time. Disable per chart with `chart.animations.dynamicAnimation.enabled: false`; auto-skipped above `chart.animations.largeDatasetThreshold` (default 1000) and under `prefers-reduced-motion`.
+2. **Native-feeling mobile gestures**: two-finger pinch-zoom, two-finger pan, and kinetic inertia after a flick, with axis rails so a vertical swipe still scrolls the page. Configure via `chart.zoom.pinch` (default `true`) and `chart.pan.inertia` (default `true`, `friction` default `0.92`).
+
+Also new by default: **`render()` is idempotent**: a repeated `render()` (e.g. a framework double-invoking an effect) returns the same promise instead of building a duplicate chart. `destroy()` clears it so an instance can render fresh.
+
+---
+
+## Weave: public plugin platform
+
+`import 'apexcharts/features/weave'`
+
+Publish reusable chart plugins to npm against a stable, versioned API. A plugin draws into its own sandboxed layer and subscribes to lifecycle hooks; it never touches raw internal state.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/weave'
+
+ApexCharts.registerPlugin({
+  name: 'watermark',
+  apiVersion: 1,
+  setup(api) {
+    api.on('draw', () => {
+      const layer = api.layer({ z: 'front', className: 'wm' }) // z: 'front' | 'behind'
+      layer.text({ x: 10, y: 20, text: 'ACME', size: '12px', color: '#999' })
+    })
+  },
+  destroy(api) {},
+})
+// ApexCharts.unregisterPlugin('watermark')  // for tests / hot reload
+
+// Activate per chart:
+const options = { plugins: [{ name: 'watermark', options: { /* frozen, live */ }, order: 0 }] }
+```
+
+The `setup(api)` facade:
+
+- `api.on(hook, fn)` / `api.off(hook, fn)`: hooks: `'afterParse' | 'afterScales' | 'draw' | 'afterUpdate' | 'destroy'`.
+- `api.layer(opts?)`: a plugin-owned drawing surface (`path`, `line`, `rect`, `circle`, `text`, `clear`); call it inside draw handlers only, layers are wiped each pass.
+- `api.scales` (readonly): `x(v)`, `y(v, axis?)`, `domainX`, `domainY(axis?)`, `gridWidth`, `gridHeight`, `ratios`.
+- `api.data` (readonly): `[{ name?, hidden, color?, points: [{ x, y }] }]`.
+- `api.theme`: `{ mode, foreColor, seriesColor(i), token(name) }`.
+- `api.store`: per-instance mutable state bag.
+- `api.emit(name, detail?)`: dispatches `plugin:<name>:<event>` on the chart; `api.chart`, `api.el`, `api.name`, `api.version`, `api.options` round out the facade.
+
+`apiVersion` gates the contract so raw internals can keep changing safely.
+
+---
+
+## Strata: hybrid SVG + canvas renderer
+
+`import 'apexcharts/features/renderer-canvas'`
+
+Break the SVG node ceiling without leaving SVG behind. Below a threshold the output is identical SVG; above it, only the series layer becomes a `<canvas>` while axes, grid, tooltips, annotations, and exports stay SVG.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/renderer-canvas'
+
+const options = {
+  chart: {
+    renderer: 'auto',        // 'svg' | 'canvas' | 'auto'
+    rendererThreshold: 5000, // point count above which 'auto' picks canvas
+  },
+}
+// chart.getActiveRenderer()  // => 'svg' | 'canvas'
+```
+
+Canvas is live for line, area, bar, column, scatter, and candlestick, with shared tooltip, crosshair, zoom, pan, hover/legend dimming, and PNG/SVG export all working. It falls back to SVG automatically for canvas-unsupported features (pattern/image fills, color-matrix filters). Per-point selection visuals and keyboard traversal on canvas remain SVG-only for now.
+
+---
+
+## Marks: composable custom series types
+
+`import 'apexcharts/features/marks'`
+
+Register a `renderItem(ctx)` function and get a first-class series: events, shared tooltip, legend, and keyboard navigation all work with no extra wiring. Dumbbell, lollipop, and bullet ship as samples.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/marks'
+
+ApexCharts.registerSeriesType('lollipop', {
+  // dataType?: 'xy' (default) | 'rangeXY' | 'custom'
+  // yExtent?: (datum, i) => number | number[]   // folds extra values into the y-scale
+  // tooltip?: (datum) => number | number[] | string
+  renderItem(ctx) {
+    const baseline = ctx.scales.y(0)               // IMPORTANT: baseline is scales.y(0), NOT api.zeroY
+    ctx.api.line({ x1: ctx.x, y1: baseline, x2: ctx.x, y2: ctx.y, stroke: ctx.color, width: 2 })
+    ctx.api.circle({ cx: ctx.x, cy: ctx.y, r: 6, fill: ctx.color })
+  },
+})
+
+const options = {
+  chart: { type: 'lollipop' },
+  series: [{ name: 'Signups', data: [{ x: 'Jan', y: 41 }, { x: 'Feb', y: 58 }] }],
+}
+```
+
+**`renderItem` context** (`ctx`): `{ datum, x, y, scales, api, seriesIndex, dataPointIndex, color }`: `x`/`y` are resolved pixels for the datum, `color` is the series palette color.
+
+**`ctx.api` primitives**: `api.path({ d, stroke, width, fill, opacity, dash, lineCap })`, `api.line({ x1, y1, x2, y2, stroke, width, dash })`, `api.rect({ x, y, w, h, r, fill, stroke, strokeWidth, opacity })`, `api.circle({ cx, cy, r, fill, stroke, strokeWidth })`, `api.text({ x, y, text, anchor, size, color, weight })`.
+
+**`ctx.scales`**: `scales.x(value)`, `scales.xAt(index, value)`, `scales.y(value, axis?)`, `scales.gridWidth`, `scales.gridHeight`, `scales.band` (pixel width of one x step / band). There is **no `api.zeroY`**: use `scales.y(0)` for the baseline.
+
+Dumbbell uses `dataType: 'rangeXY'` (datum `y` is `[start, end]`, both bounds folded into the axis); bullet uses `yExtent` to fold `target`/top-band into the y-scale. Built-in type names are guarded against shadowing.
+
+---
+
+## Rewind: history and undo/redo
+
+`import 'apexcharts/features/history'`
+
+Generic Ctrl-Z over a command journal. Zooms, series toggles, option changes, and annotation edits are recorded; high-frequency gestures coalesce into a single step.
+
+```js
+const options = {
+  chart: { history: { enabled: true, maxDepth: 50, coalesceMs: 300, keyboard: true } },
+}
+
+chart.history.undo(animate?)   // and .redo(animate?)
+chart.history.canUndo()        // and .canRedo()  -> boolean
+chart.history.jump(id, animate?)
+chart.history.clear()
+await chart.history.transaction(() => { /* batched edits */ }, { label: 'batch' })
+chart.history.entries()        // [{ id, label, at }]
+```
+
+---
+
+## Perspectives: shareable view state
+
+`import 'apexcharts/features/perspectives'`
+
+Serialize the exact view (zoom window, hidden series, selection, annotations, theme) into a compact token you can put in a URL and restore anywhere.
+
+```js
+const token = chart.perspectives.capture()             // { v, view, options? }
+const str   = chart.perspectives.encode(token)
+const url   = chart.perspectives.toURL()               // href with #apex=<token>
+chart.perspectives.apply(token, { animate: true, mergeOptions: {} })
+const id    = chart.perspectives.save('Q3 zoom')       // -> id
+chart.perspectives.list()                              // [{ id, name, token }]
+chart.perspectives.delete(id)
+
+// static:
+ApexCharts.perspectives.fromURL(location.href)         // -> token | null
+ApexCharts.perspectives.decode(str)
+
+// config: control which options travel with the token
+const options = { chart: { perspectives: { serializeOptions: ['colors', 'title'] } } }
+```
+
+---
+
+## Facet: design tokens and OS-aware themes
+
+`import 'apexcharts/features/facet'`
+
+Charts read `--apx-*` CSS custom properties from the cascade, follow the OS light/dark and contrast preferences with no JS, and can reference named brand themes.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/facet'
+
+ApexCharts.registerTheme('brand', {
+  mode: 'dark',                              // 'light' | 'dark'
+  palette: ['#4f46e5', '#0ea5e9'],
+  tokens: { accent: '#4f46e5', grid: '#333', surface: '#111' },
+})
+// ApexCharts.unregisterTheme('brand')
+
+const options = {
+  theme: {
+    follow: 'os',   // 'os' | false: tracks prefers-color-scheme + prefers-contrast
+    name: 'brand',  // a registered theme
+    tokens: true,   // read --apx-* CSS vars (default true)
+  },
+}
+```
+
+```css
+:root { --apx-accent: #4f46e5; --apx-grid: #e5e7eb; --apx-surface: #fff; --apx-series-1: #4f46e5; }
+```
+
+`await chart.refreshTokens()` re-reads the cascade after a runtime token change that does not itself trigger a render.
+
+---
+
+## Cadence: pluggable easing
+
+Core (no feature import).
+
+`chart.animations.easing` accepts a named curve, a cubic-bezier array, or a function. The default (`easeInOutSine`) is unchanged, so existing charts animate exactly as before.
+
+```js
+const options = {
+  chart: {
+    animations: {
+      easing: 'easeOutBack',                 // or [0.34, 1.56, 0.64, 1], or (t) => t * t
+      dynamicAnimation: { enabled: true, speed: 350, easing: 'linear' },
+    },
+  },
+}
+
+ApexCharts.registerEasing('myBounce', (t) => 1 - Math.pow(1 - t, 3))
+```
+
+Built-in curve names: `linear`, `easeInSine`, `easeOutSine`, `easeInOutSine`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeOutBack`, `easeInOutBack`. Anything else (elastic, bounce, ...) must be registered via `registerEasing`.
+
+---
+
+## Link: crossfilter and cross-chart coordination
+
+`import 'apexcharts/features/link'`
+
+Coordinate a group of charts without wiring.
+
+```js
+// Highlight mode: brushing one chart dims non-matching marks in the others (no redraw):
+const a = {
+  chart: {
+    group: 'sales',
+    link: { enabled: true, mode: 'highlight', dimOpacity: 0.2 }, // mode: 'highlight' | 'filter'
+    selection: { enabled: true },   // required for brushing
+  },
+}
+
+// Crossfilter engine: categorical click-filters, range brushes, shared data table, 2D matrix target:
+const cf = ApexCharts.crossfilter({ id: 'sales', records: rows })
+// ApexCharts.getCrossfilter('sales'); chart.clearCrossfilter()
+
+// Per-chart filter binding (presence of `dimension` selects filter mode):
+const b = {
+  chart: {
+    link: {
+      enabled: true,
+      id: 'sales',
+      dimension: (row) => row.region,   // key extractor; [xKey, yKey] for a matrix
+      reduce: 'count',                  // 'count' | { sum, avg, min, max } | (rows) => number
+      type: 'category',                 // 'category' | 'range' | 'matrix'
+    },
+  },
+}
+```
+
+---
+
+## Ink: direct-manipulation annotation authoring
+
+`import 'apexcharts/features/ink'`
+
+Annotations become draggable and resizable, with click-to-create, snap to gridlines, and a floating editor card (rename, recolor, bold, font size, marker size/shape, delete). Every edit is undoable when Rewind is enabled.
+
+```js
+const options = {
+  chart: {
+    ink: {
+      enabled: true,
+      palette: true,                       // show the "add note" tool palette
+      snap: true,                          // snap to gridlines
+      noteColors: ['#e91e63', '#3f51b5'],  // optional palette override
+    },
+  },
+}
+// Fires: annotationDragged, annotationEdited, annotationStyled, annotationDeleted
+```
+
+---
+
+## Measure: delta ruler
+
+`import 'apexcharts/features/measure'`
+
+Hold a key and drag to read the change, percent, range, and slope between two points; on release the ruler pins as a data-anchored overlay that re-projects on zoom and resize.
+
+```js
+const options = {
+  chart: {
+    measure: {
+      enabled: true,
+      mode: 'span',         // 'span' = finance-style vertical band; 'free' = diagonal ruler
+      key: 'm',
+      pinOnRelease: true,
+    },
+    events: {
+      measured: (chart, { from, to, dx, dy, percentChange, slope }) => {},
+    },
+  },
+}
+// Or drive from code: chart.startMeasure(), chart.stopMeasure(), chart.clearMeasures()
+```
+
+Styling resolves through `--apx-measure-*` tokens.
+
+### Toolbar tool (v6.1)
+
+Since 6.1 the ruler is also a built-in toolbar tool, so it can be armed with a click instead of holding the measure key. The button appears automatically whenever `chart.measure.enabled` is true and the `measure` feature is bundled.
+
+```js
+const options = {
+  chart: {
+    measure: { enabled: true },
+    toolbar: {
+      autoSelected: 'measure',   // pre-select the ruler on load (also accepts 'zoom' | 'pan' | 'selection')
+      tools: { measure: true },  // default; false keeps it key-only; a string supplies a custom SVG icon
+    },
+  },
+}
+```
+
+- `toolbar.tools.measure` is `boolean | string` (like the other tools). `toolbar.autoSelected` now also accepts `'measure'` so the plot loads armed with no key held and no click. The `m` key still works.
+- Selecting the ruler is mutually exclusive with zoom / pan / selection. The `locale.toolbar.measure` string labels the button.
+- **Behavior change (v6.1, on by default):** clicking an already-selected zoom / pan / selection / measure toolbar icon now toggles it *off*, leaving the chart with no active tool (previously those buttons were one-way).
+
+---
+
+## Context menu: Radial Actions
+
+`import 'apexcharts/features/context-menu'`
+
+Right-click or long-press a data point for actions that operate at that exact point.
+
+```js
+const options = {
+  chart: {
+    contextMenu: {
+      enabled: true,
+      // built-in ids (default) + custom items:
+      items: ['annotate', 'xline', 'yline', 'measure', {
+        id: 'copy',
+        label: 'Copy value',
+        onClick: (chart, { x, y, seriesIndex, dataPointIndex, clientX, clientY }) => {},
+      }],
+    },
+  },
+}
+```
+
+Built-in `annotate` / `xline` / `yline` items are ink-managed when the ink feature is bundled (they open the floating editor and undo via Rewind).
+
+---
+
+## Storyboard: scroll-driven choreography (scrollytelling)
+
+`import 'apexcharts/features/storyboard'` (includes Perspectives)
+
+Pair prose sections with saved views. Scrolling a beat past the viewport trigger applies its view; scrolling back reverses it. A beat can also merge an `options` payload to restyle or morph `chart.type` inside one animated transition.
+
+```js
+chart.storyboard.bind({
+  beats: [
+    { selector: '[data-apex-beat="1"]', view: { window: { xaxis: { min: 0, max: 10 } } } },
+    { selector: '[data-apex-beat="2"]', view: { collapsed: [1] }, options: { chart: { type: 'area' } } },
+  ],
+  scroller: window,   // Element | selector; default viewport
+  offset: 0.5,        // 0..1 trigger line
+})
+chart.storyboard.goTo('intro', { animate: true })  // beat index or key
+chart.storyboard.current()                          // { index, key } | null
+chart.storyboard.unbind()
+// Fires: beatChange
+```
+
+---
+
+## Real-time streaming: constant-velocity scroll
+
+Core (the scroll animation needs no opt-in; `chart.streaming` bounds memory).
+
+Rolling-window updates scroll at constant velocity instead of warping in place. Any update that continues the previous window (`appendData`, or a shifted fixed-length `updateSeries`) translates smoothly.
+
+```js
+const options = { chart: { streaming: { enabled: true, maxPoints: 100000 } } }
+// appendData() trims each series to maxPoints (or the visible xaxis.range window)
+```
+
+---
+
+## Drilldown: hierarchical drill-down
+
+`import 'apexcharts/features/drilldown'` (add `import 'apexcharts/features/morph'` for animated cross-type transitions)
+
+Data points reference a child level via a `drilldown` id; clicking drills in, with an optional breadcrumb.
+
+```js
+import 'apexcharts/features/drilldown'
+import 'apexcharts/features/morph'   // optional, animated type morphs
+
+const options = {
+  series: [{ data: [
+    { x: '2021', y: 480, drilldown: '2021' },
+    { x: '2022', y: 530, drilldown: '2022' },
+  ] }],
+  drilldown: {
+    enabled: true,
+    breadcrumb: { show: true, position: 'top-right', rootLabel: 'All Years' },
+    animation: { enabled: true, zoomFromPoint: false, speed: 260 },
+    series: [
+      { id: '2021', name: '2021 by Channel', data: [/* ... */], chart: { type: 'bar' } },
+    ],
+    // or resolve lazily:
+    onDrillDown: (ctx) => ({ id: ctx.point.drilldown, name: '...', data: [] }),
+  },
+  chart: {
+    events: {
+      drillDownStart: (info, chart, options) => {},
+      drillDownEnd: (info, chart, options) => {},
+      drillUp: (info, chart, options) => {},
+    },
+  },
+}
+
+chart.drillDown(id)   // Promise
+chart.drillUp()
+chart.drillToRoot()
+```
+
+---
+
+## Common Pitfalls
+
+1. **Forgetting the feature import**: every v6 feature is off until you `import 'apexcharts/features/<name>'` (or use the full `apexcharts` bundle). Enabling the config alone does nothing if the feature isn't in the bundle.
+2. **Using `api.zeroY` in a custom mark**: it does not exist. Use `ctx.scales.y(0)` for the baseline.
+3. **Expecting `mode: 'filter'` on `chart.link` without records**: highlight mode needs `chart.selection.enabled: true`; the crossfilter engine needs `ApexCharts.crossfilter({ id, records })` or a `dimension` extractor.
+4. **`largeDatasetThreshold` is under `chart.animations`**, not `chart` directly.
+5. **Assuming the canvas renderer supports everything**: pattern/image fills and per-point selection visuals fall back to (or stay) SVG.