@amcharts/amcharts5-mcp 1.8.0 → 1.9.0

package/README.md

@@ -225,7 +225,7 @@ Once connected, your AI assistant can:
 - **"How do I format date axis labels?"** → AI calls `search_all("date axis label format")`
 - **"Show me the Sankey diagram example"** → AI calls `get_example("examples/flow/sankey-diagram")`
 - **"What settings does XYChart support?"** → AI calls `get_doc("reference/xychart")`
-- **"How do I integrate with React?"** → AI calls `get_doc("getting-started/integrations/react")`
+- **"How do I integrate with React?"** → AI calls `get_doc("getting-started/integrations/react")`, which covers the `@amcharts/amcharts5-react` package
 - **"What chart types are available?"** → AI calls `list_chart_types()`
 - **"Map the current US congressional districts"** → AI calls `list_geodata("congressional whole country")`
 
@@ -233,7 +233,7 @@ Once connected, your AI assistant can:
 
 The server includes **1,800+ documents**:
 
-- **160+ documentation pages** — getting started, chart guides, concepts (themes, events, adapters, data binding, animations, accessibility, etc.), and framework integration guides (React, Angular, Vue, Next.js, Svelte, and more)
+- **160+ documentation pages** — getting started, chart guides, concepts (themes, events, adapters, data binding, animations, accessibility, etc.), and framework integration guides for amCharts' React, Vue, Angular, Svelte and React Native packages (with Next.js, Nuxt, SvelteKit, React Router and Remix 3)
 - **290+ code examples** — working demos across 16 categories including column/bar, line/area, pie/donut, maps, hierarchy, flow, radar/polar, stock, gauges, Gantt, timeline, and more
 - **1,300+ API reference pages** — every class, interface and function in the amCharts 5 library, generated from the release's typings: settings with their real defaults (theme rules included), events, properties, data item fields, the inheritance chain and the import line
 - **670+ geodata entries** — every map in `@amcharts/amcharts5-geodata`, for `list_geodata`
@@ -244,12 +244,23 @@ The server includes **1,800+ documents**:
 - **Read-only tools.** Every tool reads the bundled amCharts documentation and returns text. No tool writes files, runs commands or fetches URLs.
 - **The hosted endpoint has no authentication, by design.** `https://mcp.amcharts.com/mcp` serves the same public documentation as amcharts.com. There are no accounts, API keys, user data or write operations behind it.
   - It runs on Cloudflare Workers.
-  - MCP session state is kept in a Durable Object, as the MCP agents framework requires.
-  - Cloudflare's standard request logs are enabled. The server itself does not log tool arguments.
+  - MCP session state is kept in a Durable Object, as the MCP agents framework requires. It is deleted when the session ends, or 24 hours after its last request.
+  - Per-request logs (Workers invocation logs) are off. Only error messages are logged, and they hold no tool arguments. See "Privacy" below.
 - **Local install.** The npm package runs over stdio on your machine and reads only the content bundled in it; it makes no network requests. Its only runtime dependencies are `@modelcontextprotocol/sdk` and `zod`.
 - **Maintainer scripts.** The scripts in `scripts/` (the demo and docs scrapers, the API reference generator) are not part of the npm package and never run in the server.
 - **Reporting a vulnerability:** https://www.amcharts.com/report-vulnerability/
 
