@amcharts/amcharts5-mcp 1.1.4 → 1.1.5

package/content/SKILL.md

@@ -52,7 +52,7 @@ Docs: https://www.amcharts.com/docs/v5/
 | Core | `@amcharts/amcharts5` | `index.js` | Root, Theme, Legend, Tooltip, Label, Container |
 | XY charts | `@amcharts/amcharts5/xy` | `xy.js` | XYChart, axes, series |
 | Pie / Sliced | `@amcharts/amcharts5/percent` | `percent.js` | PieChart, SlicedChart, PieSeries, FunnelSeries, PyramidSeries, PictorialStackedSeries |
-| Map | `@amcharts/amcharts5/map` | `map.js` | MapChart, MapPolygonSeries, MapPointSeries, MapLineSeries |
+| Map | `@amcharts/amcharts5/map` | `map.js` | MapChart, MapPolygonSeries, MapPointSeries, MapLineSeries, MapSankeySeries |
 | Hierarchy | `@amcharts/amcharts5/hierarchy` | `hierarchy.js` | Treemap, VoronoiTreemap, ForceDirected, Sunburst, Pack, Partition, Tree |
 | Flow | `@amcharts/amcharts5/flow` | `flow.js` | Sankey, Chord, ChordDirected, ChordNonRibbon, ArcDiagram |
 | Radar | `@amcharts/amcharts5/radar` | `radar.js` | RadarChart, AxisRendererCircular, AxisRendererRadial |
@@ -73,7 +73,7 @@ Based on the chart type the user is building, read the relevant reference file f
 |-----------|------|
 | Line, area, bar, column, candlestick, OHLC, scatter, stacked charts | `references/xy.md` |
 | Pie, donut, semi-circle, funnel, pyramid, pictorial stacked charts | `references/pie.md` |
-| World map, country map, choropleth, bubble map, point map | `references/map.md` |
+| World map, country map, choropleth, bubble map, point map, map sankey | `references/map.md` |
 | Treemap, sunburst, force-directed, pack, partition, tree, org chart | `references/hierarchy.md` |
 | Sankey, chord, arc diagram, alluvial, flow visualization | `references/flow.md` |
 | Radar, spider, polar chart, gauge, speedometer, meter | `references/radar.md` |
@@ -638,6 +638,36 @@ onUnmounted(() => { root.dispose(); });
 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, {})`.
 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, ... })`.
+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`) 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. **Use `forceHidden` instead of `visible: false` when you need to guarantee something stays hidden** — amCharts internally manages `visible` on many elements (cursor lines, labels, ticks, tooltips, grid, etc.), toggling them on/off in response to user interaction or data changes. If you set `visible: false`, the library may set it back to `true`. `forceHidden: true` overrides all system visibility changes and keeps the element hidden regardless. Examples: `cursor.lineX.set("forceHidden", true)`, `yRenderer.labels.template.set("forceHidden", true)`, `xRenderer.grid.template.set("forceHidden", true)`. 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.
+31. **Globe rotation uses negative coordinates** — To center the globe (`geoOrthographic`) on a geographic point, set `rotationX` to **-longitude** and `rotationY` to **-latitude**. E.g., to center on Paris (48.86°N, 2.35°E): `chart.animate({ key: "rotationX", to: -2.35 }); chart.animate({ key: "rotationY", to: -48.86 });`. Using positive values rotates the globe the wrong way.
+32. **`positionOnLine` with multi-segment lines limits per-segment control** — `MapPointSeries` data items can animate along a line via `positionOnLine` (0→1). If the line has 3+ points (multi-segment), position 0.5 is the midpoint of the *entire* path, making per-segment effects (scaling at each segment midpoint, pausing between segments, etc.) difficult. For advanced per-segment animations, use **single-segment lines** (2 points each) and animate the bullet across them sequentially. E.g., instead of one line [A,B,C,D], create [A,B], [B,C], [C,D].
+33. **Do NOT exclude Antarctica (`exclude: ["AQ"]`) by default** — Many amCharts demos exclude Antarctica because they use Mercator projection where it appears disproportionately large. This is a demo-specific choice, not a best practice. Unless the user explicitly asks to exclude Antarctica, or references a demo that does so, keep Antarctica in the map. With non-Mercator projections (`geoNaturalEarth1`, `geoEqualEarth`, `geoOrthographic`, `geoEquirectangular`), Antarctica renders at a reasonable size.
+
+## Easing functions
+
+amCharts 5 easing functions live under `am5.ease`:
+
+```js
+// Base functions (ease-in by default):
+am5.ease.linear    am5.ease.quad     am5.ease.cubic
+am5.ease.sine      am5.ease.circle   am5.ease.exp
+am5.ease.pow       am5.ease.bounce   am5.ease.elastic
+
+// Modifiers — wrap a base function:
+am5.ease.out(am5.ease.cubic)      // ease-out
+am5.ease.inOut(am5.ease.cubic)    // ease in + out
+am5.ease.yoyo(am5.ease.cubic)     // animate to end, then back to start
+
+// Usage in .animate():
+sprite.animate({
+  key: "y", to: 100, duration: 400,
+  easing: am5.ease.out(am5.ease.cubic)
+});
+```
+
+**There is NO `am5.ease.in()`** — the base functions already ease-in by default.
 
 ## Validate generated code (if you can execute commands)
 

package/content/flow.md

@@ -42,6 +42,8 @@ Node IDs ("A", "B", etc.) are automatically extracted — you don't define nodes
 | `am5flow.ChordNonRibbon` | Chord with line links | Arc nodes + line links |
 | `am5flow.ArcDiagram` | Arc connections between linear nodes | Linear nodes + arc links |
 
+**Geographic Sankey (MapSankeySeries):** For Sankey-style flow bands drawn on a geographic map, use `am5map.MapSankeySeries` from the **map** package (not flow). See `references/map.md` → MapSankeySeries section.
+
 ## Sankey diagram
 
 ```js

