@amcharts/amcharts5-mcp 1.7.0 → 1.8.0

package/README.md

@@ -207,13 +207,15 @@ npm start
 | `get_core_reference` | Get core amCharts 5 docs — setup, themes, colors, events, common pitfalls |
 | `get_chart_reference` | Get full reference for a chart type (e.g. "pie", "sankey", "xy") |
 | `list_chart_types` | List all available chart types and their keywords |
-| `search_docs` | Search the skill reference docs by keyword |
+| `search_docs` | Search the skill reference docs by keyword (`scope: "all"` adds the full docs, API reference and examples) |
 | `search_all` | Search across **everything** — skill docs, full documentation, and code examples |
 | `get_doc` | Get a full documentation page (e.g. "charts/xy-chart/axes", "concepts/events") |
 | `get_section` | Get a specific section from a reference file by heading |
 | `get_quick_start` | Get a minimal working template for any chart type |
-| `list_examples` | Browse all 283 examples, optionally filtered by category |
+| `list_examples` | Browse all 290+ examples, optionally filtered by category |
 | `get_example` | Get the full code for a specific example |
+| `get_api_reference` | Get the API reference for a class, interface or function — settings with their defaults, events, inheritance and the import line |
+| `list_geodata` | Find map (geodata) files — world, continents, countries, regional packs and the per-Congress US congressional district packs — with each file's CDN path, script global and ES import |
 
 ## Example Usage
 