+## Privacy
+
+Neither the hosted server nor the npm package needs an account or asks for personal data.
+
+- **Hosted server** (`https://mcp.amcharts.com/mcp`):
+  - **What your AI app sends:** a search phrase, a chart type, a doc path. These are used only to build the answer, and are not logged or stored. A response is kept in the session's storage only until it has been delivered (so a dropped stream can resume), then deleted.
+  - **Session record:** when an AI app connects, the server keeps its MCP initialize message in the session's storage. That message holds what the app says about itself (its name and version, and whatever else it puts there), the protocol version and the app's MCP capabilities. All of the session's storage is deleted when the app ends the session, or 24 hours after its last request.
+  - **Logs:** the server keeps no request logs (Workers invocation logs are off). It runs on Cloudflare Workers, and Cloudflare processes each request, including its IP address, to deliver it. Error and warning messages are logged and kept for up to 7 days; they hold no request contents or tool arguments.
+- **npm package:** it runs on your computer over stdio and sends nothing to amCharts or anyone else.
+- **Policy and questions:** see the [amCharts privacy policy](https://www.amcharts.com/privacy-policy/), or write to contact@amcharts.com.
+
 ## License
 
 MIT

package/content/SKILL.md

@@ -9,7 +9,8 @@ description: >
   JavaScript chart built with amCharts, wants to create any data visualization
   using the amCharts library, is migrating from amCharts v4 to v5, or needs help
   with amCharts configuration, theming, exporting, tooltips, legends, or axis
-  setup. Also use when the user mentions chart types that amCharts supports, even
+  setup, including amCharts in React, Next.js, Vue, Nuxt, Angular, Svelte or
+  React Native apps. Also use when the user mentions chart types that amCharts supports, even
   if they don't say "amCharts" explicitly, if amCharts is already present in the
   project or was discussed in the conversation.
 metadata:
@@ -40,7 +41,7 @@ Docs: https://www.amcharts.com/docs/v5/
 9. **Every axis needs a renderer** — `am5xy.AxisRendererX.new(root, {})` or `AxisRendererY`.
 10. **CategoryAxis must receive data** — call `xAxis.data.setAll(data)` in addition to series data. Forgetting this is the #1 bug.
 11. **DateAxis values must be timestamps** — use `new Date().getTime()`, not Date objects.
-12. **Disposal is mandatory in SPAs** — call `root.dispose()` on component unmount. Not `chart.dispose()`.
+12. **Disposal is mandatory in SPAs** — in React, Vue, Angular, Svelte or React Native use amCharts' framework package, which creates and disposes the root for you (see "Frameworks"); without one, call `root.dispose()` on component unmount. Not `chart.dispose()`.
 13. **Style through amCharts, not CSS** — charts draw on canvas by default, so CSS cannot reach chart internals. Even with the optional SVG renderer (5.21.0) the shapes carry no per-element classes or ids, are rewritten as the chart redraws, and exports ignore page CSS. Use amCharts settings/templates/themes instead.
 14. **Dark backgrounds require Dark theme** — If the user requests or the page clearly has a dark background, always add `am5themes_Dark.new(root)` to `root.setThemes()` alongside Animated. Without it, labels, grid, and tooltips will be invisible. If the background is not clearly dark, default to white/light and do NOT add the Dark theme unless asked.
 15. **Use default amCharts colors** — Do NOT invent custom color palettes unless the user explicitly asks for specific colors. amCharts assigns colors automatically from its built-in ColorSet. If you need a color programmatically, use `chart.get("colors").getIndex(index)` or `chart.get("colors").next()`. For pie/percent charts, use `series.get("colors")` instead.
@@ -66,6 +67,7 @@ Docs: https://www.amcharts.com/docs/v5/
 | Exporting | `@amcharts/amcharts5/plugins/exporting` | `plugins/exporting.js` | Exporting, ExportingMenu |
 | JSON | `@amcharts/amcharts5/plugins/json` | `plugins/json.js` | ChartSerializer, JsonParser |
 | Chart element (5.21.0) | `@amcharts/amcharts5/element` | `element.js` (after `plugins/json.js`) | `<am5-chart>` — see "Serializing to JSON" |
+| Framework packages | `@amcharts/amcharts5-react`, `-vue`, `-angular`, `-svelte`, `-react-native` (separate npm packages) | — | `useAmChart`, `<AmChart>`, `[amChart]`, `attachAmChart` — see "Frameworks" |
 
 ## Which reference to read
 
@@ -88,7 +90,7 @@ Based on the chart type the user is building, read the relevant reference file f
 
 If the chart type is unclear, start with `references/xy.md` — XY charts are by far the most common.
 
-If the user asks about core setup (theming, colors, exporting, legends, tooltips, disposal, responsive) without a specific chart type, the information below is sufficient — no reference file needed.
+If the user asks about core setup (theming, colors, exporting, legends, tooltips, disposal, responsive) without a specific chart type, the information below is sufficient — no reference file needed. For a chart in a React, Vue, Angular, Svelte or React Native app, read "Frameworks" below as well as the chart type's reference.
 
 ## Root element setup
 
@@ -703,10 +705,24 @@ colors.set("colors", [
 ]);
 ```
 
-**A `ColorSet` must always hold at least one color.** `colorSet.set("colors", [])` crashes the next `next()`/`getIndex()` call (`Maximum call stack size exceeded`, or `Cannot read properties of undefined (reading 'toHSL')` inside `generateColors`) as soon as a series iterates the palette — as of 5.21.0 the empty list is not guarded. To "reset" a palette, swap in a fresh `am5.ColorSet.new(root, {})` instead of emptying the list. The theme's `baseColor` also resolves lazily, so a **synchronous** re-color right after swapping a `ColorSet` can read a transient value (sprites momentarily black); re-set the series data and let amCharts' own data pass recolor the sprites.
+**A `ColorSet` must always hold at least one color.** `colorSet.set("colors", [])` crashes the next `next()`/`getIndex()` call (`Maximum call stack size exceeded`, or `Cannot read properties of undefined (reading 'toHSL')` inside `generateColors`) as soon as a series iterates the palette — as of 5.21.3 the empty list is not guarded. To "reset" a palette, swap in a fresh `am5.ColorSet.new(root, {})` instead of emptying the list. The theme's `baseColor` also resolves lazily, so a **synchronous** re-color right after swapping a `ColorSet` can read a transient value (sprites momentarily black); re-set the series data and let amCharts' own data pass recolor the sprites.
 
 **`step` with a theme that reuses its colors** (`reuse: true`: Adaptive, Monochrome, Nord, Pastel, Kelly, …): before 5.21.2 a `step` sharing a factor with the list length used only a few of the colors (a word cloud or treemap with Nord got two or three). Now every color is used before any repeats, so `step: count / 2` interleaves the palette.
 
+**Repeats are lighter (5.21.3).** In themes that reuse their list, once every color has been used, the next round is 10% lighter instead of the same colors again. This covers Adaptive, Monochrome, Ember, Frozen, Kelly, Material, Midnight, Moonrise, Nord, Pastel, Petroleum, Savanna and Spirited, with their Dark variants, but not Colorblind, Patterns or Dataviz. The setting is `repeatLightness` on the `ColorSet`: HSL lightness per round, `0.1` is 10%, and a negative value makes it darker. It only acts with `reuse: true`. The color sets of one root share the theme's list, and the repeats are added to that list, so whichever color set on the root first needs a new round decides that round for every chart on it. To repeat the colors as they are, as before 5.21.3, set it for the whole root:
+
+```js
+// Every ColorSet on the root, through a theme rule
+var noLighter = am5.Theme.new(root);
+noLighter.rule("ColorSet").set("repeatLightness", 0);
+root.setThemes([am5themes_Animated.new(root), am5themes_Nord.new(root), noLighter]);
+
+// Adaptive and Monochrome: a theme setting (true = 0.1, or a number)
+am5themes_Adaptive.new(root, { repeatLightness: false });
+```
+
+With one chart on the root, `chart.get("colors").set("repeatLightness", 0)` before the data is set works too.
+
 ## Data processor
 
 ```js
@@ -732,7 +748,8 @@ Without `dateFormat`, since 5.21.1 the browser's `Date` parses the strings, so I
 - **Only user-set settings are serialized (5.20.3)** — theme and library defaults are left out, so a serialized config is much smaller than before and a value you never set will not appear in it. Add `includeRoot: true` (5.20.2) to also write a top-level `root` section (Root settings/properties, `interfaceColors`, formatters).
 - **Re-parsing into an existing chart:** `parser.parse(config, { updateTargets: "soft" })` (5.20.3) applies settings onto an existing object of the same `type` instead of replacing it. The default `"strict"` replaces.
 - **Also saved (5.20.6 – 5.20.8):** `themeTags` you pass to `.new()` (5.20.6 — e.g. a `Button` with `themeTags: ["switch"]` keeps its look; tags the library adds are left out); a legend inside an `axisHeader` (5.20.7); declared `animations` (5.20.8, see "Animations"); and animations started in code that **loop forever** (`loops: Infinity`) with a nameable `am5.ease` easing — written as `animations` entries. `runningAnimations` (5.20.8, default `true`) controls the latter: `am5plugins_json.ChartSerializer.new(root, { runningAnimations: false })` turns it off. Never saved: finite animations (`appear()`, states, zoom) and loops with a custom-function or `pow` easing — for the opening animation use `autoAppear` (5.21.0, see "Animations").
-- **Also saved (5.21.0):** a loop started on a **data item** in code (`dataItem.animate({ key: "positionOnLine", loops: Infinity, … })`) — the first one found is written as an `animations` entry with `target: "dataItem"` on the bullet sprite, so after parsing every point of the series plays it (declare it on the bullet sprite yourself if points need different loops); a series hidden with `hide()` or a legend click; elements you add to library-built containers (`chart.plotContainer`, `seriesContainer`, axes containers, an axis) — no `themeTags: ["serialize"]` needed; a `ZoomableContainer`'s `contents`; `Date` values (as timestamps); settings on a series' `bulletsContainer` and on a pie/funnel series' `labelsContainer`/`ticksContainer`; the `axisFills`, `rectangles` (`Treemap`, `Partition`) and `polygons` (`VoronoiTreemap`) templates. A color taken from `root.interfaceColors` is written as a reference, `"@root.interfaceColors.get('background')"`, so a config parsed under another theme (e.g. Dark) uses that theme's color — write the same string in hand-made configs.
+- **Data-item loops (5.21.0):** a loop started on a **data item** in code (`dataItem.animate({ key: "positionOnLine", loops: Infinity, … })`) is saved as an `animations` entry with `target: "dataItem"`. When every data item plays the same loop, it goes on the bullet sprite. Since 5.21.3, when they differ (e.g. points each moving at their own speed), each one goes in its own data row, under the sprite's `templateField` (`"bulletSettings"` if none is set). Before 5.21.3, every item got the first one's loop.
+- **Also saved (5.21.0):** a series hidden with `hide()` or a legend click; elements you add to library-built containers (`chart.plotContainer`, `seriesContainer`, axes containers, an axis) — no `themeTags: ["serialize"]` needed; a `ZoomableContainer`'s `contents`; `Date` values (as timestamps); settings on a series' `bulletsContainer` and on a pie/funnel series' `labelsContainer`/`ticksContainer`; the `axisFills`, `rectangles` (`Treemap`, `Partition`) and `polygons` (`VoronoiTreemap`) templates. A color taken from `root.interfaceColors` is written as a reference, `"@root.interfaceColors.get('background')"`, so a config parsed under another theme (e.g. Dark) uses that theme's color — write the same string in hand-made configs. Since 5.21.3 a color taken from the theme's palette with `getIndex()` is written as `"@colors.getIndex(3)"` the same way, and hand-made configs can use it too in settings (e.g. `"fill": "@colors.getIndex(0)"`). Only the palette's own colors become references: generated or lightened repeats stay hex, and references are not read inside data rows. Changing a setting such as `step` on a chart's colors no longer writes the theme's whole palette into the config.
 - **Not captured by `ChartSerializer` (as of 5.21.0)** — re-apply these in code after `parse()`: a `ZoomTools` you added to a hand-made `ZoomableContainer` (its `target` is written as a copy, so the parsed buttons drive a different container — re-point `target`, or use `am5.SerialChartContainer`, which wires its own `zoomTools`); Venn `hoverGraphics` (Venn slice-template `states` do round-trip); data items added with `pushDataItem()` (only `series.data` rows are written — map points on lines can be data rows since 5.20.6, see `references/map.md`).
 - **Bullets** are captured by calling the factory with a sample data item — write factories as `function(root, series, dataItem)` (pitfall #36).
 
@@ -850,21 +867,113 @@ button.events.on("click", function() {
 });
 ```
 
-## Disposal (SPA frameworks)
+## Frameworks (React, Vue, Angular, Svelte, React Native)
+
+In a framework app, use amCharts' package for that framework (first released 2026-10-22, version 5.0.0) instead of writing the mount and dispose code yourself. Each package makes the chart once its element is on the page, disposes it with the component, and loads the library in the browser only, so pages rendered on a server work (Next.js, Nuxt, SvelteKit, Angular SSR). Each takes a chart written in code, or a chart from a JSON config (it wraps the `<am5-chart>` element, see "Serializing to JSON").
+
+| Framework | Package | A chart in code | A chart from a JSON config |
+|---|---|---|---|
+| React 18+ (Next.js, React Router, Astro) | `@amcharts/amcharts5-react` | `const { ref, root, result } = useAmChart((root) => { … }, [data])`, `<div ref={ref} style={{ height: "500px" }} />` | `<AmChart config={config} themes={[am5themes_Animated]} onReady={({ root, chart }) => …} />` |
+| Vue 3.5.2+ (Nuxt) | `@amcharts/amcharts5-vue` | `const { root, result } = useAmChart(useTemplateRef("chart"), (root) => { … }, { watch: () => props.data })`, `<div ref="chart" style="height: 500px">`; `root`/`result` are shallow refs | `<AmChart :config="config" :themes="themes" @ready="onReady" />` |
+| Angular 19+ | `@amcharts/amcharts5-angular` | `AmChartDirective`: `<div [amChart]="buildChart" [amChartDeps]="[data()]" (amChartReady)="…" style="height: 500px">`, with `buildChart = (root: Root) => { … }` as an arrow-function property so `this` is the component | `AmChartComponent`: `<am5-chart [config]="config" [themes]="themes" (amChartReady)="…">` |
+| Svelte 4+ (SvelteKit) | `@amcharts/amcharts5-svelte` | Svelte 5.29+: `<div {@attach attachAmChart(buildChart)} style="height: 500px">`; Svelte 4 and older 5: `<div use:amChart={{ setup: buildChart, deps: [data] }}>` | `<am5-chart {@attach attachAmChartConfig({ config, themes })}>`, or `use:amChartConfig={{ config, themes }}`; events `onready`/`onerror` (`on:ready` in Svelte 4) |
+| React Native 0.72+ | `@amcharts/amcharts5-react-native` (+ `react-native-webview` 13+) | `<AmChart code={code} data={data} />`, where `code` is a **string** (below) | `<AmChart config={config} themes={["Animated"]} />` |
+
+Install the library with the package: `npm install @amcharts/amcharts5 @amcharts/amcharts5-react` (the web packages need amCharts 5.21.0 or later). React Native installs only `@amcharts/amcharts5-react-native react-native-webview`: the WebView loads the library from the amCharts CDN.
+
+```jsx
+// React. Vue, Angular and Svelte work the same way: your function gets the root.
+import { useEffect } from "react";
+import { useAmChart } from "@amcharts/amcharts5-react";
+import * as am5xy from "@amcharts/amcharts5/xy";
+import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
+
+function Chart({ data }) {
+  const { ref, result } = useAmChart((root) => {
+    root.setThemes([am5themes_Animated.new(root)]);
+    const chart = root.container.children.push(am5xy.XYChart.new(root, {}));
+    const xAxis = chart.xAxes.push(am5xy.CategoryAxis.new(root, {
+      categoryField: "category",
+      renderer: am5xy.AxisRendererX.new(root, {})
+    }));
+    const yAxis = chart.yAxes.push(am5xy.ValueAxis.new(root, {
+      renderer: am5xy.AxisRendererY.new(root, {})
+    }));
+    const series = chart.series.push(am5xy.ColumnSeries.new(root, {
+      xAxis: xAxis, yAxis: yAxis, categoryXField: "category", valueYField: "value"
+    }));
+    return { xAxis, series };
+  }, []); // made once: [data] here would make the chart again on every change
+
+  // New data goes to the chart that is there, with an animation
+  useEffect(() => {
+    if (result) {
+      result.xAxis.data.setAll(data);
+      result.series.data.setAll(data);
+    }
+  }, [result, data]);
+
+  return <div ref={ref} style={{ width: "100%", height: "500px" }}></div>;
+}
+```
+
+- **Your function gets the root:** never call `am5.Root.new()` or `root.dispose()` in it, because the package does both. Put the code that follows `Root.new()` in any example inside it.
+- **The chart's element needs a height.** The JSON-config components are 400 px high without one.
+- **Deps make the chart again from scratch:** `[data]` in React, `watch` in Vue (what Vue's `watch()` takes; add `deep: true` to also catch `push()`), `[amChartDeps]` in Angular, `deps` in Svelte actions. A Svelte attachment runs again when state read in its own expression changes. To change data without rebuilding, return what you need and use it from `result` (React, Vue), from `(amChartReady)`'s `{ root, result }` (Angular), or from a `$state.raw` variable set in the function (Svelte).
+- **SVG:** `useAmChart(setup, deps, { renderer: "svg" })` in React, `{ renderer: "svg" }` in Vue's options, `[amChartRenderer]="'svg'"` in Angular, and `attachAmChart(setup, { renderer: "svg" })` or `renderer: "svg"` in Svelte's action parameter. The JSON-config components take a `renderer` prop or input.
+- **Themes for the JSON-config components are classes** (`[am5themes_Animated]`, not `.new(root)`): themes are not part of a config. React Native takes theme **names** (`["Animated", "Dark"]`).
+- **Give amCharts plain data.** In Vue, keep amCharts objects out of reactive state: use `shallowRef()` for data, or pass `toRaw(data)`. In Svelte 5, use `$state.snapshot(data)`.
+- **License:** call `am5.addLicense("AM5C-…")` once when the app starts, before any chart is made, never in the setup function, because the logo is decided when the root is made. Put it in `main.ts`/`main.jsx`, before `createApp()` or `bootstrapApplication()`. In Next.js, put it at the top of a client component's file; in Nuxt, in a client plugin (`plugins/amcharts.client.ts`); in SvelteKit, in `src/hooks.client.ts`. React Native takes `licenses={["AM5C-…"]}` on each chart.
+- **Errors** thrown in your function go to React's nearest error boundary, Vue's `app.config.errorHandler`, Angular's `ErrorHandler` and `(amChartError)`, and Svelte's `onError` option (an uncaught error without it).
+- **Server rendering:**
+  - Next.js, Nuxt (no `<ClientOnly>` needed), SvelteKit and Angular SSR need no configuration.
+  - In the Next.js app router, `useAmChart` and theme classes need a client component (`"use client"`). A server component can render `<AmChart config={config}>` itself, because a config is plain data.
+  - React Router (Remix 2) and Astro: add `ssr: { noExternal: ["@amcharts/amcharts5"] }` to the Vite config (under `vite` in `astro.config.mjs`).
+  - Remix 3 has no package. Either load the script files and render `<am5-chart config={JSON.stringify(config)} data-rmx-preserve-dom>`, or use a `clientEntry()` component that imports amCharts inside Remix's `ref` mixin and disposes the root when its signal aborts.
+- **Unit tests in jsdom** (no canvas): mock the package, e.g. `vi.mock("@amcharts/amcharts5-react", () => ({ useAmChart: () => ({ ref: () => {}, root: undefined, result: undefined }), AmChart: () => null }))`.
+
+**React Native** draws the real library in a WebView, so every chart type works, and it runs in Expo Go.
+- The chart code is a **string** written like a script-tag example: `am5xy.XYChart`, globals rather than imports. `root`, `data` (the `data` prop) and `post(name, value)` are in scope, and the files the code uses are loaded for it.
+- If the code returns a function, new `data` (compared by content) goes to that function instead of making the chart again.
+- `post()` calls the `onMessage(name, value)` prop.
+- Everything between the app and the chart is JSON, so give dates as timestamps.
+- Never build `code` from text a user typed or a server sent: pass such values in `data`.
+- Other props: `renderer`, `modules` (e.g. `["locales/de_DE"]`), `libraryUrl`, `geodataUrl`, `onReady`, `onError`, `webViewProps`. A ref gives `run(code)`.
+
+```jsx
+import { AmChart } from "@amcharts/amcharts5-react-native";
+
+const code = `
+const chart = root.container.children.push(am5xy.XYChart.new(root, {}));
+// ... axes and series, as in a script-tag example
+series.columns.template.events.on("click", (ev) => post("country", ev.target.dataItem.dataContext.country));
+xAxis.data.setAll(data);
+series.data.setAll(data);
+return (newData) => { xAxis.data.setAll(newData); series.data.setAll(newData); };
+`;
+
+<AmChart code={code} data={visits} themes={["Animated"]} style={{ height: 300 }}
+  onMessage={(name, value) => console.log(name, value)} />
+```
+
+**Without a package** (an older framework version, or when the user asks for it), create the root once the element exists, and dispose it when the component goes away:
 
 ```js
 // React
 useLayoutEffect(() => {
-  const root = am5.Root.new("chartdiv");
+  const root = am5.Root.new(chartdiv.current); // const chartdiv = useRef(null)
   // ... build chart
   return () => { root.dispose(); };
 }, []);
 
-// Angular
+// Angular: in ngAfterViewInit, only if isPlatformBrowser(), inside zone.runOutsideAngular()
 ngOnDestroy() { this.root?.dispose(); }
 
-// Vue
-onUnmounted(() => { root.dispose(); });
+// Vue: root = am5.Root.new(chartdiv.value) in onMounted, kept in a plain variable, not reactive state
+onBeforeUnmount(() => { root?.dispose(); });
+
+// Svelte: onMount runs in the browser only
+onMount(() => { const root = am5.Root.new(chartdiv); /* ... */ return () => root.dispose(); });
 ```
 
 **Always call `root.dispose()`** — this cleans up all children, series, and event listeners.
@@ -921,7 +1030,7 @@ onUnmounted(() => { root.dispose(); });
 35. **`axis.dispose()` does NOT remove the axis from `chart.xAxes`/`chart.yAxes`** — unlike `series.dispose()`, which self-removes from `chart.series`. A disposed axis stays in the list, keeps showing up in anything built from `chart.yAxes`, and makes `ChartSerializer` throw `Template is disposed`. Remove axes with `chart.yAxes.removeValue(axis)` (or `removeIndex(i)`) — the list auto-disposes the removed axis, no separate `dispose()` needed.
 36. **Declare bullet callbacks as `function(root, series, dataItem)`** — amCharts passes all three; closing over an outer `root` works at runtime but breaks JSON round-trips (`ChartSerializer` captures the function source, and the outer `root` dangles on re-bind). Every `series.bullets.push(...)` in these references uses the parameter form — copy it.
 37. **A `ColorSet` must contain at least one color** — `colors.set("colors", [])` crashes the next `next()`/`getIndex()`. Swap in a fresh `am5.ColorSet.new(root, {})` instead. See "ColorSet" above.
-38. **`LinearGradient` `rotation` only works from 0 to 90** (bug in 5.20.8–5.21.2) — other angles give a flat or wrong fill, and with a transparent end stop the shape can vanish. For the opposite direction keep the angle in range and reverse the `stops`: 180 = `rotation: 0` with reversed stops, 270 = `rotation: 90` with reversed stops. See `references/xy.md` → Series gradients.
+38. **`LinearGradient` `rotation` only works from 0 to 90** (bug since 5.20.8, still in 5.21.3) — other angles give a flat or wrong fill, and with a transparent end stop the shape can vanish. For the opposite direction keep the angle in range and reverse the `stops`: 180 = `rotation: 0` with reversed stops, 270 = `rotation: 90` with reversed stops. See `references/xy.md` → Series gradients.
 39. **Several colors in one `am5.Graphics` `draw`** — `endFill()` fills everything since the last `beginPath()`, so start each color with `display.beginPath()`, or the last color paints over all shapes. Don't give such a Graphics its own `fill` either: after `draw` runs it fills the current path once more, so the last shape takes the Graphics' own `fill` (the default theme sets none). E.g. `draw: function (display) { display.beginPath(); display.beginFill(am5.color(0xff0000)); display.drawRect(0, 0, 10, 10); display.endFill(); display.beginPath(); display.beginFill(am5.color(0x0000ff)); display.drawRect(10, 0, 10, 10); display.endFill(); }`.
 40. **Changing a value on a data item moves nothing** — series draw from the working values: set `valueYWorking` (XY) or `valueWorking` (pie) along with the value, or use `series.data.setIndex()`. See "Dynamic data".
 41. **A setting changed after a hover snaps back on unhover** — the `"default"` state keeps the value from before the first hover. Change it there too: `sprite.states.lookup("default")?.set("fill", c)`. See "States".
@@ -969,7 +1078,7 @@ Skip this step entirely if you cannot execute code (e.g., chat-only context with
 
 ## Recent API changes
 
-Latest release covered here: **5.21.2** (2026-10-14). These are the renames, new settings and behavior changes that code written from older knowledge most often gets wrong — prefer these names/settings. For exact types and defaults, use the typings (`*.d.ts`) or the amCharts MCP server's `get_api_reference`, which is generated from them; for anything newer, verify against the live docs (see next section).
+Latest release covered here: **5.21.3** (2026-10-21), and the framework packages 5.0.0 (2026-10-22). These are the renames, new settings and behavior changes that code written from older knowledge most often gets wrong — prefer these names/settings. For exact types and defaults, use the typings (`*.d.ts`) or the amCharts MCP server's `get_api_reference`, which is generated from them; for anything newer, verify against the live docs (see next section).
 
 **Renamed settings (old name still works but is deprecated — use the new one):**
 
@@ -986,6 +1095,13 @@ am5hierarchy.VoronoiTreemap.new(root, { shapeType: "rectangle" }); // was: type
 
 **Breaking change — WordCloud internals (5.20.1):** the layout is now computed synchronously in one pass (much faster). The per-data-item `ghostLabel` is gone and labels live in an internal container, so `dataItem.get("ghostLabel")` and any code walking `series.children` to find labels must be updated — use `series.labels` / `dataItem.get("label")` instead.
 
+**Framework packages (5.0.0, 2026-10-22):** `@amcharts/amcharts5-react`, `@amcharts/amcharts5-vue`, `@amcharts/amcharts5-angular`, `@amcharts/amcharts5-svelte` and `@amcharts/amcharts5-react-native`. They make and dispose the chart with the component and work with server rendering. Prefer them over hand-written `Root.new()`/`dispose()` code in those frameworks. See "Frameworks".
+
+**New in 5.21.3 (2026-10-21):**
+- `ColorSet` `repeatLightness`: themes that reuse their colors (Adaptive, Monochrome, Kelly, Material, Nord, Pastel and others, but not Colorblind or Patterns) now make each repeat of the list 10% lighter. For the old behavior, set `repeatLightness: 0` through a theme rule, `rule("ColorSet").set("repeatLightness", 0)`: the color sets of a root share one list. In the Adaptive and Monochrome theme settings, use `false`. See "ColorSet".
+- JSON: palette colors are written as `"@colors.getIndex(n)"`, so they follow the theme the config is parsed with. A `step` or `passOptions` set on a chart's colors round-trips without the theme's palette. Data-item loops that differ per item are saved per item. See "Serializing to JSON".
+- Maps: d3 projections with a shape of their own (HEALPix, Armadillo, Berghaus, interrupted and polyhedral) display properly, and switching projections at zoom level 1 shows the whole map again.
+
 **New in 5.21.2 (2026-10-14):**
 - Interface color `warning`: a yellow between `negative` and `positive` (default `#f2c230`; themes with their own `positive`/`negative` have a matching one), for the middle of a bad-to-good scale: `root.interfaceColors.get("warning")`.
 - `am5.Color.interpolateColors(position, colors, mode?)`: a color on a scale through any number of colors, evenly spaced (`position` 0–1, clamped; `mode` `"rgb"` (default) or `"hsl"`). Through `[negative, warning, positive]` it avoids the brown middle of `Color.interpolate(t, negative, positive)`. See "Colors".

package/content/flow.md

@@ -343,6 +343,8 @@ bullet.on("locationY", function() {
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/hierarchy.md

@@ -350,6 +350,8 @@ Bullets on series inside a `SerialChartContainer` are drawn as of 5.20.4, and fl
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/map.md

@@ -551,7 +551,7 @@ planeSeries.bullets.push(function (root, series, dataItem) {
 planeSeries.data.setAll([{ lineId: "jfk-lhr", positionOnLine: 0, autoRotate: true }]);
 ```
 
-**Direction on the way back (5.20.8):** an `autoRotate` point turns round to face its travel direction **only** while an `animations` entry on its bullet sprite (`target: "dataItem"`, `key: "positionOnLine"`) moves it back toward the line start. A point moved by `dataItem.animate()` from code keeps facing the line's direction — that code has to turn it (Example 4 rotates its plane between segments itself). An endless loop started on a data item in code is saved by `ChartSerializer` since 5.21.0 (not in 5.20.8), but only the first one found, written onto the bullet sprite — after parsing every point of the series plays it; a declared entry per bullet is the predictable form. Since 5.21.0 every point placed on a line follows the line when it changes (e.g. gets an `altitude`), not just one of them.
+**Direction on the way back (5.20.8):** an `autoRotate` point turns round to face its travel direction **only** while an `animations` entry on its bullet sprite (`target: "dataItem"`, `key: "positionOnLine"`) moves it back toward the line start. A point moved by `dataItem.animate()` from code keeps facing the line's direction — that code has to turn it (Example 4 rotates its plane between segments itself). An endless loop started on a data item in code is saved by `ChartSerializer` since 5.21.0 (not in 5.20.8). In 5.21.0–5.21.2 only the first one found was saved, on the bullet sprite, so after parsing every point played it. Since 5.21.3 loops that differ per point are saved in each point's data row, under the bullet sprite's `templateField` (`"bulletSettings"` if none is set); one loop shared by all points still goes on the sprite. Where the rows can't hold them, the first one still goes on the sprite for all: points made from geodata, a sprite with its own `animations`, or a loop animating object values. Since 5.21.0 every point placed on a line follows the line when it changes (e.g. gets an `altitude`), not just one of them.
 
 **IMPORTANT — Multi-segment lines and `positionOnLine`:**
 - `positionOnLine` treats the entire line as one unit (0 = start, 1 = end). If a line has multiple segments (i.e. `pointsToConnect` has 3+ points), position 0.5 is the midpoint of the *entire* path.
@@ -979,6 +979,8 @@ linkedSeries.data.setAll([{ id: "US", url: "https://en.wikipedia.org/wiki/United
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/pie.md

@@ -371,6 +371,8 @@ series.set("linkTarget", "_blank");     // default "_self"
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/radar.md

@@ -315,6 +315,8 @@ handDataItem.animate({
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/stock.md

@@ -343,6 +343,8 @@ valueSeries.events.on("datavalidated", () => {
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/xy.md

@@ -132,7 +132,7 @@ am5xy.ColumnSeries.new(root, {
 
 ## Disposal (SPA frameworks)
 
-Always dispose on component unmount:
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root on component unmount:
 ```js
 root.dispose();
 ```
@@ -799,7 +799,7 @@ series.fills.template.set("fillGradient", am5.LinearGradient.new(root, {
 
 `Series` also has `fillGradient` and `strokeGradient` settings (5.20.0), but the series' own fills, lines and columns don't use them: they are handed to bullets. A bullet `Graphics` that sets none of `fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient` inherits all of them from its series, so bullets pick up series gradients and patterns automatically.
 
-**`LinearGradient` `rotation` only works from 0 to 90** (a bug in 5.20.8–5.21.2, any element). Other angles give a flat or wrong fill, and with a transparent end stop the shape can vanish. For the opposite direction keep the angle in that range and reverse the `stops`: 180 = `rotation: 0` with reversed stops, 270 = `rotation: 90` with reversed stops:
+**`LinearGradient` `rotation` only works from 0 to 90** (a bug since 5.20.8, still in 5.21.3, any element). Other angles give a flat or wrong fill, and with a transparent end stop the shape can vanish. For the opposite direction keep the angle in that range and reverse the `stops`: 180 = `rotation: 0` with reversed stops, 270 = `rotation: 90` with reversed stops:
 
 ```js
 // what rotation: 180 with stops [{ opacity: 0.6 }, { opacity: 0 }] should draw (it doesn't):

package/extended/getting-started/integrations/am5-chart-element.md

@@ -1,131 +1,156 @@
 ---
 title: "The <am5-chart> Element"
 source: "https://www.amcharts.com/docs/v5/getting-started/integrations/am5-chart-element/"
-scraped: "2026-10-08"
+scraped: "2026-10-22"
 ---
 
 `<am5-chart>` is an HTML element that builds a chart from a [JSON config](https://www.amcharts.com/docs/v5/concepts/serializing/). There is no root element to create and no chart code to write: put the element on the page and give it a config.
 
-NOTEThe `<am5-chart>` element is available since version 5.21.0.
+NOTE The `<am5-chart>` element is available since version 5.21.0.
 
 ## Loading
 
 With script tags, load `index.js`, `plugins/json.js` and `element.js`, in that order. Then load the files for the chart types the config uses, and any themes:
 
+```html
 <script src="https://cdn.amcharts.com/lib/5/index.js"></script>
 <script src="https://cdn.amcharts.com/lib/5/plugins/json.js"></script>
 <script src="https://cdn.amcharts.com/lib/5/element.js"></script>
 <script src="https://cdn.amcharts.com/lib/5/percent.js"></script>
 <script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>
+```
 
 With npm, import the element module. The chart types a config uses are loaded automatically when the chart is built.
 
+```typescript
 import "@amcharts/amcharts5/element";
+```
 
+```javascript
 import "@amcharts/amcharts5/element";
+```
 
 ## Adding a chart
 
 The config can be given right in the `config` attribute, as a JSON string:
 
+```html
 <am5-chart config='{
   "type": "PieChart",
   "properties": {
-    "series": \[{
+    "series": [{
       "type": "PieSeries",
       "settings": { "valueField": "value", "categoryField": "category" },
       "properties": {
-        "data": \[
+        "data": [
           { "category": "One", "value": 10 },
           { "category": "Two", "value": 9 },
           { "category": "Three", "value": 6 }
-        \]
+        ]
       }
-    }\]
+    }]
   }
 }'></am5-chart>
+```
 
 Or loaded from a file, with `src`:
 
+```html
 <am5-chart src="chart.json"></am5-chart>
+```
 
 In code, the `config` property takes an object or a JSON string:
 
+```typescript
 let element = document.createElement("am5-chart");
 
 element.config = {
   type: "PieChart",
   properties: {
-    series: \[{
+    series: [{
       type: "PieSeries",
       settings: { valueField: "value", categoryField: "category" },
       properties: {
-        data: \[
+        data: [
           { category: "One", value: 10 },
           { category: "Two", value: 9 },
           { category: "Three", value: 6 }
-        \]
+        ]
       }
-    }\]
+    }]
   }
 };
 
 document.getElementById("chartdiv").appendChild(element);
+```
 
+```javascript
 var element = document.createElement("am5-chart");
 
 element.config = {
   type: "PieChart",
   properties: {
-    series: \[{
+    series: [{
       type: "PieSeries",
       settings: { valueField: "value", categoryField: "category" },
       properties: {
-        data: \[
+        data: [
           { category: "One", value: 10 },
           { category: "Two", value: 9 },
           { category: "Three", value: 6 }
-        \]
+        ]
       }
-    }\]
+    }]
   }
 };
 
 document.getElementById("chartdiv").appendChild(element);
+```
 
 Changing the config, by attribute or property, builds the chart again. Removing the element from the page disposes the chart. Moving the element keeps it.
 
-MORE INFOFor the config format, see "[Serializing / JSON config](https://www.amcharts.com/docs/v5/concepts/serializing/)". To have the chart animate in when it loads, use the `autoAppear` setting in the config (more about it in "[Animations](https://www.amcharts.com/docs/v5/concepts/animations/)").
+MORE INFO For the config format, see "[Serializing / JSON config](https://www.amcharts.com/docs/v5/concepts/serializing/)". To have the chart animate in when it loads, use the `autoAppear` setting in the config (more about it in "[Animations](https://www.amcharts.com/docs/v5/concepts/animations/)").
+
 
 ## Themes
 
 Themes are not part of a config. With script tags, list theme names in the `themes` attribute, separated by spaces or commas. Each theme's file must be loaded first.
 
+```html
 <am5-chart src="chart.json" themes="Animated Dark"></am5-chart>
+```
 
 With npm, set theme classes on the `themes` property:
 
-import am5themes\_Animated from "@amcharts/amcharts5/themes/Animated";
+```typescript
+import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
 
-element.themes = \[am5themes\_Animated\];
+element.themes = [am5themes_Animated];
+```
 
-import am5themes\_Animated from "@amcharts/amcharts5/themes/Animated";
+```javascript
+import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
 
-element.themes = \[am5themes\_Animated\];
+element.themes = [am5themes_Animated];
+```
 
 ## Size
 
 The chart fills the element. Size it with CSS like any other block element. If nothing gives it a height, it is 400 pixels high.
 
+```html
 <am5-chart src="chart.json" style="height: 600px"></am5-chart>
+```
 
 ## SVG renderer
 
 Charts are drawn on canvas. To draw the chart as SVG instead, set `renderer="svg"`:
 
+```html
 <am5-chart src="chart.json" renderer="svg"></am5-chart>
+```
 
-MORE INFOFor differences between the two, see "[Root element](https://www.amcharts.com/docs/v5/getting-started/root-element/)".
+MORE INFO For differences between the two, see "[Root element](https://www.amcharts.com/docs/v5/getting-started/root-element/)".
 
 ## Accessing the chart
 
@@ -133,24 +158,29 @@ Once the chart is built, the element's `root` and `chart` properties hold its ro
 
 The chart is built asynchronously. `whenReady()` returns a promise that resolves once it is built, or right away if it already is:
 
+```typescript
 let element = document.querySelector("am5-chart");
 
 element.whenReady().then(function(ev) {
-  am5plugins\_exporting.Exporting.new(ev.root, {
-    menu: am5plugins\_exporting.ExportingMenu.new(ev.root, {})
+  am5plugins_exporting.Exporting.new(ev.root, {
+    menu: am5plugins_exporting.ExportingMenu.new(ev.root, {})
   });
 });
+```
 
+```javascript
 var element = document.querySelector("am5-chart");
 
 element.whenReady().then(function(ev) {
-  am5plugins\_exporting.Exporting.new(ev.root, {
-    menu: am5plugins\_exporting.ExportingMenu.new(ev.root, {})
+  am5plugins_exporting.Exporting.new(ev.root, {
+    menu: am5plugins_exporting.ExportingMenu.new(ev.root, {})
   });
 });
+```
 
 The element also fires DOM events: `ready` when the chart is built (with `root` and `chart` in `event.detail`), and `error` if it could not be built (with the error in `event.detail`):
 
+```typescript
 element.addEventListener("ready", function(ev) {
   console.log("Chart is ready", ev.detail.chart);
 });
@@ -158,7 +188,9 @@ element.addEventListener("ready", function(ev) {
 element.addEventListener("error", function(ev) {
   console.log("Chart could not be built", ev.detail);
 });
+```
 
+```javascript
 element.addEventListener("ready", function(ev) {
   console.log("Chart is ready", ev.detail.chart);
 });
@@ -166,19 +198,28 @@ element.addEventListener("ready", function(ev) {
 element.addEventListener("error", function(ev) {
   console.log("Chart could not be built", ev.detail);
 });
+```
+
+NOTE A chart with a config right in the page can be built before a script gets to add its `ready` listener. `whenReady()` works no matter when it is called, so prefer it.
+
+## In frameworks
 
-NOTEA chart with a config right in the page can be built before a script gets to add its `ready` listener. `whenReady()` works no matter when it is called, so prefer it.
+Our packages for React, Vue, Angular and Svelte wrap the element: they load its code in the browser only, so pages can be rendered on a server, and take the config, themes and renderer as props or inputs. See [Integrations](https://www.amcharts.com/docs/v5/getting-started/integrations/).
 
 ## Custom element name
 
 To use the element under another name, register it with `defineChartElement()`. The name must contain a hyphen.
 
+```typescript
 import { defineChartElement } from "@amcharts/amcharts5/element";
 
 defineChartElement("my-chart");
+```
 
+```javascript
 import { defineChartElement } from "@amcharts/amcharts5/element";
 
 defineChartElement("my-chart");
+```
 
 `<am5-chart>` stays registered too.