package/content/map.md

@@ -63,8 +63,8 @@ const chart = root.container.children.push(
 // Polygon series (countries/regions)
 const polygonSeries = chart.series.push(
   am5map.MapPolygonSeries.new(root, {
-    geoJSON: am5geodata_worldLow,
-    exclude: ["AQ"]             // exclude Antarctica
+    geoJSON: am5geodata_worldLow
+    // exclude: ["AQ"]             // exclude Antarctica (only if needed)
     // include: ["US", "CA", "MX"]  // show only these
   })
 );
@@ -83,6 +83,11 @@ am5map.geoEqualEarth()        // equal-area
 am5map.geoEquirectangular()   // simple lat/long grid
 ```
 
+**IMPORTANT — Antarctica (`exclude: ["AQ"]`):**
+- Do NOT exclude Antarctica by default. Many amCharts demos exclude it because they use Mercator projection where Antarctica appears disproportionately large, but this is a demo-specific choice, not a best practice.
+- Only exclude Antarctica when the user explicitly asks for it, or when referencing a specific demo that excludes it.
+- With non-Mercator projections (`geoNaturalEarth1`, `geoEqualEarth`, `geoOrthographic`, `geoEquirectangular`) Antarctica renders at a reasonable size and should be included.
+
 ## Series types
 
 ### MapPolygonSeries (countries, regions)
@@ -91,7 +96,7 @@ am5map.geoEquirectangular()   // simple lat/long grid
 const polygonSeries = chart.series.push(
   am5map.MapPolygonSeries.new(root, {
     geoJSON: am5geodata_worldLow,
-    exclude: ["AQ"],
+    // exclude: ["AQ"],          // only if user requests Antarctica exclusion
     valueField: "value",        // for choropleth coloring
     calculateAggregates: true   // needed for heat rules
   })
@@ -209,6 +214,225 @@ lineSeries.pushDataItem({
 });
 ```
 
+### MapSankeySeries (geographic flow bands)
+
+Draws variable-width curved bands between geographic points on a map. Band thickness represents a numeric value — like a Sankey diagram projected onto a map. Extends `MapPolygonSeries` and generates actual GeoJSON polygon geometries, so bands follow the map projection during pan, zoom, and rotation.
+
+**Requires** a `MapPolygonSeries` to resolve country IDs to geographic centroids.
+
+```js
+// Create polygon series for countries (required for ID resolution)
+var polygonSeries = chart.series.push(
+  am5map.MapPolygonSeries.new(root, {
+    geoJSON: am5geodata_worldLow
+  })
+);
+
+// Create Sankey flow series
+var sankeySeries = chart.series.push(
+  am5map.MapSankeySeries.new(root, {
+    polygonSeries: polygonSeries,
+    maxWidth: 5               // max band width in geographic degrees
+  })
+);
+```
+
+#### Data format
+
+Each item needs `sourceId`, `targetId`, and `value`. IDs use ISO 3166-1 alpha-2 codes matching the geodata.
+
+```js
+sankeySeries.data.setAll([
+  { sourceId: "BR", targetId: "DE", value: 350 },
+  { sourceId: "BR", targetId: "US", value: 450 },
+  { sourceId: "DE", targetId: "FR", value: 150 },
+  { sourceId: "DE", targetId: "PL", value: 100 }
+]);
+```
+
+**Explicit coordinates** instead of polygon IDs:
+```js
+sankeySeries.data.setAll([
+  {
+    sourceLongitude: 2.35, sourceLatitude: 48.86,    // Paris
+    targetLongitude: -74.01, targetLatitude: 40.71,  // New York
+    value: 100
+  }
+]);
+```
+
+**Waypoints** — route flows through intermediate points:
+```js
+sankeySeries.data.setAll([
+  {
+    sourceId: "GB", targetId: "JP", value: 40,
+    waypoints: [
+      { longitude: 30, latitude: 65 },
+      { longitude: 90, latitude: 55 }
+    ]
+  }
+]);
+```
+
+#### Key settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `polygonSeries` | MapPolygonSeries | — | Reference series for resolving country IDs |
+| `maxWidth` | number | `5` | Maximum band width in geographic degrees |
+| `controlPointDistance` | number | `0.5` | Bezier control point distance (0–0.5) |
+| `controlPointDistanceSource` | number | — | Control point distance at source end |
+| `controlPointDistanceTarget` | number | — | Control point distance at target end |
+| `orientation` | string | `"horizontal"` | `"horizontal"` or `"vertical"` — controls departure/arrival direction |
+| `resolution` | number | `50` | Sample points per bezier segment |
+| `autoSort` | boolean | `true` | Sort bands by target latitude to prevent overlap |
+| `nodeType` | string | `"circle"` | `"circle"` or `"bar"` — endpoint node shape |
+| `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 |
+| `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 |
+| `sourceLatitudeField` | string | `"sourceLatitude"` | Data field for source latitude |
+| `targetLongitudeField` | string | `"targetLongitude"` | Data field for target longitude |
+| `targetLatitudeField` | string | `"targetLatitude"` | Data field for target latitude |
+| `waypointsField` | string | `"waypoints"` | Data field for waypoints array |
+
+#### Band appearance
+
+Configure flow bands via `mapPolygons.template`:
+
+```js
+sankeySeries.mapPolygons.template.setAll({
+  fill: am5.color(0xff6b35),
+  fillOpacity: 0.6,
+  strokeOpacity: 0,
+  tooltipText: "{sourceId} → {targetId}: {value}"
+});
+```
+
+Per-link control point overrides in data:
+```js
+sankeySeries.data.setAll([
+  { sourceId: "CN", targetId: "US", value: 300, controlPointDistance: 0.2 },
+  { sourceId: "CN", targetId: "DE", value: 200, controlPointDistanceSource: 0.4 }
+]);
+```
+
+#### Node configuration
+
+Each unique endpoint gets a node shape. Configure via `mapCircles.template`:
+
+```js
+sankeySeries.mapCircles.template.setAll({
+  fill: am5.color(0x8b5e3c),
+  fillOpacity: 0.9,
+  stroke: am5.color(0xffffff),
+  strokeWidth: 1.5
+});
+```
+
+Bar-style nodes (like traditional Sankey):
+```js
+var sankeySeries = chart.series.push(
+  am5map.MapSankeySeries.new(root, {
+    polygonSeries: polygonSeries,
+    nodeType: "bar",
+    nodeWidth: 1.5   // bar width in degrees
+  })
+);
+```
+
+#### Animated bullets along bands
+
+```js
+sankeySeries.bullets.push(function() {
+  return am5.Bullet.new(root, {
+    locationX: 0,
+    autoRotate: true,
+    sprite: am5.Circle.new(root, {
+      radius: 3,
+      fill: am5.color(0xffffff)
+    })
+  });
+});
+
+// Animate bullets along flow paths
+sankeySeries.events.on("datavalidated", function() {
+  am5.array.each(sankeySeries.dataItems, function(dataItem) {
+    var bullets = dataItem.bullets;
+    if (bullets) {
+      am5.array.each(bullets, function(bullet) {
+        bullet.animate({
+          key: "locationX",
+          from: 0,
+          to: 1,
+          duration: 3000,
+          easing: am5.ease.linear,
+          loops: Infinity
+        });
+      });
+    }
+  });
+});
+```
+
+Bullets automatically hide on the back side of the globe (orthographic projection).
+
+#### Multi-level flows
+
+The same country can be both target and source — incoming and outgoing bands share unified stacking at intermediate nodes:
+
+```js
+sankeySeries.data.setAll([
+  // Level 1: Producers → Hubs
+  { sourceId: "BR", targetId: "DE", value: 350 },
+  { sourceId: "VN", targetId: "DE", value: 200 },
+  // Level 2: Hubs → Consumers
+  { sourceId: "DE", targetId: "FR", value: 150 },
+  { sourceId: "DE", targetId: "PL", value: 100 }
+]);
+```
+
+### Animating bullets along lines (positionOnLine)
+
+`MapPointSeries` data items have a `positionOnLine` setting (0–1) that positions the point along a line. Combined with `lineDataItem` and `autoRotate`, this enables flight-path-style animations.
+
+```js
+// Create a point that follows a line
+var planeSeries = chart.series.push(am5map.MapPointSeries.new(root, {}));
+planeSeries.bullets.push(function() {
+  return am5.Bullet.new(root, {
+    sprite: am5.Graphics.new(root, {
+      svgPath: "m2,106h28l24,30h72l-44,-133h35l80,132h98c21,0 21,34 0,34l-98,0 -80,134h-35l43,-133h-71l-24,30h-28l15,-47",
+      scale: 0.04, centerY: am5.p50, centerX: am5.p50, fill: am5.color(0xff6600)
+    })
+  });
+});
+
+var plane = planeSeries.pushDataItem({
+  lineDataItem: lineDataItem,  // a MapLineSeries data item
+  positionOnLine: 0,
+  autoRotate: true
+});
+
+// Animate along the line
+plane.animate({ key: "positionOnLine", to: 1, duration: 3000,
+  easing: am5.ease.inOut(am5.ease.cubic) });
+
+// Track position for globe rotation or scale changes
+plane.on("positionOnLine", function(pos) {
+  // Center globe on plane's current position
+  chart.set("rotationX", -plane.get("longitude"));
+  chart.set("rotationY", -plane.get("latitude"));
+});
+```
+
+**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.
+- For advanced per-segment animations (e.g., scaling the bullet differently at the midpoint of each segment, or pausing between segments), use **single-segment lines** (2 points each) instead of one multi-segment line. This gives you full control: animate `positionOnLine` from 0→1 on each segment line sequentially, with independent timing, easing, and callbacks per segment.
+- Example: instead of one line with points [A, B, C, D], create three lines: [A,B], [B,C], [C,D] and animate the bullet across them one at a time.
+
 ## Zoom controls
 
 ```js
@@ -241,11 +465,15 @@ var chart = root.container.children.push(am5map.MapChart.new(root, {
   rotationY: -30       // initial latitude center
 }));
 
-// Rotate to a specific country
-chart.animate({ key: "rotationX", to: -2.35, duration: 1500, easing: am5.ease.out(am5.ease.cubic) });
-chart.animate({ key: "rotationY", to: -48.86, duration: 1500, easing: am5.ease.out(am5.ease.cubic) });
+// Rotate to a specific point (center it on the globe)
+// IMPORTANT: use NEGATIVE longitude and NEGATIVE latitude
+var paris = { latitude: 48.8566, longitude: 2.3522 };
+chart.animate({ key: "rotationX", to: -paris.longitude, duration: 1500, easing: am5.ease.out(am5.ease.cubic) });
+chart.animate({ key: "rotationY", to: -paris.latitude, duration: 1500, easing: am5.ease.out(am5.ease.cubic) });
 ```
 
+**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.
+
 ## GraticuleSeries (grid lines / ocean background)
 
 ```js
@@ -374,7 +602,6 @@ root.dispose();
 
     var polygonSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
       geoJSON: am5geodata_worldLow,
-      exclude: ["AQ"],
       valueField: "value",
       calculateAggregates: true
     }));
@@ -449,7 +676,7 @@ root.dispose();
       projection: am5map.geoMercator()
     }));
 
-    // Background polygons
+    // Background polygons — excluding Antarctica here because Mercator makes it disproportionately large
     var polygonSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
       geoJSON: am5geodata_worldLow,
       exclude: ["AQ"]
@@ -572,3 +799,339 @@ root.dispose();
 </body>
 </html>
 ```
+
+## Example 4: Globe with animated flight path (positionOnLine + globe rotation)
+
+Demonstrates: orthographic projection, single-segment lines for per-segment animation control, `positionOnLine` animation, globe auto-rotation to follow the plane, bullet scale animation, and city expand/shrink effects.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Globe Flight Path</title>
+  <script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/map.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/geodata/continentsLow.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>
+  <style>#chartdiv { width: 100%; height: 600px; background: #0a0a1a; }</style>
+</head>
+<body>
+  <div id="chartdiv"></div>
+  <script>
+    var root = am5.Root.new("chartdiv");
+    root.setThemes([am5themes_Animated.new(root)]);
+    var orange = am5.color(0xff6b35);
+    var cityColor = am5.color(0xcc4a1a);
+
+    var cities = [
+      { name: "London", latitude: 51.5074, longitude: -0.1278 },
+      { name: "Dubai", latitude: 25.2048, longitude: 55.2708 },
+      { name: "Singapore", latitude: 1.3521, longitude: 103.8198 },
+      { name: "Sydney", latitude: -33.8688, longitude: 151.2093 },
+      { name: "Tokyo", latitude: 35.6762, longitude: 139.6503 },
+      { name: "Honolulu", latitude: 21.3069, longitude: -157.8583 },
+      { name: "Los Angeles", latitude: 34.0522, longitude: -118.2437 },
+      { name: "São Paulo", latitude: -23.5505, longitude: -46.6333 },
+      { name: "New York", latitude: 40.7128, longitude: -74.006 },
+      { name: "London", latitude: 51.5074, longitude: -0.1278 }
+    ];
+
+    // Globe centered on first city (note: NEGATIVE lat/lon for rotation)
+    var chart = root.container.children.push(am5map.MapChart.new(root, {
+      panX: "rotateX",
+      panY: "rotateY",
+      projection: am5map.geoOrthographic(),
+      rotationX: -cities[0].longitude,
+      rotationY: -cities[0].latitude
+    }));
+
+    // Ocean background
+    var bgSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {}));
+    bgSeries.mapPolygons.template.setAll({
+      fill: am5.color(0x1a1a2e), fillOpacity: 1, strokeOpacity: 0
+    });
+    bgSeries.data.push({ geometry: am5map.getGeoRectangle(90, 180, -90, -180) });
+
+    // Graticule
+    var graticuleSeries = chart.series.push(am5map.GraticuleSeries.new(root, {}));
+    graticuleSeries.mapLines.template.setAll({
+      stroke: am5.color(0x4a4a65), strokeOpacity: 0.5, strokeWidth: 0.8
+    });
+
+    // Continents
+    var polygonSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
+      geoJSON: am5geodata_continentsLow
+    }));
+    polygonSeries.mapPolygons.template.setAll({
+      fill: am5.color(0x2a2a45), stroke: am5.color(0x3a3a55),
+      strokeWidth: 0.5, strokeOpacity: 0.6
+    });
+
+    // Dashed route lines — one per segment for animation control
+    var lineSeries = chart.series.push(am5map.MapLineSeries.new(root, {}));
+    lineSeries.mapLines.template.setAll({
+      stroke: orange, strokeOpacity: 0.35, strokeWidth: 1.5, strokeDasharray: [3, 3]
+    });
+
+    // City points with pulse + label
+    var pointSeries = chart.series.push(am5map.MapPointSeries.new(root, {}));
+    pointSeries.bullets.push(function () {
+      var container = am5.Container.new(root, {});
+      container.children.push(am5.Circle.new(root, {
+        radius: 3.5, fill: cityColor, fillOpacity: 0.9,
+        stroke: orange, strokeWidth: 4, strokeOpacity: 0
+      }));
+      container.children.push(am5.Label.new(root, {
+        text: "{name}", fill: am5.color(0xffffff), fontSize: 11,
+        fontWeight: "600", centerX: am5.p50, centerY: am5.p100,
+        dy: -8, opacity: 0, populateText: true
+      }));
+      return am5.Bullet.new(root, { sprite: container });
+    });
+
+    var pointsToConnect = [];
+    for (var i = 0; i < cities.length; i++) {
+      if (i === cities.length - 1) {
+        pointsToConnect.push(pointsToConnect[0]); // loop back
+      } else {
+        pointsToConnect.push(pointSeries.pushDataItem({
+          latitude: cities[i].latitude, longitude: cities[i].longitude,
+          name: cities[i].name
+        }));
+      }
+    }
+
+    // Single-segment lines (one per city pair) for per-segment control
+    var segmentLines = [];
+    var numSegments = cities.length - 1;
+    for (var i = 0; i < numSegments; i++) {
+      segmentLines.push(lineSeries.pushDataItem({
+        pointsToConnect: [pointsToConnect[i], pointsToConnect[i + 1]]
+      }));
+    }
+
+    // Plane series — one per segment, all hidden initially
+    var planeSeries = chart.series.push(am5map.MapPointSeries.new(root, {}));
+    planeSeries.bullets.push(function () {
+      return am5.Bullet.new(root, {
+        sprite: am5.Graphics.new(root, {
+          svgPath: "m2,106h28l24,30h72l-44,-133h35l80,132h98c21,0 21,34 0,34l-98,0 -80,134h-35l43,-133h-71l-24,30h-28l15,-47",
+          scale: 0.04, centerY: am5.p50, centerX: am5.p50,
+          fill: orange, forceHidden: true
+        })
+      });
+    });
+
+    var planes = [];
+    for (var i = 0; i < numSegments; i++) {
+      planes.push(planeSeries.pushDataItem({
+        lineDataItem: segmentLines[i], positionOnLine: 0, autoRotate: true
+      }));
+    }
+
+    var baseScale = 0.04, peakScale = 0.065;
+
+    // Haversine distance for proportional timing
+    function haversine(lat1, lon1, lat2, lon2) {
+      var R = 6371, dLat = (lat2 - lat1) * Math.PI / 180,
+          dLon = (lon2 - lon1) * Math.PI / 180;
+      var a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
+        Math.sin(dLon / 2) * Math.sin(dLon / 2);
+      return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    }
+
+    var msPerKm = 0.4;
+    var segDurations = [];
+    for (var i = 0; i < numSegments; i++) {
+      var d = haversine(cities[i].latitude, cities[i].longitude,
+                        cities[i + 1].latitude, cities[i + 1].longitude);
+      segDurations.push(Math.max(800, Math.round(d * msPerKm)));
+    }
+
+    var activeCityIdx = -1;
+
+    function expandCity(idx) {
+      var di = pointsToConnect[idx];
+      if (!di || !di.bullets || !di.bullets[0]) return;
+      var container = di.bullets[0].get("sprite");
+      var dot = container.children.getIndex(0);
+      var label = container.children.getIndex(1);
+      activeCityIdx = idx;
+      dot.animate({ key: "radius", to: 14, duration: 400, easing: am5.ease.out(am5.ease.cubic) });
+      dot.animate({ key: "fillOpacity", to: 0, duration: 400, easing: am5.ease.out(am5.ease.cubic) });
+      dot.animate({ key: "strokeOpacity", to: 1, duration: 400, easing: am5.ease.out(am5.ease.cubic) });
+      label.setAll({ opacity: 0, dy: 0 });
+      label.animate({ key: "opacity", to: 1, duration: 300, easing: am5.ease.out(am5.ease.cubic) });
+      label.animate({ key: "dy", to: -10, duration: 300, easing: am5.ease.out(am5.ease.cubic) });
+    }
+
+    function shrinkCity(idx) {
+      var di = pointsToConnect[idx];
+      if (!di || !di.bullets || !di.bullets[0]) return;
+      var container = di.bullets[0].get("sprite");
+      var dot = container.children.getIndex(0);
+      var label = container.children.getIndex(1);
+      dot.animate({ key: "radius", to: 3.5, duration: 500, easing: am5.ease.cubic });
+      dot.animate({ key: "fillOpacity", to: 0.9, duration: 500, easing: am5.ease.cubic });
+      dot.animate({ key: "strokeOpacity", to: 0, duration: 500, easing: am5.ease.cubic });
+      label.animate({ key: "opacity", to: 0, duration: 400, easing: am5.ease.cubic });
+      activeCityIdx = -1;
+    }
+
+    var lastRotation = null;
+    var activeFlightDisposer = null;
+
+    function startFlight(plane, sprite, idx) {
+      if (activeCityIdx >= 0) shrinkCity(activeCityIdx);
+      var nextIdx = (idx + 1) % numSegments;
+      var expanded = false;
+
+      if (activeFlightDisposer) { activeFlightDisposer.dispose(); activeFlightDisposer = null; }
+
+      // Track position: rotate globe + scale bullet + expand destination city early
+      activeFlightDisposer = plane.on("positionOnLine", function (pos) {
+        chart.set("rotationX", -plane.get("longitude"));
+        chart.set("rotationY", -plane.get("latitude"));
+        var s = baseScale + (peakScale - baseScale) * Math.sin(pos * Math.PI);
+        if (plane.bullets && plane.bullets[0]) {
+          plane.bullets[0].get("sprite").set("scale", s);
+        }
+        if (!expanded && pos >= 0.85) { expanded = true; expandCity(nextIdx); }
+      });
+
+      var anim = plane.animate({
+        key: "positionOnLine", to: 1, duration: segDurations[idx],
+        easing: am5.ease.inOut(am5.ease.cubic)
+      });
+      anim.events.on("stopped", function () {
+        lastRotation = sprite.get("rotation", 0);
+        sprite.set("forceHidden", true);
+        flySegment(nextIdx);
+      });
+    }
+
+    function flySegment(idx) {
+      var plane = planes[idx];
+      var sprite = plane.bullets[0].get("sprite");
+      plane.set("positionOnLine", 0);
+      sprite.set("forceHidden", false);
+
+      if (lastRotation === null) {
+        sprite.set("opacity", 0);
+        sprite.animate({ key: "opacity", to: 1, duration: 400, easing: am5.ease.out(am5.ease.cubic) });
+      }
+
+      if (lastRotation !== null) {
+        var targetRotation = sprite.get("rotation", 0);
+        plane.set("autoRotate", false);
+        sprite.set("rotation", lastRotation);
+        var diff = targetRotation - lastRotation;
+        while (diff > 180) diff -= 360;
+        while (diff < -180) diff += 360;
+        var rotAnim = sprite.animate({
+          key: "rotation", to: lastRotation + diff, duration: 500,
+          easing: am5.ease.out(am5.ease.cubic)
+        });
+        rotAnim.events.on("stopped", function () {
+          plane.set("autoRotate", true);
+          startFlight(plane, sprite, idx);
+        });
+      } else {
+        startFlight(plane, sprite, idx);
+      }
+    }
+
+    chart.appear(1000, 100);
+    expandCity(0);
+    setTimeout(function () { flySegment(0); }, 1500);
+  </script>
+</body>
+</html>
+```
+
+## Example 5: Map Sankey — trade flows between countries
+
+Demonstrates: `MapSankeySeries` with geographic flow bands, node circles, tooltips, and multi-level flows.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Map Sankey — Trade Flows</title>
+  <script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/map.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/geodata/worldLow.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>
+  <style>#chartdiv { width: 100%; height: 600px; }</style>
+</head>
+<body>
+  <div id="chartdiv"></div>
+  <script>
+    var root = am5.Root.new("chartdiv");
+    root.setThemes([am5themes_Animated.new(root)]);
+
+    var chart = root.container.children.push(am5map.MapChart.new(root, {
+      panX: "rotateX",
+      panY: "translateY",
+      projection: am5map.geoNaturalEarth1()
+    }));
+
+    // Background countries
+    var polygonSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
+      geoJSON: am5geodata_worldLow
+    }));
+    polygonSeries.mapPolygons.template.setAll({
+      fill: am5.color(0xdddddd),
+      stroke: am5.color(0xffffff),
+      strokeWidth: 0.5
+    });
+
+    // Sankey flow series
+    var sankeySeries = chart.series.push(am5map.MapSankeySeries.new(root, {
+      polygonSeries: polygonSeries,
+      maxWidth: 4,
+      controlPointDistance: 0.4,
+      autoSort: true
+    }));
+
+    // Band appearance
+    sankeySeries.mapPolygons.template.setAll({
+      fill: am5.color(0xff6b35),
+      fillOpacity: 0.5,
+      strokeOpacity: 0,
+      tooltipText: "{sourceId} → {targetId}: {value}B"
+    });
+
+    // Node appearance
+    sankeySeries.mapCircles.template.setAll({
+      fill: am5.color(0x8b5e3c),
+      fillOpacity: 0.9,
+      stroke: am5.color(0xffffff),
+      strokeWidth: 1.5
+    });
+
+    // Multi-level trade data
+    sankeySeries.data.setAll([
+      // Producers → Trade hubs
+      { sourceId: "BR", targetId: "DE", value: 350 },
+      { sourceId: "BR", targetId: "US", value: 450 },
+      { sourceId: "CN", targetId: "DE", value: 500 },
+      { sourceId: "CN", targetId: "US", value: 600 },
+      { sourceId: "AU", targetId: "JP", value: 200 },
+      { sourceId: "AU", targetId: "CN", value: 300 },
+      // Hubs → Consumers
+      { sourceId: "DE", targetId: "FR", value: 250 },
+      { sourceId: "DE", targetId: "GB", value: 300 },
+      { sourceId: "US", targetId: "CA", value: 400 },
+      { sourceId: "JP", targetId: "KR", value: 100 }
+    ]);
+
+    chart.set("zoomControl", am5map.ZoomControl.new(root, {}));
+    chart.appear(1000, 100);
+  </script>
+</body>
+</html>
+```