@@ -225,16 +227,29 @@ Once connected, your AI assistant can:
 - **"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")`
 - **"What chart types are available?"** → AI calls `list_chart_types()`
+- **"Map the current US congressional districts"** → AI calls `list_geodata("congressional whole country")`
 
 ## Content
 
-The server includes **1,500+ documents**:
+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)
 - **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`
 - **Curated skill reference** — quick-start templates and chart-specific guides from the [amCharts 5 AI Skill](https://github.com/amcharts/amcharts5-skill)
 
+## Security
+
+- **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.
+- **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/
+
 ## License
 
 MIT

package/content/SKILL.md

@@ -157,8 +157,14 @@ chart.get("colors").set("colors", [
   am5.color(0x86a873),
   am5.color(0xbb9f06)
 ]);
+
+// A color on a scale through several colors (5.21.2): position 0–1, clamped, colors evenly spaced
+var ic = root.interfaceColors;
+var mid = am5.Color.interpolateColors(0.5, [ic.get("negative"), ic.get("warning"), ic.get("positive")]);   // = warning
 ```
 
+The interface color `warning` (5.21.2) is a yellow between `negative` (red) and `positive` (green), for the middle of a bad-to-good scale. Prefer `interpolateColors()` through it over `am5.Color.interpolate(t, negative, positive)`, whose middle is brown.
+
 ## Legend
 
 ```js
@@ -330,6 +336,15 @@ series.set("heatRules", [{
   max: 30,
   key: "radius"
 }]);
+
+// Through more than two values (5.21.2): `stops` in place of min/max, e.g. red–yellow–green
+var ic = root.interfaceColors;
+series.set("heatRules", [{
+  target: series.columns.template,
+  dataField: "valueY",
+  stops: [ic.get("negative"), ic.get("warning"), ic.get("positive")],
+  key: "fill"
+}]);
 ```
 
 **Heat rule settings:**
@@ -341,6 +356,7 @@ series.set("heatRules", [{
 | `dataField` | string | Data field for the value: `"valueY"`, `"value"`, `"valueX"`, etc. |
 | `min` | color/number | Value applied at the lowest data value |
 | `max` | color/number | Value applied at the highest data value |
+| `stops` | array | Values for a scale through more than two (5.21.2), in place of `min`/`max`: the lowest data value gets the first, the highest the last, blended between. Numbers, percents or colors, all of one kind |
 | `minValue` | number | Override auto-calculated min (skips `calculateAggregates`; `0` is honored since 5.21.0) |
 | `maxValue` | number | Override auto-calculated max (skips `calculateAggregates`; `0` is honored since 5.21.0) |
 | `customFunction` | function | `(sprite, min, max, value)` — full control over the rule |
@@ -392,6 +408,14 @@ series.events.on("datavalidated", function() {
   heatLegend.set("startValue", series.getPrivate("valueLow"));
   heatLegend.set("endValue", series.getPrivate("valueHigh"));
 });
+
+// Through several colors (5.21.2): `colors` in place of startColor/endColor, matching a heat rule's `stops`
+var ic = root.interfaceColors;
+var scaleLegend = chart.children.push(am5.HeatLegend.new(root, {
+  orientation: "horizontal",
+  colors: [ic.get("negative"), ic.get("warning"), ic.get("positive")]
+  // stepCount: 1 (default) = a gradient through them; with stepCount > 1, one step per color
+}));
 ```
 
 ## Animations
@@ -488,14 +512,16 @@ const cursor = chart.set("cursor", am5xy.XYCursor.new(root, {}));
 
 ## Settings that already equal the default — omit them
 
-Generated code routinely spells out settings that equal the amCharts default (verified against the default themes of 5.21.0). They add noise and mislead readers into thinking they matter. Do not emit these unless changing them:
+Generated code routinely spells out settings that equal the amCharts default (verified against the default themes, and for `Gantt` the code, of 5.21.2). They add noise and mislead readers into thinking they matter. Do not emit these unless changing them:
 
 | Class | Setting(s) that are already the default |
 |-------|------------------------------------------|
 | All hierarchy series | `childDataField: "children"`, `downDepth: 1`, `initialDepth: 5` |
 | `Sunburst`, `Partition`, `Treemap`, `VoronoiTreemap` | `singleBranchOnly: true` (`Partition`/`Treemap` also `upDepth: 0`; `VoronoiTreemap` also `shapeType: "polygon"`; `Sunburst` ignores the setting since 5.21.0 — always single-branch) |
 | `Tree`, `ForceDirected` | `singleBranchOnly: false`, `upDepth: Infinity`, `topDepth: 0` (`Tree` also `orientation: "vertical"`) |
-| `PieSeries`, `FunnelSeries` | `alignLabels: true` (`FunnelSeries` also `orientation: "vertical"`, `startLocation: 0`, `endLocation: 1`, `bottomRatio: 0`) |
+| `PieSeries`, `FunnelSeries`, `PyramidSeries`, `PictorialStackedSeries` | `alignLabels: true` (`PieSeries` also `startAngle: -90`, `endAngle: 270`; `FunnelSeries` also `orientation: "vertical"`, `startLocation: 0`, `endLocation: 1`, `bottomRatio: 0`) |
+| `Chord` | `sort: "none"` (data order) |
+| `Gantt` | `excludeWeekends: true` |
 | `XYSeries` (all XY series) | `maskBullets: true` — note the default is **true**, so `maskBullets: false` is a real change |
 | `LineSeries` (incl. smoothed/step) | `connect: true`; `StepLineSeries` `noRisers: false` |
 | `XYChart` | `maxTooltipDistance` — leave **unset** (unset shows tooltips for all items in the category; `0` is *not* the same) |
@@ -532,6 +558,16 @@ series.data.insertIndex(1, { category: "Inserted", value: 50 });
 // ✅ series.dataItems.forEach(function(dataItem) {})         — standard JS
 ```
 
+**Changing values on existing data items.** Series draw from the **working** values, so `dataItem.set("valueY", v)` (or `"value"` on a pie) changes nothing on screen, and `markDirtyValues()` doesn't help. Change the data row with `series.data.setIndex(i, row)` (animates), or set the working key too (jumps; use it for per-frame updates):
+
+```js
+xySeries.dataItems[0].setAll({ valueX: 4, valueY: 7, valueXWorking: 4, valueYWorking: 7 });   // XY series
+pieSeries.dataItems[0].setAll({ value: 80, valueWorking: 80 });                                // pie, funnel, pyramid
+// per-frame updates through setIndex on XY: set interpolationDuration: 0 on the series, or the points lag behind
+```
+
+A data item's bullets are a plain array **property**: `dataItem.bullets?.[0]?.get("sprite")` is the sprite the bullet function made (`dataItem.get("bullets")` is `undefined`).
+
 ## Adapters
 
 ```js
@@ -566,6 +602,13 @@ series.columns.template.states.create("active", {
 // State animation: stateAnimationDuration, stateAnimationEasing
 ```
 
+**A state keeps the value it first replaced.** Once a state (e.g. `hover`) has changed a setting, the sprite's `"default"` state holds the value from that moment and restores it on every unhover. So a setting changed later (painting a polygon on click, a new base color) snaps back on the next unhover unless you change it in both places:
+
+```js
+polygon.set("fill", color);
+polygon.states.lookup("default")?.set("fill", color);
+```
+
 ## Parameterized themes — Monochrome & Adaptive (5.20.0)
 
 Two themes generate their palette from colors you pass in (OKLCH-based, so the result stays perceptually balanced). Because a theme cannot take constructor parameters, these ship as **factory functions** — call them with `(root, settings)`; `.new(root, settings)` also works.
@@ -599,6 +642,12 @@ root.setThemes([
 
 Both are additive (they do not modify built-in themes) and both handle dark mode themselves via `dark: true` — do not also add the `Dark` theme.
 
+**More settings (5.21.2, both themes, all off by default):** `interleave: true` takes the colors in the order 1, 4, 2, 5, 3, 6, so series next to each other differ more (Monochrome keeps `accent` first); `mapShade: true` fills map land with a mid shade of the base color, as light as default map land, instead of the color itself; `keepContrast: true` keeps the series colors and primary buttons at least 3:1 against the background (or give a ratio, e.g. `4.5`). A branded palette:
+
+```js
+am5themes_Adaptive(root, { baseColor: 0x2c6e91, baseColor2: 0xffdd00, count: 10, interleave: true, mapShade: true, keepContrast: true })
+```
+
 ## Custom themes
 
 ```js
@@ -656,13 +705,15 @@ 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.
 
+**`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.
+
 ## Data processor
 
 ```js
 // Auto-convert fields when loading external / API data
 series.data.processor = am5.DataProcessor.new(root, {
   dateFields: ["date"],
-  dateFormat: "yyyy-MM-dd",
+  dateFormat: "yyyy-MM-dd",  // read as local time (UTC with root.utc); see below for leaving it out
   numericFields: ["value", "count"],
   colorFields: ["color"],
   emptyAs: 0  // replace null, undefined and "" with 0 (before 5.21.0 it also replaced 0 and false)
@@ -670,6 +721,8 @@ series.data.processor = am5.DataProcessor.new(root, {
 // Configure processor BEFORE setting data
 ```
 
+Without `dateFormat`, since 5.21.1 the browser's `Date` parses the strings, so ISO strings work and a date-only `"2024-03-15"` is midnight **UTC**. Before 5.21.1 every such string became 1 January 1970.
+
 ## Serializing to JSON (ChartSerializer / JsonParser)
 
 `am5plugins_json.ChartSerializer` turns a live chart into a JSON config and `am5plugins_json.JsonParser` rebuilds it (`await parser.parse(config, { parent: root.container })`). Rules that keep round-trips working:
@@ -853,11 +906,11 @@ onUnmounted(() => { root.dispose(); });
 20. **Gantt data uses TWO separate calls** — Do NOT use `chart.data.setAll()`. Set categories on `chart.yAxis.data.setAll([{id, name, parentId, color}])` and tasks on `chart.series.data.setAll([{id, start, duration, progress, linkTo}])`. Use flat `parentId` for hierarchy, NOT nested `children` arrays. CDN order: `index.js` → `xy.js` → `plugins/colorPicker.js` → `gantt.js` → `themes/Animated.js` (gantt.js webpack-depends on colorPicker chunk). See `references/gantt.md`.
 21. **No continent-level geodata at top-level CDN** — `geodata/europeLow.js` does NOT exist. Use `geodata/region/world/europeLow.js` (global: `am5geodata_region_world_europeLow`) or filter `worldLow` with `include: [...]`.
 22. **Do not add chart titles as HTML** — HTML titles are outside the chart and won't appear in exports. Use `am5.Label` pushed into the container BEFORE the chart, with `verticalLayout` on the container. See "Chart title" section above.
-23. **`XYChartScrollbar` axes — never use `scrollbar.get("xAxis")`** — The axes passed to the scrollbar constructor are NOT stored as gettable settings. Create axes as separate variables, pass them to the scrollbar, and reuse those same variables for the scrollbar's inner series. `scrollbar.get("xAxis")` returns `undefined`.
+23. **`XYChartScrollbar` has no `xAxis`/`yAxis` settings** — its preview is a chart of its own, `scrollbar.chart`: push the preview's axes into `scrollbar.chart.xAxes`/`yAxes`, its series into `scrollbar.chart.series`, and give that series the data. Axes passed to `XYChartScrollbar.new()` are never added to the preview (its series then throws), and `get("xAxis")` only hands back whatever you passed. See `references/xy.md` → Scrollbar.
 24. **`am5.color()` only accepts hex integers or CSS strings** — `am5.color(0xff0000)`, `am5.color("#ff0000")`, `am5.color("rgb(255,0,0)")` are valid. `am5.color({ r: 255, g: 0, b: 0 })` is NOT — it throws.
-25. **`MapChart` has NO `"colors"` setting** — `chart.get("colors")` returns `undefined` on `MapChart`. Only XY, Radar, and Percent charts auto-create a ColorSet. For maps, create your own: `am5.ColorSet.new(root, {})`.
+25. **`MapChart` has no default `colors`** — it inherits the `colors` setting from `SerialChart`, but no theme sets it on a map, so `chart.get("colors")` returns `undefined`, and map series don't use it anyway. XY and Radar charts (and percent series, via `series.get("colors")`) get a ColorSet from the theme. For maps, make your own: `am5.ColorSet.new(root, {})`.
 26. **`VoronoiTreemap` has NO `.rectangles` property** — Unlike `Treemap` (which has `series.rectangles.template`), `VoronoiTreemap` renders organic polygon cells. Style via `series.nodes.template` and its children, not `.rectangles`.
-27. **Labels with data placeholders need `populateText: true`** — When a Label uses data field placeholders like `text: "{name}"`, you MUST also set `populateText: true`. Without it, the placeholder is not resolved and the label appears blank. This applies everywhere Labels display dynamic data — bullet labels, map point labels, etc. Example: `am5.Label.new(root, { text: "{name}", populateText: true, ... })`.
+27. **Labels with data placeholders need `populateText: true`** — `Label` defaults to `populateText: false`; labels the library makes for you (axis, legend, tooltip, pie/funnel slice labels, hierarchy and flow node labels…) get `true` from their own theme rules, but a `Label` you create does not. Any Label you create whose `text` has `{placeholders}` (a bullet sprite, a child of a bullet's container, a map point label) needs `populateText: true`, or it shows the braces literally. Example: `am5.Label.new(root, { text: "{name}", populateText: true, ... })`. A `tooltipText` is filled in regardless.
 28. **Easing: `am5.ease.in()` does NOT exist** — amCharts 5 provides base easing functions (`am5.ease.cubic`, `am5.ease.bounce`, `am5.ease.elastic`, `am5.ease.linear`, `am5.ease.quad`, `am5.ease.sine`, `am5.ease.circle`, `am5.ease.exp`; `am5.ease.pow(t, e)` takes an exponent, so it is only usable wrapped: `(t) => am5.ease.pow(t, 3)`) and three modifiers: `am5.ease.out()`, `am5.ease.inOut()`, `am5.ease.yoyo()`. Usage: `am5.ease.cubic` (ease-in by default), `am5.ease.out(am5.ease.cubic)` (ease-out), `am5.ease.inOut(am5.ease.cubic)` (ease in+out). There is NO `am5.ease.in()` — using it throws a runtime error. The base functions already ease-in by default.
 29. **`forceHidden` vs `visible`** — `forceHidden: true` ALWAYS hides an element, immune to states, themes/library and even `show()`. `visible` is weaker: amCharts re-manages it on many elements (notably cursor lines, but also labels, ticks, tooltips, grid) in response to interaction or data changes, so a `visible: false` you set may be flipped back to `true`. Rules of thumb: for a **persistent hide**, use `forceHidden: true` (`cursor.lineX.set("forceHidden", true)`, `yRenderer.labels.template.set("forceHidden", true)`, `xRenderer.grid.template.set("forceHidden", true)`). To **reveal** an element that defaults hidden — notably **axis ticks** (`ticks.template` defaults to `visible:false`) — you must raise `visible: true`; flipping `forceHidden` alone won't show it. For cursor lines specifically, always access `cursor.lineX`/`cursor.lineY` after creation — do NOT pass them as constructor options.
 30. **`snapTooltip: true` on series for cursor tooltip snapping** — When using a cursor and you want tooltips to snap to data points, set `snapTooltip: true` on the series in addition to (or instead of) `snapToSeries` on the cursor. This is especially useful for timeline/curve charts.
@@ -868,6 +921,10 @@ 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.
+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".
 
 ## Easing functions
 
@@ -912,7 +969,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.0** (2026-10-08). 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.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).
 
 **Renamed settings (old name still works but is deprecated — use the new one):**
 
@@ -929,6 +986,20 @@ 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.
 
+**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".
+- Heat rules: `stops` (numbers, percents or colors, all of one kind) in place of `min`/`max`, for a scale through more than two values. `HeatLegend`: `colors` in place of `startColor`/`endColor`, a gradient through them with `stepCount: 1` or one step per color otherwise (`stepCount` is then ignored). See "Heat rules".
+- `am5themes_Adaptive` and `am5themes_Monochrome`: `interleave`, `mapShade` and `keepContrast` (all off by default). See "Parameterized themes".
+- Fixed: a ColorSet `step` with a theme that reuses its colors used only two or three of them (word clouds and treemaps with Nord, Pastel or Adaptive), see "ColorSet"; `RadialGradient` with pixel `x`/`y` was off-center on radar fills and similar shapes in 5.21.1.
+
+**Behavior changes / fixes (5.21.1, 2026-10-13)** — no workaround needed any more:
+- `root.timezone`: charts were up to 16 times slower with it, and grid, labels, data groups and date math could be an hour off around a daylight saving change. A `DateAxis` grid of several hours now stays on the clock after a DST change (where the clocks skip a grid time, the line goes at the jump). `PeriodSelector` and `DateRangeSelector` follow `root.timezone`/`root.utc` (they used the viewer's time zone). Date formats `Z`, `ZZ`, `x`, `i`, `I` are right with `root.timezone`, and `YYYY`, `ww`, `W`, `DDD` honor `root.utc`.
+- `DataProcessor`: string dates in `dateFields` without a `dateFormat` were all read as 1 January 1970. Now the browser's `Date` parses them, and a date-only `"2024-03-15"` is midnight UTC. See "Data processor".
+- A chart in a container scaled with CSS (`transform` or `zoom`) was scaled twice, and clicks hit the wrong elements.
+- Maps: a `zoomLevel` set before the map loaded was ignored or left the map blank; `MapSankeySeries` bands follow `linkColorMode` and node fill changes, and nodes without coordinates are drawn; raised map lines (`MapLine` `altitude`) draw 3–4 times faster.
+- `RadialGradient` is centered on map polygons, line and area fills and bullets (with `target` set, on the target). `Picture`: changing a shadow setting after the image loaded no longer removes the image. `CurveChart`: a path scaled down to fit no longer gets far too many labels and grid lines. Responsive theme: XY axis ticks on small charts are no longer moved inside the plot.
+
 **New in 5.21.0 (2026-10-08):**
 
 *Rendering, export, chart element*
@@ -961,7 +1032,7 @@ am5hierarchy.VoronoiTreemap.new(root, { shapeType: "rectangle" }); // was: type
 - `Gantt`: the category axis' `colorField` and `nameField` are honored (bar colors were always read from `color`).
 - `Sunburst` ignores `singleBranchOnly` (always `true`). `StockToolbar` `focusable` now defaults to `true`.
 - Responsive theme: minor axis labels are hidden only on charts 600 px or smaller (was 1000 px), so turned-on minor labels show on mid-size charts.
-- `PatternSet` starts over from its first pattern past the end of its list (the built-in list has 16, so the 17th element and later got no pattern).
+- `PatternSet` starts over from its first pattern past the end of its list (elements after the 17th got no pattern).
 - `DurationFormatter`: codes `H`, `D`, `Y`, `K`, `k`, `n` work (as `h`, `d`, `y`, `h`, `h`, `S` — e.g. `"HH:mm:ss"` gave `NaN`); durations between a month and a year use the month formats again (`1m 15d 00:00:00`, not `45d 00:00:00`), which `DurationAxis` labels show.
 - `am5.CSVParser` honors `skipEmpty: false` (empty lines were always skipped). `series.updateData([])` removes every data item (it kept the first).
 - A `fontSize` given as a number in a string (`"8"`) counts as pixels (was ignored). Filters (`brightness`, `saturate`, `blur`, …) combine instead of replacing each other, and one set back to neutral turns off.
@@ -992,7 +1063,7 @@ am5hierarchy.VoronoiTreemap.new(root, { shapeType: "rectangle" }); // was: type
 - 20+ new themes (5.20.0): `Midnight`, `Ember`, `Nord`, `Pastel`, `Colorblind`, `Patterns`, `Petroleum`, `Savanna`, plus `*Dark` variants of most palettes. Two parameterized factory themes, `Monochrome` and `Adaptive` — see "Parameterized themes" above.
 - New fill patterns (5.20.0): `am5.StarPattern` (`radius`, `innerRadius`, `spikes`, `gap`, `checkered`) and `am5.TrianglePattern` (`maxWidth`, `maxHeight`, `gap`, `checkered`).
 - `rotateShapes` (5.20.0) on `RectanglePattern`/`StarPattern`/`TrianglePattern`: `rotation` then spins each shape around its own center instead of the whole grid — tiles seamlessly and is much faster. Prefer it over a whole-pattern `rotation` on large tiles.
-- `Series`: `fillGradient` / `strokeGradient` settings. A bullet `Graphics` with no paint of its own (`fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient`) now inherits all of them from its series — and on pie, funnel, flow and hierarchy charts, from its own slice/node (5.20.0–5.20.1).
+- `Series`: `fillGradient` / `strokeGradient` settings, handed to bullets (the series' own fills, lines and columns don't use them: set gradients on `fills.template` / `columns.template` / `strokes.template`). A bullet `Graphics` with no paint of its own (`fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient`) now inherits all of them from its series — and on pie, funnel, flow and hierarchy charts, from its own slice/node (5.20.0–5.20.1).
 
 *XY charts*
 - `XYChart`: `strokeWidths` (array of pixel widths) and `strokeDasharrays` (array of dash arrays) — cycled across line series as they are added, exactly like `colors`. Lets series be told apart without relying on color, e.g. with the `Patterns` theme.
@@ -1012,7 +1083,7 @@ am5hierarchy.VoronoiTreemap.new(root, { shapeType: "rectangle" }); // was: type
 - `Root`: `ariaLabel` is now applied to the `<div>` holding the chart's focusable elements (5.20.0).
 - `Label`: `oversizedBehavior: "truncate"` now ignores `maxHeight` (there is no way to truncate text vertically).
 - A `Container`'s `Rectangle`/`RoundedRectangle` background now defaults `crisp` to `true` unless set explicitly (5.20.0).
-- `Root` (5.20.2): `fontFamily`, `fontSize` (number or string) and `fontWeight` (`"normal" | "bold" | "bolder" | "lighter" | "100"…`"900"`) settings — defaults for **all** text elements unless overridden on an element. Set them in `am5.Root.new("chartdiv", { fontFamily: "Inter" })` or `root.setAll({...})` instead of a custom theme rule on `Label`.
+- `Root` (5.20.2): `fontFamily`, `fontSize` (number or string) and `fontWeight` (`"normal" | "bold" | "bolder" | "lighter"`, or `"100"` … `"900"`) settings — defaults for **all** text elements unless overridden on an element. Set them in `am5.Root.new("chartdiv", { fontFamily: "Inter" })` or `root.setAll({...})` instead of a custom theme rule on `Label`.
 - `am5.SerialChartContainer` (5.20.2) — a directly usable `SerialChart` whose `seriesContainer` sits inside a `ZoomableContainer` (exposed as `chart.zoomableContainer`), so series such as `ForceDirected` can be zoomed and panned. Exported from the **`am5` root module**, not a chart package. Optional `zoomTools` setting takes a `ZoomTools` instance whose `target` is pointed at the series container automatically. Bullets added to its series are drawn (5.20.4) and flow-chart bullets are placed correctly inside it (5.20.5). See `references/hierarchy.md`.
 
 *JSON config / serialization (5.20.2 – 5.20.8)*

package/content/flow.md

@@ -127,7 +127,7 @@ const series = root.container.children.push(
     padAngle: 2,              // gap between nodes in degrees
     radius: am5.percent(90),
     startAngle: 80,
-    sort: "ascending"         // "ascending" | "descending" | "none"
+    sort: "ascending"         // "ascending" | "descending" | "none" (default: data order)
   })
 );
 

package/content/gantt.md

@@ -47,7 +47,7 @@ var chart = root.container.children.push(
 | `editable` | boolean | `true` | Allow user to add, edit, remove, drag tasks |
 | `durationUnit` | string | `"day"` | `"year"`, `"month"`, `"week"`, `"day"`, `"hour"`, `"minute"`, `"second"` |
 | `weekends` | number[] | `[0, 6]` | Non-working days (0=Sun, 1=Mon, ... 6=Sat) |
-| `excludeWeekends` | boolean | `false` | Whether to exclude weekends from task durations |
+| `excludeWeekends` | boolean | `true` | Skips `weekends` and `holidays`: task starts move to the next working day and durations count working days only. Set `false` to count every day |
 | `holidays` | Date[] | `[]` | Specific non-working dates |
 | `snapThreshold` | number | `0.5` | Drag snap position within a period (0–1) |
 | `sidebarWidth` | number \| Percent | `30%` | Sidebar width in pixels or Percent |

package/content/hierarchy.md

@@ -145,6 +145,8 @@ series.outerCircles.template.setAll({
 series.data.setAll(data);
 ```
 
+On `ForceDirected`, `nodePadding` (default `0`) is room in pixels kept free around each node (its collision radius is its radius + `nodePadding`), so neighbours stay at least twice that apart. It is not the `Sankey` `nodePadding`, which is a real gap between nodes.
+
 Since 5.21.0 changing `manyBodyStrength`, `centerStrength`, or a link's `distance`/`strength` takes effect after the layout has settled (it used to do nothing) — no need to re-set the data to apply new forces.
 
 ## Sunburst

package/content/map.md

@@ -42,7 +42,16 @@ Pattern: camelCase country name + detail level. E.g. `germanyLow`, `canadaHigh`,
   - CDN: `https://cdn.amcharts.com/lib/5/geodata/region/world/europeLow.js`
   - Global: `am5geodata_region_world_europeLow`
 - For a map of European countries, use `worldLow.js` and filter with `include: ["DE", "FR", "IT", ...]`
-- US congressional districts: `geodata/usaCongressionalLow.js` (may not be available on all CDN versions)
+- **US congressional districts** come in versioned packs under `geodata/region/usa/<pack>/`, each with `usaCongressionalLow.js` / `usaCongressionalHigh.js` (all states) and per-state `<st>Low.js` / `<st>High.js` (e.g. `txLow.js`). There is no top-level `geodata/usaCongressionalLow.js`.
+
+| Pack | Districts |
+|------|-----------|
+| `congressional` | 117th Congress (the original set; the 116th used the same districts) |
+| `congressional2022` | 118th |
+| `congressional2025` | 119th |
+| `congressional120` | 120th, the newest (geodata 5.1.6; includes proposed changes) |
+
+**Global names** are `am5geodata_` + the path below `geodata/`, with `/` → `_` and case kept: `geodata/region/usa/congressional120/usaCongressionalLow.js` → `am5geodata_region_usa_congressional120_usaCongressionalLow`; ES import `@amcharts/amcharts5-geodata/region/usa/congressional120/usaCongressionalLow`. The npm package has the same maps (default exports, raw GeoJSON under `json/`, also on the CDN as `geodata/json/<path>.json`), and its `loadMap("region/usa/congressional120/txLow")` loads any map by path. Where the amCharts MCP server is connected, its `list_geodata(filter)` tool lists every map with its CDN path, global name and ES import.
 
 ## Core setup
 
@@ -168,6 +177,8 @@ const heatLegend = chart.children.push(am5.HeatLegend.new(root, {
 }));
 ```
 
+For a scale through more than two colors (5.21.2), give the heat rule `stops` instead of `min`/`max` and the legend `colors` instead of `startColor`/`endColor`: see SKILL.md "Heat rules". `Adaptive` and `Monochrome` themes take `mapShade: true` (5.21.2) for map land in a lighter shade of their base color.
+
 **Styling heat-legend segments.** With `stepCount: N` the legend draws N discrete `RoundedRectangle` markers inside `heatLegend.markerContainer`, all styled through `heatLegend.markers.template` (it accepts the usual Graphics settings — `stroke`, `strokeWidth`, `strokeOpacity`, `fillOpacity`, `cornerRadius*`, `tooltipText` for a per-block hover tooltip). Segment **thickness** is the marker's cross-axis size: a **vertical** legend uses the marker `width` (default `15`) with `height: 100%`; a **horizontal** legend uses `height` (default `15`) with `width: 100%`. Style via the template — `heatLegend.markers.values` can read empty even while `markerContainer.children` holds the rectangles.
 
 ```js
@@ -221,6 +232,12 @@ pointSeries2.data.setAll([
 
 `surfaceBullets: true` (5.21.0) lays the bullets onto the map surface, and `altitudeField` (5.21.0) raises points — see "Bullets on the surface" and "Raised lines and points" below.
 
+**A point's bullet sprite:** `dataItem.bullets` is a plain array property, not a setting (`dataItem.get("bullets")` is `undefined`), on every series type:
+
+```js
+var sprite = pointSeries.dataItems[0].bullets?.[0]?.get("sprite");   // the Circle made by the bullet function
+```
+
 **Points on lines as data rows (5.20.6):** `MapPointSeries` has `lineIdField` (default `"lineId"`), `positionOnLineField` (default `"positionOnLine"`), `autoRotateField` (default `"autoRotate"`) and `autoRotateAngleField` (default `"autoRotateAngle"`), so a point on a `MapLine` can be a plain row — `{ lineId: "jfk-lhr", positionOnLine: 0.5, autoRotate: true }`, where `lineId` is the line's data `id` in a `MapLineSeries` of the same chart — instead of `pushDataItem({ lineDataItem, positionOnLine })`. Data values of `autoRotate`/`autoRotateAngle` win over the bullet's own setting. `polygonIdField` still has **no** default — declare it as above. See "Animating bullets along lines".
 
 ### MapLineSeries (connections, routes)
@@ -363,6 +380,7 @@ polygonSeries.events.on("datavalidated", function() {
 | `nodeWidth` | number | `1` | Bar width in degrees (bar nodeType only) |
 | `nodePadding` | number | `0.3` | Extra padding on node shapes in degrees |
 | `antimeridian` | string | `"short"` | `"short"` for shortest path, `"long"` to avoid ±180° crossing |
+| `linkColorMode` | string | `"solid"` | `"solid"`: every band takes `mapPolygons.template`'s fill; `"source"` / `"target"`: each band takes that node's fill, so the nodes need colors (see "Band appearance"). Followed since 5.21.1, also when node fills change |
 | `sourceIdField` | string | `"sourceId"` | Data field for source polygon ID |
 | `targetIdField` | string | `"targetId"` | Data field for target polygon ID |
 | `sourceLongitudeField` | string | `"sourceLongitude"` | Data field for source longitude |
@@ -384,6 +402,16 @@ sankeySeries.mapPolygons.template.setAll({
 });
 ```
 
+Bands colored like their nodes — map nodes get no colors of their own, so give them a `ColorSet` (before the data):
+
+```js
+var sankeySeries = chart.series.push(am5map.MapSankeySeries.new(root, {
+  polygonSeries: polygonSeries,
+  linkColorMode: "source"     // each band takes its source node's fill ("target": its target's)
+}));
+sankeySeries.nodes.set("colors", am5.ColorSet.new(root, {}));   // map nodes have no colors by default
+```
+
 Per-link control point overrides in data:
 ```js
 sankeySeries.data.setAll([
@@ -563,7 +591,22 @@ satSeries.bullets.push(function (root, series, dataItem) {
 satSeries.data.setAll([{ latitude: 10, longitude: 0, altitude: 400000 }]);   // metres
 ```
 
-A point on a line takes the line's altitude. `mapLine.positionToAltitude(position)` returns the altitude (m) at `0`–`1` along a line. Works best on a globe (`geoOrthographic`, see `map-altitude-arcs` in the npm package examples).
+A point on a line takes the line's altitude. `mapLine.positionToAltitude(position)` returns the altitude (m) at `0`–`1` along a line. Works best on a globe (`geoOrthographic`, see `map-altitude-arcs` in the npm package examples). Raised lines draw 3–4 times faster since 5.21.1.
+
+**Heights per coordinate:** once a line's `altitude` is set (`0` for none), the third value of each coordinate is that point's height in metres, and a non-zero `altitude` adds its arc to each leg on top. One line can then change height along its length (a descent from orbit, relief along a parallel); without `altitude` the third values are ignored. The demo "Globe with raised parallels" (`maps/globe-with-raised-parallels`) does this.
+
+```js
+var pathSeries = chart.series.push(am5map.MapLineSeries.new(root, {}));
+pathSeries.mapLines.template.setAll({ altitude: 0, stroke: am5.color(0xff621f), strokeWidth: 2 });
+pathSeries.data.setAll([{ geometry: { type: "LineString",
+  coordinates: [[0, 0, 800000], [20, 10, 400000], [40, 15, 0]] } }]);   // [longitude, latitude, metres]
+```
+
+**Where a raised point is on screen:** for a `MapPointSeries` point, `dataItem.get("point")` is its raised position (`{ x, y }`) and `dataItem.get("clipped")` says whether it is hidden. For any other longitude, latitude and height `h` (MapUtils' `projectAltitude` is not exported): on a globe, `screen = T + (P − T) × (1 + h / R)`, with `P = chart.convert({ longitude, latitude })` the surface point, `T = chart.get("projection").translate()` the globe's center and `R = 6371008.8` m; on a flat map, `P` moved up by `h / R × projection.scale()`.
+
+**`clipFront: true`** on a point series hides the points on the near side. With points raised high (`altitudeField`), what is left are the ones behind the globe that rise past its edge: a starfield behind the globe (`clipBack`, default `true`, still hides those the globe covers).
+
+**`ClusteredPointSeries` with `altitudeField`:** a cluster's bullet floats at the average altitude of its points (the cluster data item gets `altitude`); points still cluster by their distance on screen.
 
 ### Bullets on the surface — `surfaceBullets` (5.21.0)
 
@@ -645,6 +688,35 @@ columns.data.setAll([{ id: "CN", value: 1410 }, { id: "IN", value: 1430 }, { id:
 
 Pixels have no outline by default (the theme keeps pixel polygons at `strokeWidth: 0`); set `strokeWidth` (and `stroke`) on `mapPolygons.template` to outline each pixel. `pixelSeries.pixels` is the `Graphics` that draws them all: `am5.renderToSVG(pixelSeries.pixels)` exports just the pixels, with each polygon's pixels in a `<g id="US" data-name="United States">`. `include`/`exclude` work as on `MapPolygonSeries`.
 
+**The classic dotted map** is `pixelType: "circle"` with `uniform: true`. Without `uniform` the pixels lie on the surface, so on projections such as `geoEqualEarth` the circles near the poles widen into ovals.
+
+**`step` for one country:** `step` is in degrees, so the default `2` suits the world but leaves a country only a few pixels. Derive it from the area shown, its longer side divided by the pixels wanted across it:
+
+```js
+var geodata = am5geodata_germanyLow;
+var b = am5map.getGeoBounds({ type: "GeometryCollection",
+  geometries: geodata.features.map(function (f) { return f.geometry; }) });   // { left, right, top, bottom } in degrees
+var countrySeries = chart.series.push(am5map.PixelMapSeries.new(root, {
+  geoJSON: geodata,
+  step: Math.max(b.right - b.left, b.top - b.bottom) / 60   // about 60 pixels across
+}));
+```
+
+(`getGeoBounds` spans `-180`…`180` for a shape that crosses the 180th meridian.)
+
+**Random column heights:** `pixelHeightFunction` runs again for every pixel whenever heights are recomputed (data changes, a hover state that sets `MapPolygon` `pixelHeight`, …), so `Math.random()` makes the columns jump. Use a deterministic hash of longitude and latitude, times the polygon's own height so per-polygon heights still apply:
+
+```js
+var hashed = chart.series.push(am5map.PixelMapSeries.new(root, {
+  geoJSON: am5geodata_worldLow,
+  columnHeight: 0.1,
+  pixelHeightFunction: function (dataItem, longitude, latitude) {
+    var h = Math.sin(longitude * 12.9898 + latitude * 78.233) * 43758.5453;
+    return (h - Math.floor(h)) * dataItem.get("mapPolygon").get("pixelHeight", 1);
+  }
+}));
+```
+
 ### Satellite images — `MapRasterSeries` (5.21.0)
 
 `am5map.MapRasterSeries` shows one image of the whole world, reprojected as the map turns and zooms (on the GPU with WebGL2 for orthographic, equirectangular, Mercator, Equal Earth and Natural Earth; on the CPU otherwise). With `nightSrc` and a sun position it shows day where the sun is up and night where it is down, blended across twilight.
@@ -659,7 +731,7 @@ raster.events.on("loaded", function () { /* src (and nightSrc) are drawn */ });
 raster.events.on("loaderror", function () { /* failed, or cross-origin without CORS */ });
 ```
 
-- The image must be **equirectangular** ("plate carrée": longitude −180…180 left to right, latitude 90…−90 top to bottom). The geodata package ships `geodata/images/earthDay2048.jpg` and `earthNight2048.jpg` (NASA Earth Observatory — credit it, e.g. a small `am5.Label`).
+- The image must be **equirectangular** ("plate carrée": longitude −180…180 left to right, latitude 90…−90 top to bottom). The CDN has `geodata/images/{earthDay,earthNight,moon,mars}{2048,4096}.jpg`, e.g. `https://cdn.amcharts.com/lib/5/geodata/images/moon4096.jpg` (the npm geodata package has no images). The Earth images are from NASA Earth Observatory: credit the source, e.g. with a small `am5.Label`.
 - `cors` (default `"anonymous"`): a cross-origin image is drawn only if its server sends CORS headers. A page opened from disk (`file://`) cannot read an image file beside it — serve the page, or use the CDN copy.
 - The series counts as the whole world in the map's bounds; on a regional map set `affectsBounds: false`. The projection needs `invert`, so nothing is drawn while `animateProjection()` runs.
 - Draw country borders over it with a `MapPolygonSeries` pushed after it, `fillOpacity: 0` on `mapPolygons.template`. `twilight` (default `12` degrees of sun height) sets how wide the day/night blend is.
@@ -686,6 +758,20 @@ night.get("sun").setAll({ radius: 12 });   // the sun is a Circle the series mak
 - `twilight` (default `12`) and `twilightSteps` (default `4`, number of shades from day to full night).
 - `sunAltitude` is for looks: `1000000`–`5000000` suits a globe.
 - `am5map.getSunPosition(date?)` takes a `Date` (default now) and returns the `{ longitude, latitude }` where the sun is directly overhead — also for `MapRasterSeries` `sunPosition`, or to place a sun marker on a `MapPointSeries`.
+- **JSON:** a saved chart keeps `sunDate`, never the `sunPosition` worked out from it, so a `"now"` map still follows the clock after parsing.
+
+**Day and night on another body.** `sunDate` is the Earth's sun only, so for the Moon or Mars set `sunPosition` to that body's sub-solar point (from your own ephemeris), and leave `sunDate` unset (it wins). A small `twilight` gives an airless body's sharp edge:
+
+```js
+chart.series.push(am5map.MapRasterSeries.new(root, {
+  src: "https://cdn.amcharts.com/lib/5/geodata/images/moon2048.jpg"
+}));
+var lunarNight = chart.series.push(am5map.NightSeries.new(root, {
+  sunPosition: { longitude: 30, latitude: 1.5 },   // the Moon's sub-solar point
+  twilight: 1.5                                    // default 12 (degrees)
+}));
+lunarNight.get("sun").set("forceHidden", true);    // hide the sun marker
+```
 
 ## Zoom controls
 
@@ -735,6 +821,8 @@ polygonSeries.mapPolygons.template.states.create("active", {
 });
 ```
 
+`clickZoom` sets `active` itself, so `toggleKey: "active"` is not needed (with it, the two still agree).
+
 **Start at the home position — `autoHome` (5.21.0).** Goes to the home position (`homeGeoPoint`, `homeZoomLevel`, `homeRotationX`/`homeRotationY`) once the map is loaded, as `goHome()` does — animated when `animationDuration` is set (the Animated theme sets it), at once otherwise. No `goHome()` call in a `datavalidated` handler needed, so a map loaded from JSON can start zoomed in. Default `false`.
 
 ```js
@@ -746,6 +834,22 @@ var chart = root.container.children.push(am5map.MapChart.new(root, {
 }));
 ```
 
+With `autoHome` and no `homeZoomLevel`, home zoom is `1`, so a starting `zoomLevel` is overridden: set `homeZoomLevel` to the same value. Without `autoHome`, a `zoomLevel` given to `MapChart.new()` is the starting zoom (since 5.21.1; before, one set before the map loaded was ignored or left the map blank).
+
+**Home on a globe.** On a map that pans by rotating (`panX: "rotateX"`, `panY: "rotateY"`), `goHome()` and the home button restore the rotation only from `homeRotationX` / `homeRotationY` (−longitude / −latitude). `homeGeoPoint` alone leaves the rotation as it is and shifts the globe sideways.
+
+```js
+var globe = root.container.children.push(am5map.MapChart.new(root, {
+  projection: am5map.geoOrthographic(),
+  panX: "rotateX",
+  panY: "rotateY",
+  homeRotationX: -10,   // home = centered on 10°E…
+  homeRotationY: -50    // …50°N
+}));
+```
+
+**`zoomStep`** (default `2`) is a multiplier, not an increment: `zoomIn()` and the + button multiply `zoomLevel` by it, `zoomOut()` divides, and the mouse wheel and double clicks use it too, one step per wheel event whatever its size. So keep it above `1` (`1` does nothing, below `1` reverses); `zoomStep: 1.1`–`1.2` gives fine control, e.g. on trackpads, which fire many small wheel events. `wheelSensitivity` does not affect wheel zoom, only wheel rotation.
+
 Fixed in 5.21.0: `goHome()` went to the wrong place before the map was ready or on a rotated map (globe); a zoomed-in map could not be dragged to its edges (with `maxPanOut: 0` not at all); `zoomToGeoBounds()` rotated with `animationDuration` instead of the given duration and changed the bounds object; `MapPointSeries.zoomToDataItems(items, true)` / `ClusteredPointSeries.zoomToCluster()` turned a globe to the wrong point; `chart.geoPoint()` and `getPolygonByGeoPoint()` were off on charts with padding.
 
 ## Globe (orthographic projection)
@@ -768,6 +872,8 @@ chart.animate({ key: "rotationY", to: -paris.latitude, duration: 1500, easing: a
 
 **IMPORTANT — Globe rotation direction:** To center the globe on a geographic point, set `rotationX` to **negative longitude** and `rotationY` to **negative latitude**. This is because rotation moves the globe under the camera: rotating X by -2.35 brings longitude 2.35 to the center. A common mistake is using positive coordinates, which rotates the globe in the wrong direction.
 
+Setting `rotationX`/`rotationY`/`rotationZ` on every frame (e.g. a camera that follows a moving point) performs fine.
+
 ## GraticuleSeries (grid lines / ocean background)
 
 ```js
@@ -825,8 +931,9 @@ am5map.MapChart.new(root, {
   rotationX: 0,             // center longitude
   rotationY: 0,             // center latitude
   rotationZ: 0,             // tilt
-  wheelY: "zoom",           // "zoom", "none"
-  wheelSensitivity: 1,      // zoom speed multiplier
+  wheelY: "zoom",           // "zoom", "rotateX", "rotateY", "none"
+  zoomStep: 2,              // zoom multiplier per step: buttons, wheel, double click (see "Zoom controls")
+  wheelSensitivity: 1,      // how far the wheel rotates the map ("rotateX"/"rotateY" only), not zoom speed
   doubleClickZoom: true,    // (5.20.2) double click zooms in, shift+double click out — default true
   boxZoom: "none",          // (5.20.2) "none" | "drag" | "shift" | "ctrl" | "alt" — key held to drag a zoom box
   autoHome: false,          // (5.21.0) true = go to homeGeoPoint/homeZoomLevel once loaded

package/content/pie.md

@@ -70,8 +70,8 @@ chart.appear(1000, 100);
 | `alignLabels` | boolean | Align labels in column (default: true). Set false for radial/inside labels |
 | `legendLabelText` | string | Legend label format, e.g. `"{category}"` |
 | `legendValueText` | string | Legend value format, e.g. `"{value}"` |
-| `startAngle` | number | Start angle in degrees (default: inherits from chart). Must match PieChart's startAngle for semi-circle |
-| `endAngle` | number | End angle in degrees (default: inherits from chart). Must match PieChart's endAngle for semi-circle |
+| `startAngle` | number | Start angle in degrees (default: `-90`). Must match PieChart's startAngle for semi-circle |
+| `endAngle` | number | End angle in degrees (default: `270`). Must match PieChart's endAngle for semi-circle |
 
 ### Labels
 
@@ -132,6 +132,15 @@ series.slices.template.adapters.add("fill", function(fill, target) {
 // series.slices.template.set("templateField", "sliceSettings");
 ```
 
+### Changing slice values live
+
+Percent series (pie, funnel, pyramid, pictorial) size slices from each data item's `valueWorking`, not `value`, so `dataItem.set("value", v)` moves nothing, and `series.markDirtyValues()` doesn't help. Change the data row, or set both keys:
+
+```js
+series.data.setIndex(0, { category: "A", value: 80 });        // animates (Animated theme)
+series.dataItems[1].setAll({ value: 5, valueWorking: 5 });    // jumps: for per-frame updates, e.g. a countdown donut
+```
+
 ## Funnel chart setup
 
 ```js
@@ -147,7 +156,7 @@ const series = chart.series.push(
     valueField: "value",
     categoryField: "stage",
     orientation: "vertical",   // "vertical" or "horizontal"
-    bottomRatio: 0,            // 0 = trapezoids (classic funnel), 1 = rectangles
+    bottomRatio: 0,            // 0 = rectangles (default), 1 = each slice narrows to the next (trapezoids)
     alignLabels: true
   })
 );
@@ -164,8 +173,8 @@ series.data.setAll([
 
 | Setting | Type | Description |
 |---------|------|-------------|
-| `orientation` | `"vertical" \| "horizontal"` | Direction of the funnel (required) |
-| `bottomRatio` | number (0–1) | 0 = trapezoids (classic funnel), 1 = rectangles (default) |
+| `orientation` | `"vertical" \| "horizontal"` | Direction of the funnel (default: `"vertical"`) |
+| `bottomRatio` | number (0–1) | 0 = rectangular slices (default); 1 = each slice narrows to the next (trapezoids) |
 | `alignLabels` | boolean | Align labels in a column (default: true) |
 
 ### Slice links (connectors between funnel slices)
@@ -245,7 +254,7 @@ series.data.setAll([
 | `orientation` | `"vertical"` \| `"horizontal"` | Fill direction |
 | `startLocation` | number (0–1) | Where the fill starts within the shape |
 | `endLocation` | number (0–1) | Where the fill ends within the shape |
-| `alignLabels` | boolean | Align labels outside the shape |
+| `alignLabels` | boolean | Align labels in a column outside the shape (default: true), as on funnel and pyramid |
 
 **Getting SVG paths:** Use any vector editor (Adobe Illustrator, Inkscape, Figma) to draw a shape and export as SVG, then extract the `d` attribute from the `<path>` element.
 

package/content/radar.md

@@ -570,8 +570,7 @@ root.dispose();
       strokeOpacity: 0,
       fillOpacity: 0.8,
       width: am5.percent(80),
-      cornerRadiusTL: 3,
-      cornerRadiusTR: 3
+      cornerRadius: 3          // radar columns are Slices: one cornerRadius, no cornerRadiusTL/TR
     });
 
     // Color each column differently

package/content/stock.md

@@ -324,6 +324,8 @@ var data = [
 
 **`PeriodSelector` labels (5.21.0):** a period without a `name` is labeled from its unit and count — `{ timeUnit: "month" }` shows `MONTH1`, `{ timeUnit: "ytd" }` shows `YTD` (before: `MONTHundefined`, `YTDundefined`). Give each period a `name` for nicer labels.
 
+**Time zones (5.21.1):** `PeriodSelector` and `DateRangeSelector` count periods and dates in `root.timezone` (or UTC with `root.utc`), like the date axis; before 5.21.1 they used the viewer's time zone. Charts with `root.timezone` are also much faster (up to 16 times) and keep grid, labels and data groups on the hour across daylight saving changes.
+
 ## Events
 
 ```js