@pixerate/editor 0.162.0 → 0.163.0

package/dist/chart/index.js

@@ -2,12 +2,19 @@ import {
   CATEGORY_REF,
   CHART_UPDATE_PROPERTIES,
   HEIGHT,
+  REFERENCE_BAND_PATCH,
+  REFERENCE_BAND_PROPS,
+  REFERENCE_INDEX,
+  REFERENCE_LINE_PATCH,
+  REFERENCE_LINE_PROPS,
   SERIES_PROPS,
   SERIES_REF,
+  TREE_DEFS,
+  TREE_PATH,
   TRENDLINE_PROPS,
   VALUE,
   WIDTH
-} from "../chunk-EVPZ5IKN.js";
+} from "../chunk-5FNGLV2D.js";
 import {
   CHART_OOXML_CONTENT_TYPE,
   CHART_OOXML_NS,
@@ -15,7 +22,7 @@ import {
   chartFormatToCode,
   chartFromOoxml,
   chartToOoxml
-} from "../chunk-7CKPUUN4.js";
+} from "../chunk-POR54B55.js";
 import {
   CHART_COLOR_SCHEMES,
   CHART_LAYOUT_PRESETS,
@@ -37,7 +44,7 @@ import {
   monochromeChartPalette,
   sparklineToSvg,
   summarizeChart
-} from "../chunk-XDCFJEU7.js";
+} from "../chunk-SZA42R4N.js";
 import {
   CHART_DATE_STEPS,
   MAX_CHART_DATA_LABELS,
@@ -74,9 +81,10 @@ import {
   sameChartSelection,
   snapChartValue,
   stepDecimals,
+  suggestChartReferences,
   summarizeChartSeries,
   trendNumberText
-} from "../chunk-DTSTNRPH.js";
+} from "../chunk-Z4P2RBMJ.js";
 import {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -86,11 +94,14 @@ import {
   CHART_ERROR_BAR_TYPES,
   CHART_LABEL_POSITIONS,
   CHART_LEGEND_POSITIONS,
+  CHART_LIKERT_NEUTRALS,
+  CHART_LIKERT_SORTS,
   CHART_MARKERS,
   CHART_NUMBER_STYLES,
   CHART_ORIENTATIONS,
   CHART_PALETTE_SHADES,
   CHART_RADAR_GRATICULES,
+  CHART_REFERENCE_AXES,
   CHART_SERIES_TYPES,
   CHART_STACKINGS,
   CHART_TRENDLINE_TYPES,
@@ -99,6 +110,9 @@ import {
   CSS_VARIABLE_CHART_THEME,
   DEFAULT_CHART_PALETTE,
   DEFAULT_CHART_THEME,
+  MAX_CHART_TREE_DEPTH,
+  MAX_CHART_TREE_NODES,
+  addChartTreeRow,
   chartColorDistance,
   chartColorInputValue,
   chartColorsByCategory,
@@ -108,6 +122,7 @@ import {
   chartErrorAmounts,
   chartErrorBarsOfType,
   chartFamily,
+  chartLikertColor,
   chartLuminance,
   chartPointColor,
   chartRgbToHex,
@@ -115,30 +130,47 @@ import {
   chartSeriesColor,
   chartSeriesType,
   chartSliceColor,
+  chartSpecColorsByCategory,
   chartTextOn,
+  chartTreeColumnLabels,
+  chartTreeDepth,
+  chartTreeFromRows,
+  chartTreeFromSeries,
+  chartTreeFromTable,
+  chartTreeToRows,
+  chartTreeTotal,
+  chartVariesColors,
   checkChartColors,
   cloneChartSeries,
   cloneChartSpec,
+  cloneChartTree,
   createChartSpec,
   cyclePaletteColor,
   defaultChartAxis,
   defaultChartErrorBarValue,
   describeChartErrorBars,
+  findChartTreeNode,
   formatChartAmountList,
   isCartesianChart,
   isXyChart,
   normalizeChartAxis,
   normalizeChartErrorBars,
+  normalizeChartReferenceBand,
+  normalizeChartReferenceLine,
   normalizeChartSpec,
+  normalizeChartTree,
   normalizeChartTrendline,
   normalizeChartValues,
   parseChartAmountList,
   parseChartColor,
   parseChartValue,
+  removeChartTreeRow,
+  setChartTreeRowName,
+  setChartTreeRowValue,
   shadeChartColor,
   simulateChartVision,
   uniqueChartSeriesId
-} from "../chunk-HLOKB7WW.js";
+} from "../chunk-3NEZJCBY.js";
 import "../chunk-II2WIF5Z.js";
 import {
   parseCsv
@@ -367,6 +399,7 @@ function recommendForShape(shape) {
         add("donut", "Donut", "Shares of a whole with the total in the middle.");
         if (shape.points >= 5) add("treemap", "Treemap", "Compares many shares by area.");
         add("funnel", "Funnel", "Shows stages that narrow down.");
+        add("parliament", "Parliament", "Seats or votes per group, with the majority line.");
       }
       add("line", "Line", "Shows the values in order.");
     }
@@ -378,11 +411,13 @@ function recommendForShape(shape) {
     add("area", "Area", "Emphasises volume.");
     add("bar", "Stacked column", "Shows how the series add up.", "stacked");
   } else {
+    if (shape.series === 2 && shape.labelColumn) add("slope", "Slope", "Two columns per item: shows what rose and what fell between them.");
     add("bar", "Column", "Several series: clustered columns compare them per category.");
     add("bar", "Bar", "Horizontal bars fit long category names.");
     add("bar", "Stacked column", "Shows how the series add up.", "stacked");
     add("line", "Line", "Shows the series in order.");
     if (shape.points >= 3 && shape.series <= 6) add("radar", "Radar", "Compares several measures across the series.");
+    if (shape.nonNegative && shape.series >= 3 && shape.series <= 7) add("likert", "Likert", "Survey answers per question (columns from most negative to most positive): shows agreement against disagreement.");
   }
   return out;
 }
@@ -447,7 +482,7 @@ function createChartCommands(controller, options = {}) {
       id: `${prefix}update`,
       label: "Change Chart\u2026",
       keywords: ["chart", "title", "axis", "legend", "stack", "style", "format", "type"],
-      description: 'Changes chart presentation as one undo step: type, titles, axes (xAxis = categories, yAxis = values, yAxis2 = secondary values; reverse, and scale "log" on value axes), legend, stacking, orientation, curve, points, data labels, palette, donut hole, bar spacing, histogram bins, waterfall total, or radar rings and grid shape. Invalid values change nothing and return why.',
+      description: 'Changes chart presentation as one undo step: type, titles, axes (xAxis = categories, yAxis = values, yAxis2 = secondary values; reverse, and scale "log" on value axes), legend, stacking, orientation, curve, points, data labels, palette, donut hole, bar spacing, histogram bins, waterfall total, or radar rings and grid shape, note, highlight, reference lines and bands, or colour by category (varyColors). Invalid values change nothing and return why.',
       params: object(CHART_UPDATE_PROPERTIES),
       run: (_ctx, params) => {
         check(controller.update(params));
@@ -529,7 +564,11 @@ function createChartCommands(controller, options = {}) {
       keywords: ["chart", "category", "row", "label"],
       description: "Inserts a category (gaps in every series) at `at` (default: the end).",
       params: object({ label: { type: "string", description: "Category label (default: its number)." }, at: { type: "integer", minimum: 0, description: "Index to insert at (default: the end)." } }),
-      run: (_ctx, params = {}) => controller.addCategory(params?.label, { at: params?.at })
+      run: (_ctx, params = {}) => {
+        const result = controller.addCategory(params?.label, { at: params?.at });
+        check(result);
+        return result;
+      }
     },
     {
       ...base,
@@ -570,6 +609,197 @@ function createChartCommands(controller, options = {}) {
         return { trendlines: controller.getSeries(resolveSeries(params.series).id)?.trendlines ?? [] };
       }
     },
+    {
+      ...base,
+      id: `${prefix}addReferenceLine`,
+      label: "Add Reference Line\u2026",
+      keywords: ["chart", "target", "goal", "threshold", "average", "reference", "line", "annotation"],
+      description: "Draws a dashed line across the plot at one value (a target, floor or average). Returns its index.",
+      params: object(REFERENCE_LINE_PROPS, ["value"]),
+      run: (_ctx, params) => {
+        const result = controller.addReferenceLine(params);
+        check(result);
+        return { index: result.index, referenceLines: controller.getSpec().referenceLines };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}updateReferenceLine`,
+      label: "Change Reference Line\u2026",
+      keywords: ["chart", "target", "reference", "line", "annotation"],
+      description: "Changes a reference line by index; label, axis and color take null to remove them.",
+      params: object({ index: REFERENCE_INDEX("Reference line"), ...REFERENCE_LINE_PATCH }, ["index"]),
+      run: (_ctx, params) => {
+        const { index, ...patch } = params;
+        check(controller.updateReferenceLine(index, patch));
+        return { referenceLine: controller.getSpec().referenceLines[index] };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}removeReferenceLine`,
+      label: "Delete Reference Line",
+      keywords: ["chart", "target", "reference", "line", "remove"],
+      description: "Deletes a reference line by index.",
+      params: object({ index: REFERENCE_INDEX("Reference line") }, ["index"]),
+      run: (_ctx, params) => {
+        check(controller.removeReferenceLine(params.index));
+        return { referenceLines: controller.getSpec().referenceLines };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}addReferenceBand`,
+      label: "Add Reference Band\u2026",
+      keywords: ["chart", "target", "range", "band", "reference", "shade", "annotation"],
+      description: "Shades a band across the plot between two values (a target or normal range). Returns its index.",
+      params: object(REFERENCE_BAND_PROPS, ["from", "to"]),
+      run: (_ctx, params) => {
+        const result = controller.addReferenceBand(params);
+        check(result);
+        return { index: result.index, referenceBands: controller.getSpec().referenceBands };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}updateReferenceBand`,
+      label: "Change Reference Band\u2026",
+      keywords: ["chart", "range", "band", "reference", "annotation"],
+      description: "Changes a reference band by index; label, axis and color take null to remove them.",
+      params: object({ index: REFERENCE_INDEX("Reference band"), ...REFERENCE_BAND_PATCH }, ["index"]),
+      run: (_ctx, params) => {
+        const { index, ...patch } = params;
+        check(controller.updateReferenceBand(index, patch));
+        return { referenceBand: controller.getSpec().referenceBands[index] };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}removeReferenceBand`,
+      label: "Delete Reference Band",
+      keywords: ["chart", "range", "band", "reference", "remove"],
+      description: "Deletes a reference band by index.",
+      params: object({ index: REFERENCE_INDEX("Reference band") }, ["index"]),
+      run: (_ctx, params) => {
+        check(controller.removeReferenceBand(params.index));
+        return { referenceBands: controller.getSpec().referenceBands };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setCallout`,
+      label: "Pin Label to Point\u2026",
+      keywords: ["chart", "callout", "annotation", "label", "note", "point"],
+      description: 'Pins a short label to one bar or point (label null or "" removes it).',
+      params: object({ series: SERIES_REF, category: CATEGORY_REF, label: { type: ["string", "null"], description: "The label (a few words), or null to remove it." } }, ["series", "category", "label"]),
+      run: (_ctx, params) => {
+        const series = resolveSeries(params.series);
+        const index = resolveCategory(params.category);
+        check(controller.setCallout(series.id, index, params.label));
+        return { series: series.id, index, label: controller.getSeries(series.id)?.callouts?.[index] ?? null };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}highlight`,
+      label: "Highlight\u2026",
+      keywords: ["chart", "highlight", "emphasise", "emphasize", "focus", "mute", "dim"],
+      description: "Draws the named categories and series normally and mutes the rest ([] shows everything). Unknown names change nothing.",
+      params: object({ names: { type: "array", items: { type: "string" }, description: "Category labels and / or series names or ids; [] clears the highlight." } }, ["names"]),
+      run: (_ctx, params) => {
+        const result = controller.setHighlight(params.names);
+        check(result);
+        const { categories, series } = result;
+        return { highlight: controller.getSpec().highlight, categories, series };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setTree`,
+      label: "Replace Grouped Data\u2026",
+      keywords: ["chart", "tree", "hierarchy", "groups", "treemap", "sunburst", "nested"],
+      description: "Replaces the data with groups of items (a tree) for treemaps and sunbursts; [] goes back to plain data.",
+      params: { type: "object", properties: { tree: { type: "array", items: { $ref: "#/$defs/chartTreeNode" }, description: "The top-level nodes; [] removes the grouping." } }, required: ["tree"], additionalProperties: false, $defs: TREE_DEFS },
+      run: (_ctx, params) => {
+        check(controller.setTree(params.tree));
+        return { groups: controller.getSpec().tree.map((n) => ({ name: n.name, total: chartTreeTotal(n) })) };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}importTreeCsv`,
+      label: "Import Grouped Data from CSV\u2026",
+      keywords: ["chart", "tree", "hierarchy", "csv", "import", "treemap", "sunburst"],
+      description: "Replaces the data with grouped data from CSV / TSV: names in every column but the last (group, \u2026, item), the value in the last.",
+      params: object(
+        {
+          csv: { type: "string", description: "CSV or TSV text." },
+          header: { type: ["boolean", "string"], enum: [true, false, "auto"], description: "The first row holds column names (default auto)." }
+        },
+        ["csv"]
+      ),
+      run: (_ctx, params) => {
+        check(controller.importTreeTable(parseCsv(params.csv, { delimiter: params.csv.includes("	") ? "	" : "," }), { header: params.header }));
+        return { tree: controller.getSpec().tree };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}addTreeNode`,
+      label: "Add Item or Group\u2026",
+      keywords: ["chart", "tree", "group", "item", "add", "treemap", "sunburst"],
+      description: "Adds an item or group under a group of the grouped data ([] for the top level). Returns its path.",
+      params: {
+        type: "object",
+        properties: {
+          parent: { type: "array", items: { type: "string" }, description: "Path of the group to add to; [] or omitted for the top level." },
+          node: { $ref: "#/$defs/chartTreeNode", description: "The item or group to add." },
+          at: { type: "integer", minimum: 0, description: "Position among its siblings (default: the end)." }
+        },
+        required: ["node"],
+        additionalProperties: false,
+        $defs: TREE_DEFS
+      },
+      run: (_ctx, params) => {
+        const result = controller.addTreeNode(params.parent ?? [], params.node, { at: params.at });
+        check(result);
+        return { path: result.path };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}updateTreeNode`,
+      label: "Change Item or Group\u2026",
+      keywords: ["chart", "tree", "group", "item", "rename", "value"],
+      description: "Renames a node, sets an item's value or sets a node's colour (null for the palette).",
+      params: object(
+        {
+          path: TREE_PATH,
+          name: { type: "string", description: "New name." },
+          value: { type: "number", minimum: 0, description: "Items only: the new amount." },
+          color: { type: ["string", "null"], description: "CSS colour, or null for the palette colour." }
+        },
+        ["path"]
+      ),
+      run: (_ctx, params) => {
+        const { path, ...patch } = params;
+        const result = controller.updateTreeNode(path, patch);
+        check(result);
+        return { path: result.path };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}removeTreeNode`,
+      label: "Delete Item or Group",
+      keywords: ["chart", "tree", "group", "item", "remove", "delete"],
+      description: "Deletes a node of the grouped data with everything under it.",
+      params: object({ path: TREE_PATH }, ["path"]),
+      run: (_ctx, params) => {
+        check(controller.removeTreeNode(params.path));
+        return { groups: controller.getSpec().tree.map((n) => ({ name: n.name, total: chartTreeTotal(n) })) };
+      }
+    },
     {
       ...base,
       id: `${prefix}applyPreset`,
@@ -683,7 +913,7 @@ function createChartCommands(controller, options = {}) {
       run: () => {
         const s = controller.getSpec();
         const visible = s.series.filter((x) => !x.hidden);
-        const colors = chartColorsByCategory(s.type) ? s.categories.map((_, i) => visible[0]?.pointColors?.[i] || chartSliceColor(s, i)) : visible.map((x) => chartSeriesColor(s, s.series.indexOf(x)));
+        const colors = chartSpecColorsByCategory(s) ? s.categories.map((_, i) => visible[0]?.pointColors?.[i] || chartSliceColor(s, i)) : visible.map((x) => chartSeriesColor(s, s.series.indexOf(x)));
         return { colors, ...checkChartColors(colors) };
       }
     },
@@ -1131,6 +1361,11 @@ function planChartToolPlayback(tool, args) {
       if (args.kind === "point" && typeof args.series === "string" && args.category !== void 0) return click(chartPointRef(args.series, args.category));
       return typeof args.kind === "string" && args.kind !== "none" ? click(control(args.kind)) : null;
     case "set_chart_data":
+    case "set_chart_tree":
+    case "import_chart_tree_csv":
+    case "add_chart_tree_node":
+    case "update_chart_tree_node":
+    case "remove_chart_tree_node":
     case "import_chart_csv":
     case "import_chart_mermaid":
     case "import_chart_ooxml":
@@ -1144,6 +1379,19 @@ function planChartToolPlayback(tool, args) {
     case "add_chart_trendline":
     case "remove_chart_trendline":
       return click(control("trendline.add"));
+    case "add_chart_reference_line":
+    case "update_chart_reference_line":
+    case "remove_chart_reference_line":
+      return click(control("referenceLine.add"));
+    case "add_chart_reference_band":
+    case "update_chart_reference_band":
+    case "remove_chart_reference_band":
+      return click(control("referenceBand.add"));
+    case "set_chart_callout":
+      if (typeof args.series === "string" && (typeof args.category === "string" || typeof args.category === "number")) return [...click(chartPointRef(args.series, args.category)), ...click(control("series.callout"))];
+      return click(control("series.callout"));
+    case "highlight_chart":
+      return click(control("highlight"));
     case "render_chart":
       return [{ type: "target", ref: { kind: "action", id: "download-png" } }];
     case "undo_chart":
@@ -1203,11 +1451,17 @@ function createChartToolProvider(controller, options = {}) {
     return index;
   };
   const table = () => chartDataToTable(spec());
+  const treeTable = () => {
+    const rows = chartTreeToRows(spec().tree);
+    const depth = chartTreeDepth(spec().tree);
+    return [[...Array.from({ length: depth }, (_, k) => k === 0 ? "Group" : k === depth - 1 ? "Item" : `Level ${k + 1}`), "Value"], ...rows.map((r) => [...r.path, ...Array(depth - r.path.length).fill(""), r.value])];
+  };
+  const treeSummary = () => ({ tree: spec().tree, groups: spec().tree.map((n) => ({ name: n.name, total: chartTreeTotal(n) })), depth: chartTreeDepth(spec().tree) });
   const Parser = () => options.DOMParser ?? globalThis.DOMParser;
   const getChart = {
     name: "get_chart",
     title: "Read the chart",
-    description: "Returns the chart spec (type, titles, axes, legend, series with ids and settings), its data as a table (header row of series names, then one row per category), the current selection, and a summary at the given size: per-series min / max / mean / trend, the axes as drawn, layout warnings (hidden labels, thinned lines), a colour check and a plain-language description. Use the series ids and category indexes it returns with the write tools.",
+    description: "Returns the chart spec (type, titles, axes, legend, series with ids and settings), its data as a table (header row of series names, then one row per category), grouped data as treeTable (path of names to each item, then its value) when the chart has a tree, the current selection, and a summary at the given size: per-series min / max / mean / trend, the axes as drawn, layout warnings (hidden labels, thinned lines), a colour check and a plain-language description. Use the series ids and category indexes it returns with the write tools.",
     inputSchema: { type: "object", properties: { width: WIDTH, height: HEIGHT }, additionalProperties: false },
     annotations: { title: "Read the chart", ...READ },
     handler: ({ width = size.width, height = size.height }) => {
@@ -1217,6 +1471,7 @@ function createChartToolProvider(controller, options = {}) {
         table: table(),
         selection: controller.getState().selection,
         summary: summarizeChart(controller.toJSON(), { width, height }),
+        ...spec().tree.length ? { treeTable: treeTable() } : {},
         issues: controller.getState().issues,
         ...reason ? { readOnly: reason } : {}
       };
@@ -1260,7 +1515,7 @@ function createChartToolProvider(controller, options = {}) {
   const checkColors = {
     name: "check_chart_colors",
     title: "Check chart colours",
-    description: "Checks that colours can be told apart with normal vision and with protanopia, deuteranopia and tritanopia (OKLab distance after simulation), and that they stand out from the background. Checks the chart's own series (or slice) colours unless colours are given. Returns the closest pair per vision, contrast ratios and problems as sentences.",
+    description: "Checks whether the chart's colours are accessible: that colour-blind readers can tell them apart (protanopia, deuteranopia and tritanopia, by OKLab distance after simulation) as well as people with normal vision, and that they stand out from the background. Checks the chart's own series (or slice) colours unless colours are given. Returns the closest pair per vision, contrast ratios and problems as sentences.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1273,7 +1528,7 @@ function createChartToolProvider(controller, options = {}) {
     handler: ({ colors, surface }) => {
       const s = spec();
       const visible = s.series.filter((x) => !x.hidden);
-      const own = chartColorsByCategory(s.type) ? s.categories.map((_, i) => visible[0]?.pointColors?.[i] || chartSliceColor(s, i)) : visible.map((x) => chartSeriesColor(s, s.series.indexOf(x)));
+      const own = chartSpecColorsByCategory(s) ? s.categories.map((_, i) => visible[0]?.pointColors?.[i] || chartSliceColor(s, i)) : visible.map((x) => chartSeriesColor(s, s.series.indexOf(x)));
       return { colors: colors ?? own, ...checkChartColors(colors ?? own, { surface }) };
     }
   };
@@ -1341,7 +1596,7 @@ function createChartToolProvider(controller, options = {}) {
   const updateChart = {
     name: "update_chart",
     title: "Change chart presentation",
-    description: 'Changes how the chart looks, as one undo step: type, titles, axes (xAxis = categories or numeric x, yAxis = values, yAxis2 = secondary values; each can be reversed, and value axes can be logarithmic with scale "log"), legend, stacking, orientation, curve, points, data labels and their position, palette, donut hole, bar spacing, histogram bins, waterfall total, radar rings (radarTicks) and grid shape (radarGraticule). All-or-nothing: invalid values change nothing and come back as sentences. Returns the new spec.',
+    description: 'Changes how the chart looks, as one undo step: type, titles, axes (xAxis = categories or numeric x, yAxis = values, yAxis2 = secondary values; each can be reversed, and value axes can be logarithmic with scale "log"), legend, stacking, orientation, curve, points, data labels and their position, palette, donut hole, bar spacing, histogram bins, waterfall total, radar rings (radarTicks) and grid shape (radarGraticule), note, highlight, reference lines and bands (whole lists), and varyColors. All-or-nothing: invalid values change nothing and come back as sentences. Returns the new spec.',
     inputSchema: {
       type: "object",
       properties: CHART_UPDATE_PROPERTIES,
@@ -1466,7 +1721,7 @@ function createChartToolProvider(controller, options = {}) {
     },
     annotations: { title: "Add a category", ...WRITE },
     handler: ({ label, at }) => {
-      const result = controller.addCategory(label, { at });
+      const result = resolve(controller.addCategory(label, { at }));
       return { index: result.index, categories: spec().categories };
     }
   };
@@ -1565,6 +1820,168 @@ function createChartToolProvider(controller, options = {}) {
       return { series: s.id, trendlines: controller.getSeries(s.id)?.trendlines ?? [] };
     }
   };
+  const referenceTools = (what) => {
+    const Kind = what === "line" ? "Reference line" : "Reference band";
+    const list = () => what === "line" ? spec().referenceLines : spec().referenceBands;
+    const listKey = what === "line" ? "referenceLines" : "referenceBands";
+    const add = {
+      name: `add_chart_reference_${what}`,
+      title: `Add a reference ${what}`,
+      description: what === "line" ? "Draws a dashed line across the plot at one value: a target, a floor, an average (bar, line, area, scatter and bubble charts). The axis grows to keep it in view. Returns its index and the reference lines." : "Shades a band across the plot between two values: a target or normal range (bar, line, area, scatter and bubble charts), drawn under the data. The axis grows to keep it in view. Returns its index and the reference bands.",
+      inputSchema: { type: "object", properties: what === "line" ? REFERENCE_LINE_PROPS : REFERENCE_BAND_PROPS, required: what === "line" ? ["value"] : ["from", "to"], additionalProperties: false },
+      annotations: { title: `Add a reference ${what}`, ...WRITE },
+      handler: (args) => {
+        const result = resolve(what === "line" ? controller.addReferenceLine(args) : controller.addReferenceBand(args));
+        return { index: result.index, [listKey]: list() };
+      }
+    };
+    const update = {
+      name: `update_chart_reference_${what}`,
+      title: `Change a reference ${what}`,
+      description: `Changes a reference ${what} by index (all-or-nothing); label, axis and color take null to remove them. Returns the ${what} as stored.`,
+      inputSchema: { type: "object", properties: { index: REFERENCE_INDEX(Kind), ...what === "line" ? REFERENCE_LINE_PATCH : REFERENCE_BAND_PATCH }, required: ["index"], additionalProperties: false },
+      annotations: { title: `Change a reference ${what}`, ...WRITE_IDEMPOTENT },
+      handler: ({ index, ...patch }) => {
+        if (!Object.keys(patch).length) fail2(`Nothing to change: pass at least one field besides index, e.g. {"index": ${index}, "label": "Target"}.`);
+        resolve(what === "line" ? controller.updateReferenceLine(index, patch) : controller.updateReferenceBand(index, patch));
+        return { index, [`reference${what === "line" ? "Line" : "Band"}`]: list()[index] };
+      }
+    };
+    const remove = {
+      name: `remove_chart_reference_${what}`,
+      title: `Delete a reference ${what}`,
+      description: `Deletes a reference ${what} by index; the ones after it move up one. Returns the reference ${what}s left.`,
+      inputSchema: { type: "object", properties: { index: REFERENCE_INDEX(Kind) }, required: ["index"], additionalProperties: false },
+      annotations: { title: `Delete a reference ${what}`, ...DESTRUCTIVE },
+      handler: ({ index }) => {
+        resolve(what === "line" ? controller.removeReferenceLine(index) : controller.removeReferenceBand(index));
+        return { [listKey]: list() };
+      }
+    };
+    return [add, update, remove];
+  };
+  const [addReferenceLine, updateReferenceLine, removeReferenceLine] = referenceTools("line");
+  const [addReferenceBand, updateReferenceBand, removeReferenceBand] = referenceTools("band");
+  const setCallout = {
+    name: "set_chart_callout",
+    title: "Pin a label to a point",
+    description: 'Pins a short label to one bar or point, with a leader line, to say why it matters ("Record quarter", "Launch"); label null or "" removes it. Bar, line, area, scatter and bubble charts; the point must have a value. Selects the point and returns the series id, category index and label.',
+    inputSchema: {
+      type: "object",
+      properties: { series: SERIES_REF, category: CATEGORY_REF, label: { type: ["string", "null"], description: "The label (keep it to a few words), or null to remove it." } },
+      required: ["series", "category", "label"],
+      additionalProperties: false
+    },
+    annotations: { title: "Pin a label to a point", ...WRITE_IDEMPOTENT },
+    handler: ({ series, category, label }) => {
+      const s = seriesById(series);
+      const index = categoryIndex(category);
+      resolve(controller.setCallout(s.id, index, label));
+      return { series: s.id, index, category: spec().categories[index], label: controller.getSeries(s.id)?.callouts?.[index] ?? null };
+    }
+  };
+  const highlight = {
+    name: "highlight_chart",
+    title: "Highlight categories or series",
+    description: "Draws the named categories (labels) and series (names or ids) normally and mutes the rest, to draw attention to the marks the chart is about; [] shows everything again. A point stays bright when its category or its series is named. Unknown names change nothing and are reported. Returns the category indexes and series ids that matched.",
+    inputSchema: {
+      type: "object",
+      properties: { names: { type: "array", items: { type: "string" }, description: "Category labels and / or series names or ids, exactly as get_chart shows them. [] clears the highlight." } },
+      required: ["names"],
+      additionalProperties: false
+    },
+    annotations: { title: "Highlight categories or series", ...WRITE_IDEMPOTENT },
+    handler: ({ names }) => {
+      const result = resolve(controller.setHighlight(names));
+      const s = spec();
+      return { highlight: s.highlight, categories: result.categories.map((index) => ({ index, label: s.categories[index] })), series: result.series.map((id) => ({ id, name: s.series.find((x) => x.id === id).name })) };
+    }
+  };
+  const setTree = {
+    name: "set_chart_tree",
+    title: "Replace grouped data",
+    description: `Replaces the chart's data with groups of items (a tree) for treemaps and sunbursts, as one undo step: items {"name", "value"} and groups {"name", "children"}, up to 6 levels, names unique among siblings. The top-level groups become the categories and their totals the first series, so other chart types draw the totals. [] goes back to plain data (the totals stay as values). Returns the tree, each group's total and the depth.`,
+    inputSchema: { type: "object", properties: { tree: { type: "array", items: { $ref: "#/$defs/chartTreeNode" }, description: "The top-level nodes; [] removes the grouping." } }, required: ["tree"], additionalProperties: false, $defs: TREE_DEFS },
+    annotations: { title: "Replace grouped data", ...WRITE_IDEMPOTENT },
+    handler: ({ tree }) => {
+      resolve(controller.setTree(tree));
+      return treeSummary();
+    }
+  };
+  const importTreeCsv = {
+    name: "import_chart_tree_csv",
+    title: "Import grouped data from CSV",
+    description: "Replaces the data with grouped data from CSV or TSV: every column but the last holds names (group, subgroup, \u2026, item), the last holds the value. A blank group name repeats the one above, as spreadsheets lay out groups. One undo step. Returns the tree, group totals and depth.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        csv: { type: "string", description: 'CSV or TSV text, e.g. "Region,Country,Customers\\nEurope,France,40\\n,Spain,25".' },
+        header: { type: ["boolean", "string"], enum: [true, false, "auto"], description: "The first row holds column names (default auto: when its last cell is not a number)." }
+      },
+      required: ["csv"],
+      additionalProperties: false
+    },
+    annotations: { title: "Import grouped data from CSV", ...WRITE },
+    handler: ({ csv, header }) => {
+      resolve(controller.importTreeTable(parseCsv(csv, { delimiter: csv.includes("	") ? "	" : "," }), { header }));
+      return treeSummary();
+    }
+  };
+  const addTreeNode = {
+    name: "add_chart_tree_node",
+    title: "Add an item or group",
+    description: "Adds an item or a group (with children) under a group of the grouped data, or at the top level. Returns its path and its parent's new total.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        parent: { type: "array", items: { type: "string" }, description: "Path of the group to add to; [] or omitted for the top level." },
+        node: { $ref: "#/$defs/chartTreeNode", description: 'The item ({"name", "value"}) or group ({"name", "children"}) to add.' },
+        at: { type: "integer", minimum: 0, description: "Position among its siblings (default: the end)." }
+      },
+      required: ["node"],
+      additionalProperties: false,
+      $defs: TREE_DEFS
+    },
+    annotations: { title: "Add an item or group", ...WRITE },
+    handler: ({ parent = [], node, at }) => {
+      const result = resolve(controller.addTreeNode(parent, node, { at }));
+      const group = parent.length ? findChartTreeNode(spec().tree, parent) : null;
+      return { path: result.path, parentTotal: group ? chartTreeTotal(group) : spec().tree.reduce((t, n) => t + chartTreeTotal(n), 0) };
+    }
+  };
+  const updateTreeNode = {
+    name: "update_chart_tree_node",
+    title: "Change an item or group",
+    description: "Renames a node, sets an item's value, or sets a node's colour (null goes back to the palette). Groups have no value of their own. Returns the node's path (new if renamed) and the node.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: TREE_PATH,
+        name: { type: "string", description: "New name (unique among its siblings)." },
+        value: { type: "number", minimum: 0, description: "Items only: the new amount." },
+        color: { type: ["string", "null"], description: "CSS colour, or null for the palette colour." }
+      },
+      required: ["path"],
+      additionalProperties: false
+    },
+    annotations: { title: "Change an item or group", ...WRITE_IDEMPOTENT },
+    handler: ({ path, ...patch }) => {
+      if (!Object.keys(patch).length) fail2("Nothing to change: pass name, value or color with the path.");
+      const result = resolve(controller.updateTreeNode(path, patch));
+      return { path: result.path, node: findChartTreeNode(spec().tree, result.path) };
+    }
+  };
+  const removeTreeNode = {
+    name: "remove_chart_tree_node",
+    title: "Delete an item or group",
+    description: "Deletes a node of the grouped data with everything under it (a group left empty becomes an item with value 0). Returns the group totals left.",
+    inputSchema: { type: "object", properties: { path: TREE_PATH }, required: ["path"], additionalProperties: false },
+    annotations: { title: "Delete an item or group", ...DESTRUCTIVE },
+    handler: ({ path }) => {
+      resolve(controller.removeTreeNode(path));
+      return { groups: treeSummary().groups };
+    }
+  };
   const applyPreset = {
     name: "apply_chart_preset",
     title: "Apply a chart style",
@@ -1731,12 +2148,45 @@ function createChartToolProvider(controller, options = {}) {
     }
   };
   const reads = [getChart, renderChart, checkColors, recommend, getTrendline, listPresets, exportMermaid, exportOoxml];
-  const writes = [updateChart, setData, setValues, addSeries, updateSeries, removeSeries, addCategory, removeCategory, importCsv, importMermaid, addTrendline, removeTrendline, applyPreset, transpose, select, drag, key, undo, redo];
+  const writes = [
+    updateChart,
+    setData,
+    setValues,
+    addSeries,
+    updateSeries,
+    removeSeries,
+    addCategory,
+    removeCategory,
+    importCsv,
+    importMermaid,
+    addTrendline,
+    removeTrendline,
+    addReferenceLine,
+    updateReferenceLine,
+    removeReferenceLine,
+    addReferenceBand,
+    updateReferenceBand,
+    removeReferenceBand,
+    setCallout,
+    highlight,
+    setTree,
+    importTreeCsv,
+    addTreeNode,
+    updateTreeNode,
+    removeTreeNode,
+    applyPreset,
+    transpose,
+    select,
+    drag,
+    key,
+    undo,
+    redo
+  ];
   return withChartPlayback({
     id: options.id ?? "chart",
     namespace: options.namespace,
     title: "Chart editor",
-    description: "One chart: its spec, data and values, series and categories, trendlines and presets, CSV, Mermaid and OOXML import, rendering and colour checks.",
+    description: "One chart: its spec, data and values, series and categories, trendlines, reference lines and bands, callouts, highlight, grouped data and presets, CSV, Mermaid and OOXML import, rendering and colour checks.",
     skill: "pixerate-chart",
     tools: () => {
       if (readOnlyReason()) return reads;
@@ -2231,6 +2681,8 @@ export {
   CHART_LABEL_POSITIONS,
   CHART_LAYOUT_PRESETS,
   CHART_LEGEND_POSITIONS,
+  CHART_LIKERT_NEUTRALS,
+  CHART_LIKERT_SORTS,
   CHART_MARKERS,
   CHART_MERMAID_META_PREFIX,
   CHART_NUMBER_STYLES,
@@ -2242,6 +2694,7 @@ export {
   CHART_PRESENCE_COLORS,
   CHART_RADAR_GRATICULES,
   CHART_RASTER_MAX_SIZE,
+  CHART_REFERENCE_AXES,
   CHART_SERIES_TYPES,
   CHART_STACKINGS,
   CHART_TRENDLINE_TYPES,
@@ -2257,8 +2710,11 @@ export {
   MAX_CHART_DATA_LABELS,
   MAX_CHART_LINE_POINTS,
   MAX_CHART_MARKERS,
+  MAX_CHART_TREE_DEPTH,
+  MAX_CHART_TREE_NODES,
   OfficeChartsError,
   RENDER_CHART_INSTRUCTIONS,
+  addChartTreeRow,
   analyzeChartTable,
   blendChartScenes,
   canDragChartPoint,
@@ -2282,6 +2738,7 @@ export {
   chartFromTable,
   chartHistogram,
   chartHitTest,
+  chartLikertColor,
   chartLuminance,
   chartMermaidFamily,
   chartMovingAverage,
@@ -2301,6 +2758,7 @@ export {
   chartSeriesColor,
   chartSeriesType,
   chartSliceColor,
+  chartSpecColorsByCategory,
   chartSquarify,
   chartSupportsTrendlines,
   chartTextBaseline,
@@ -2309,12 +2767,21 @@ export {
   chartToMermaid,
   chartToOoxml,
   chartToSvg,
+  chartTreeColumnLabels,
+  chartTreeDepth,
+  chartTreeFromRows,
+  chartTreeFromSeries,
+  chartTreeFromTable,
+  chartTreeToRows,
+  chartTreeTotal,
   chartTrendlineName,
   chartValueAtPoint,
+  chartVariesColors,
   chartXAtPoint,
   checkChartColors,
   cloneChartSeries,
   cloneChartSpec,
+  cloneChartTree,
   compileChartFormatCode,
   contrastingTextColor,
   createChartCommands,
@@ -2340,6 +2807,7 @@ export {
   extractOfficeCharts,
   extractPptxCharts,
   extractXlsxCharts,
+  findChartTreeNode,
   findMermaidCharts,
   fitChartTrendline,
   formatChartAmountList,
@@ -2359,7 +2827,10 @@ export {
   niceStep,
   normalizeChartAxis,
   normalizeChartErrorBars,
+  normalizeChartReferenceBand,
+  normalizeChartReferenceLine,
   normalizeChartSpec,
+  normalizeChartTree,
   normalizeChartTrendline,
   normalizeChartValues,
   parseChartAmountList,
@@ -2373,8 +2844,11 @@ export {
   realChartClock,
   recommendChartTypes,
   recommendForShape,
+  removeChartTreeRow,
   resolveChartSvgPaints,
   sameChartSelection,
+  setChartTreeRowName,
+  setChartTreeRowValue,
   shadeChartColor,
   simulateChartVision,
   snapChartDragValue,
@@ -2382,6 +2856,7 @@ export {
   sparklineToSvg,
   startChartPointDrag,
   stepDecimals,
+  suggestChartReferences,
   summarizeChart,
   summarizeChartSeries,
   trendNumberText,