package/content/timeline.md

@@ -183,10 +183,26 @@ const series = chart.series.push(
 
 ## Cursor
 
+Timeline charts use `CurveCursor`, NOT `XYCursor`. It follows the curve path.
+
 ```js
-chart.set("cursor", am5timeline.CurveCursor.new(root, {}));
+// Create cursor — must use CurveCursor for timeline charts
+var cursor = chart.set("cursor", am5timeline.CurveCursor.new(root, {
+  xAxis: xAxis,           // recommended — enables axis-based snapping
+  yAxis: yAxis,
+  behavior: "none"         // "zoomX", "zoomY", "zoomXY", "selectX", etc.
+}));
+
+// Hide crosshair lines (forceHidden stays hidden; visible:false can be overridden by the library)
+cursor.lineX.set("forceHidden", true);
+cursor.lineY.set("forceHidden", true);
+
+// Snap tooltips to data points — set on the SERIES, not the cursor
+series.set("snapTooltip", true);
 ```
 
+**Do NOT** pass `lineX`/`lineY` as constructor options. Always access `cursor.lineX` / `cursor.lineY` after creation.
+
 ## Bullets
 
 Bullets on timeline charts work the same as XY charts:

package/content/xy.md

@@ -358,15 +358,21 @@ const cursor = chart.set("cursor", am5xy.XYCursor.new(root, {
   xAxis: xAxis,           // optional: snap to axis
 }));
 
-// Customize appearance:
+// Customize appearance (always access cursor.lineX/lineY AFTER creation):
 cursor.lineX.setAll({ stroke: am5.color(0x000000), strokeDasharray: [2, 2] });
-cursor.lineY.setAll({ visible: false });
+
+// Hide a cursor line — use forceHidden (NOT visible:false):
+cursor.lineY.set("forceHidden", true);
 
 // Snap tooltips to series data points:
 series.set("tooltip", am5.Tooltip.new(root, { labelText: "{valueY}" }));
 chart.set("cursor", am5xy.XYCursor.new(root, { snapToSeries: [series] }));
 ```
 
+**Do NOT** pass `lineX`/`lineY` as constructor options to `XYCursor.new()`. Always access `cursor.lineX` / `cursor.lineY` after creation.
+
+For timeline charts, use `am5timeline.CurveCursor` instead — see `references/timeline.md`.
+
 ## Scrollbar
 
 Enables zooming/panning via scrollbar. Can optionally include a preview chart.

package/extended/charts/xy-chart/cursor.md

@@ -292,9 +292,7 @@ cursor.lineX.setAll({
   strokeDasharray: \[\]
 });
 
-cursor.lineY.setAll({
-  visible: false
-});
+cursor.lineY.set("forceHidden", true);
 
 let cursor = chart.get("cursor");
 
@@ -304,11 +302,9 @@ cursor.lineX.setAll({
   strokeDasharray: \[\]
 });
 
-cursor.lineY.setAll({
-  visible: false
-});
+cursor.lineY.set("forceHidden", true);
 
-The above will apply color, remove dashing, and make vertical line thicker, while completely hide horizontal line.
+The above will apply color, remove dashing, and make vertical line thicker, while completely hiding the horizontal line. Use `forceHidden: true` rather than `visible: false` to hide cursor lines — the cursor internally sets `visible: true` when the pointer enters the plot area, so `visible: false` gets overridden. `forceHidden` prevents this system behavior.
 
 ### Selection
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amcharts/amcharts5-mcp",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "mcpName": "io.github.amcharts/amcharts5",
   "description": "On-demand access to amCharts 5 docs, code examples, and API reference",
   "type": "module",