@pixerate/editor 0.162.1 → 0.163.0

package/README.md

@@ -473,7 +473,7 @@ Each module is also available as a subpath import:
 | `@pixerate/editor/spreadsheet` | `SpreadsheetController`, formula parser/evaluator and dependency graph, formula function registry (`registerFormulaFunction`, `listFormulaFunctions`, `searchFormulaFunctions`, `getFormulaSignature`) and autocomplete helpers (`getFormulaHints`, `applyFormulaSuggestion`) |
 | `@pixerate/editor/image-editor` | `ImageEditorController` and Canvas 2D renderer: crop, adjustments, annotations, depth masks, selections and layer masks, and AI hooks. Needs a DOM/canvas environment (the selection algorithms themselves are pure). |
 | `@pixerate/editor/animation` | The keyframe model without canvas nodes: `AnimationTrack` / `AnimationKeyframe`, easing (`resolveEasing`, `evaluateEasing`, `cubicBezierAt`, `springAt`, presets, `parseCssEasing`, `easingToCss`), `evaluateTrack`, `interpolateAnimationValue`, `normalizeKeyframes`, OKLab colour mixing, `AnimationPlayer` and the `Clock` / `ManualClock` / `realClock` time sources (no third-party imports) |
-| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, clipboard and streaming layout helpers, and node keyframe animation (re-exports everything in `/animation`) |
+| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, node explosion (pure layout, headless explode / collapse state and agent tools), clipboard and streaming layout helpers, and node keyframe animation (re-exports everything in `/animation`) |
 | `@pixerate/editor/agent` | MCP tool schemas, a planner for agent-driven canvas edits, and the dynamic `ToolRegistry` with editor/spreadsheet tool providers |
 | `@pixerate/editor/tools` | `ToolRegistry`, tool types, `validateJsonSchema` and the static MCP tool definitions, without TipTap or dagre (no third-party imports) |
 | `@pixerate/editor/commands` | `CommandRegistry`, `ShortcutMap`, palette ranking, `createCommandToolProvider` and built-in history / arrange / spreadsheet commands (no third-party imports) |

package/dist/agent/index.cjs

@@ -2,7 +2,7 @@
 
 
 
-var _chunk4NGVHHJBcjs = require('../chunk-4NGVHHJB.cjs');
+var _chunkNZD2MZJCcjs = require('../chunk-NZD2MZJC.cjs');
 
 
 var _chunkGLQQ2VILcjs = require('../chunk-GLQQ2VIL.cjs');
@@ -115,15 +115,15 @@ var _chunkN2FGYZ4Qcjs = require('../chunk-N2FGYZ4Q.cjs');
 
 
 
-var _chunkEY22AY6Rcjs = require('../chunk-EY22AY6R.cjs');
+var _chunkYSAGBIRWcjs = require('../chunk-YSAGBIRW.cjs');
 
 
-var _chunk3IHNXRUVcjs = require('../chunk-3IHNXRUV.cjs');
-require('../chunk-HDGBM7EA.cjs');
+var _chunkGKNEJ6ENcjs = require('../chunk-GKNEJ6EN.cjs');
+require('../chunk-SBQVEBSU.cjs');
 
 
 
-var _chunkLL3H5XUHcjs = require('../chunk-LL3H5XUH.cjs');
+var _chunkR3P2M7HUcjs = require('../chunk-R3P2M7HU.cjs');
 
 
 
@@ -624,14 +624,14 @@ var SIZE_WIDTH = {
 };
 var SIZE_HEIGHT = { type: "number", minimum: 50, maximum: 4096, description: "Height in pixels (default 320)." };
 var SPEC_PROPERTIES = {
-  ..._chunk4NGVHHJBcjs.CHART_UPDATE_PROPERTIES,
+  ..._chunkNZD2MZJCcjs.CHART_UPDATE_PROPERTIES,
   categories: { type: "array", items: { type: "string" }, description: "Category labels in order (x axis labels, or pie slices)." },
   series: {
     type: "array",
     description: "The series, each with one value per category (padded with gaps).",
     items: {
       type: "object",
-      properties: { id: { type: "string", description: "Stable id (default: from the name)." }, ..._chunk4NGVHHJBcjs.SERIES_PROPS },
+      properties: { id: { type: "string", description: "Stable id (default: from the name)." }, ..._chunkNZD2MZJCcjs.SERIES_PROPS },
       required: ["name", "values"],
       additionalProperties: false
     }
@@ -642,7 +642,7 @@ function cleanSeries(series) {
   return series.map((s) => s && typeof s === "object" ? Object.fromEntries(Object.entries(s).filter(([, v]) => v !== null)) : s);
 }
 function checkedSpec(input) {
-  const { spec, issues } = _chunkLL3H5XUHcjs.normalizeChartSpec.call(void 0, { ...input, ...input.series !== void 0 ? { series: cleanSeries(input.series) } : {} });
+  const { spec, issues } = _chunkR3P2M7HUcjs.normalizeChartSpec.call(void 0, { ...input, ...input.series !== void 0 ? { series: cleanSeries(input.series) } : {} });
   if (issues.length) throw new Error(`The chart was not changed: ${issues.map((i) => i.message).join(" ")}`);
   return spec;
 }
@@ -657,14 +657,14 @@ function describe(chart, includeSpec) {
     series: spec.series.map((s) => ({ id: s.id, name: s.name })),
     width: _nullishCoalesce(node.attrs.width, () => ( null)),
     height: node.attrs.height,
-    description: _chunk3IHNXRUVcjs.describeChart.call(void 0, spec),
+    description: _chunkGKNEJ6ENcjs.describeChart.call(void 0, spec),
     ...includeSpec ? { spec } : {}
   };
 }
 function sparklines(doc) {
   const found = [];
   doc.descendants((node, pos) => {
-    if (node.type.name === "sparkline") found.push({ pos, kind: node.attrs.kind, values: node.attrs.values, label: _chunkEY22AY6Rcjs.sparklineLabel.call(void 0, node) });
+    if (node.type.name === "sparkline") found.push({ pos, kind: node.attrs.kind, values: node.attrs.values, label: _chunkYSAGBIRWcjs.sparklineLabel.call(void 0, node) });
   });
   return found;
 }
@@ -675,7 +675,7 @@ function checkPosition(editor, at) {
 function createDocumentChartTools(editor) {
   const chartType = () => editor().schema.nodes.chart;
   const findChart = (args) => {
-    const charts = _chunkEY22AY6Rcjs.getDocumentCharts.call(void 0, editor().state.doc);
+    const charts = _chunkYSAGBIRWcjs.getDocumentCharts.call(void 0, editor().state.doc);
     const list = charts.map((c) => `"${c.id}" at ${c.pos}`).join(", ") || "none; add one with insert_chart";
     if (args.chartId !== void 0) {
       const chart = charts.find((c) => c.id === args.chartId);
@@ -702,7 +702,7 @@ function createDocumentChartTools(editor) {
     annotations: { title: "List charts in the document", ...READ },
     handler: ({ includeSpec = false }) => {
       const doc = editor().state.doc;
-      return { charts: _chunkEY22AY6Rcjs.getDocumentCharts.call(void 0, doc).map((c) => describe(c, includeSpec)), sparklines: editor().schema.nodes.sparkline ? sparklines(doc) : [] };
+      return { charts: _chunkYSAGBIRWcjs.getDocumentCharts.call(void 0, doc).map((c) => describe(c, includeSpec)), sparklines: editor().schema.nodes.sparkline ? sparklines(doc) : [] };
     }
   };
   const insertChart = {
@@ -729,7 +729,7 @@ function createDocumentChartTools(editor) {
       const node = { type: "chart", attrs: { id, spec, width, ...height !== void 0 ? { height } : {} } };
       const chain = ed.chain().command(({ tr }) => (_history.closeHistory.call(void 0, tr), true));
       const ok = (at !== void 0 ? chain.insertContentAt(at, node) : chain.insertContent(node)).run();
-      const chart = _chunkEY22AY6Rcjs.getDocumentCharts.call(void 0, ed.state.doc).find((c) => c.id === id);
+      const chart = _chunkYSAGBIRWcjs.getDocumentCharts.call(void 0, ed.state.doc).find((c) => c.id === id);
       if (!ok || !chart) throw new Error(`A chart cannot go at ${_nullishCoalesce(at, () => ( ed.state.selection.from))}; pass a position between blocks or inside a paragraph.`);
       return { id: chart.id, pos: chart.pos, spec: chart.spec, width: chart.node.attrs.width, height: chart.node.attrs.height };
     }
@@ -776,8 +776,8 @@ function createDocumentChartTools(editor) {
     inputSchema: {
       type: "object",
       properties: {
-        values: { type: "array", items: _chunk4NGVHHJBcjs.VALUE, minItems: 1, maxItems: _chunkEY22AY6Rcjs.MAX_SPARKLINE_VALUES, description: "Values in order (null for a gap)." },
-        kind: { type: "string", enum: [..._chunkEY22AY6Rcjs.SPARKLINE_KINDS], description: "line (default), column, or win-loss (sign only)." },
+        values: { type: "array", items: _chunkNZD2MZJCcjs.VALUE, minItems: 1, maxItems: _chunkYSAGBIRWcjs.MAX_SPARKLINE_VALUES, description: "Values in order (null for a gap)." },
+        kind: { type: "string", enum: [..._chunkYSAGBIRWcjs.SPARKLINE_KINDS], description: "line (default), column, or win-loss (sign only)." },
         at: { type: "integer", minimum: 0, description: "Document position inside a paragraph (default: the selection)." },
         width: { type: "number", minimum: 4, maximum: 1e3, description: "Width in pixels (default 80)." },
         height: { type: "number", minimum: 4, maximum: 200, description: "Height in pixels (default 18)." },
@@ -791,12 +791,12 @@ function createDocumentChartTools(editor) {
     handler: ({ values, kind = "line", at, width = 80, height = 18, color = null, label = null }) => {
       const ed = editor();
       checkPosition(ed, at);
-      const parsed = values.map((v) => _chunkLL3H5XUHcjs.parseChartValue.call(void 0, v));
+      const parsed = values.map((v) => _chunkR3P2M7HUcjs.parseChartValue.call(void 0, v));
       const bad = parsed.findIndex((v) => v === void 0);
       if (bad >= 0) throw new Error(`values[${bad}] ("${String(values[bad])}") is not a number; pass numbers, numeric text or null. Nothing was inserted.`);
       const pos = _nullishCoalesce(at, () => ( ed.state.selection.from));
       if (!ed.state.doc.resolve(pos).parent.inlineContent) throw new Error(`Position ${pos} is between blocks; a sparkline goes inside a paragraph (use a position from get_text {blocks: true}).`);
-      const stored = _chunkEY22AY6Rcjs.normalizeSparklineValues.call(void 0, parsed);
+      const stored = _chunkYSAGBIRWcjs.normalizeSparklineValues.call(void 0, parsed);
       ed.chain().command(({ tr }) => (_history.closeHistory.call(void 0, tr), true)).insertContentAt(pos, { type: "sparkline", attrs: { values: stored, kind, width, height, color, label } }).run();
       return { pos, kind, values: stored };
     }
@@ -1134,8 +1134,8 @@ function createTextPresence(editor, providerId, option) {
   const config = option === false ? null : option === true || option === void 0 ? {} : option;
   const caret = {
     id: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _43 => _43.id]), () => ( providerId)),
-    name: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _44 => _44.name]), () => ( _chunkEY22AY6Rcjs.DEFAULT_AGENT_CARET_NAME)),
-    color: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _45 => _45.color]), () => ( _chunkEY22AY6Rcjs.DEFAULT_AGENT_CARET_COLOR))
+    name: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _44 => _44.name]), () => ( _chunkYSAGBIRWcjs.DEFAULT_AGENT_CARET_NAME)),
+    color: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _45 => _45.color]), () => ( _chunkYSAGBIRWcjs.DEFAULT_AGENT_CARET_COLOR))
   };
   const typing = !_optionalChain([config, 'optionalAccess', _46 => _46.typing]) ? null : config.typing === true ? {} : config.typing;
   const idleMs = _nullishCoalesce(_optionalChain([config, 'optionalAccess', _47 => _47.idleMs]), () => ( 12e3));
@@ -1148,19 +1148,19 @@ function createTextPresence(editor, providerId, option) {
   };
   const touch = () => {
     clearTimeout(idleTimer);
-    if (idleMs > 0) idleTimer = setTimeout(() => live() && _chunkEY22AY6Rcjs.clearAgentCaret.call(void 0, live(), caret.id), idleMs);
+    if (idleMs > 0) idleTimer = setTimeout(() => live() && _chunkYSAGBIRWcjs.clearAgentCaret.call(void 0, live(), caret.id), idleMs);
   };
   const tint = (ed, ranges) => {
     clearTimeout(tintTimer);
-    _chunkEY22AY6Rcjs.markAgentChanges.call(void 0, ed, caret.id, ranges);
-    if (changedMs > 0 && ranges.length) tintTimer = setTimeout(() => live() && _chunkEY22AY6Rcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
+    _chunkYSAGBIRWcjs.markAgentChanges.call(void 0, ed, caret.id, ranges);
+    if (changedMs > 0 && ranges.length) tintTimer = setTimeout(() => live() && _chunkYSAGBIRWcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
   };
   return {
     /** Puts the caret at `head`, selecting from `anchor`. */
     show(anchor, head = anchor) {
       const ed = live();
       if (!ed) return;
-      _chunkEY22AY6Rcjs.setAgentCaret.call(void 0, ed, { ...caret, from: anchor, to: head });
+      _chunkYSAGBIRWcjs.setAgentCaret.call(void 0, ed, { ...caret, from: anchor, to: head });
       touch();
     },
     /** Shows the caret after ranges just changed by a tool, tinting them. */
@@ -1168,7 +1168,7 @@ function createTextPresence(editor, providerId, option) {
       const ed = live();
       if (!ed || !ranges.length) return;
       const last = ranges[ranges.length - 1];
-      _chunkEY22AY6Rcjs.setAgentCaret.call(void 0, ed, { ...caret, from: last.to });
+      _chunkYSAGBIRWcjs.setAgentCaret.call(void 0, ed, { ...caret, from: last.to });
       tint(ed, ranges);
       touch();
     },
@@ -1176,12 +1176,12 @@ function createTextPresence(editor, providerId, option) {
     async write(ed, from, to, text, signal) {
       if (live() && typing) {
         clearTimeout(tintTimer);
-        const range2 = await _chunkEY22AY6Rcjs.typeAgentText.call(void 0, ed, { ...typing, from, to, text, caret, signal });
-        if (changedMs > 0) tintTimer = setTimeout(() => live() && _chunkEY22AY6Rcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
+        const range2 = await _chunkYSAGBIRWcjs.typeAgentText.call(void 0, ed, { ...typing, from, to, text, caret, signal });
+        if (changedMs > 0) tintTimer = setTimeout(() => live() && _chunkYSAGBIRWcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
         touch();
         return range2;
       }
-      const tr = _history.closeHistory.call(void 0, _chunkEY22AY6Rcjs.replaceWithTextTransaction.call(void 0, ed.state, from, to, text));
+      const tr = _history.closeHistory.call(void 0, _chunkYSAGBIRWcjs.replaceWithTextTransaction.call(void 0, ed.state, from, to, text));
       const end = tr.mapping.map(to, 1);
       const range = { from: Math.min(tr.mapping.map(from, -1), end), to: end };
       ed.view.dispatch(tr.scrollIntoView());
@@ -1210,7 +1210,7 @@ function findMatches(editor, query, args, replacement) {
     wholeWord: !!args.wholeWord,
     ...args.regex ? { regex: true } : { literal: true }
   };
-  const result = _chunkEY22AY6Rcjs.searchDocument.call(void 0, editor.state.doc, query, options, replacement !== void 0 ? { replacement } : {});
+  const result = _chunkYSAGBIRWcjs.searchDocument.call(void 0, editor.state.doc, query, options, replacement !== void 0 ? { replacement } : {});
   if (result.error) throw new Error(`Invalid search pattern: ${result.error.message}`);
   return { matches: result.matches, truncated: result.truncated };
 }
@@ -1372,7 +1372,7 @@ function createRichTextToolProvider(target, options) {
         replacement: String(replace).replace(/\r\n?|\n/g, "\r")
       }));
       const tr = _history.closeHistory.call(void 0, ed.state.tr);
-      const ends = _chunkEY22AY6Rcjs.applyReplacements.call(void 0, tr, chosen);
+      const ends = _chunkYSAGBIRWcjs.applyReplacements.call(void 0, tr, chosen);
       ed.view.dispatch(tr.scrollIntoView());
       const ranges = chosen.map((m, i) => ({ from: tr.mapping.map(m.from, -1), to: ends[i] }));
       presence.changed(ranges.filter((r) => r.from < r.to));
@@ -1473,7 +1473,7 @@ function createRichTextToolProvider(target, options) {
     inputSchema: {
       type: "object",
       properties: {
-        operation: { type: "string", enum: _chunkEY22AY6Rcjs.TABLE_ACTIONS.map((a) => a.action), description: "Table operation." },
+        operation: { type: "string", enum: _chunkYSAGBIRWcjs.TABLE_ACTIONS.map((a) => a.action), description: "Table operation." },
         at: { type: "integer", minimum: 0, description: "Document position to place the cursor first (e.g. inside a cell)." },
         rows: { type: "integer", minimum: 1, maximum: 100, description: "insertTable: rows (default 3)." },
         cols: { type: "integer", minimum: 1, maximum: 50, description: "insertTable: columns (default 3)." },
@@ -1503,10 +1503,10 @@ function createRichTextToolProvider(target, options) {
         ed.view.dispatch(ed.state.tr.setSelection(_state.TextSelection.near(ed.state.doc.resolve(at))));
       }
       const action = operation;
-      const state = _chunkEY22AY6Rcjs.getTableActionState.call(void 0, ed, action, params);
+      const state = _chunkYSAGBIRWcjs.getTableActionState.call(void 0, ed, action, params);
       if (state !== true) throw new Error(state);
-      _chunkEY22AY6Rcjs.runTableAction.call(void 0, ed, action, params);
-      const table = _chunkEY22AY6Rcjs.getTableState.call(void 0, ed);
+      _chunkYSAGBIRWcjs.runTableAction.call(void 0, ed, action, params);
+      const table = _chunkYSAGBIRWcjs.getTableState.call(void 0, ed);
       return {
         operation,
         table: table.inTable ? { rows: table.rows, columns: table.columns, row: table.row, column: table.column } : null,
@@ -1525,7 +1525,7 @@ function createRichTextToolProvider(target, options) {
       if (!ed || ed.isDestroyed) return [];
       if (!ed.isEditable) return [getText, findText, ...charts.read()];
       const tools = [getText, findText, insertText, replaceText, replaceRange, replaceSelection, setSelection, ...formatting.tools(ed)];
-      return [...tools, ..._chunkEY22AY6Rcjs.isTableEnabled.call(void 0, ed) ? [editTable] : [], ...charts.read(), ...charts.write().map(withCaret)];
+      return [...tools, ..._chunkYSAGBIRWcjs.isTableEnabled.call(void 0, ed) ? [editTable] : [], ...charts.read(), ...charts.write().map(withCaret)];
     },
     subscribe: (notify) => {
       const ed = editor();

package/dist/agent/index.js

@@ -2,7 +2,7 @@ import {
   CHART_UPDATE_PROPERTIES,
   SERIES_PROPS,
   VALUE
-} from "../chunk-EVPZ5IKN.js";
+} from "../chunk-5FNGLV2D.js";
 import {
   hasVariantCommands
 } from "../chunk-3TNA7JKI.js";
@@ -115,15 +115,15 @@ import {
   setAgentCaret,
   sparklineLabel,
   typeAgentText
-} from "../chunk-CX6JLDFC.js";
+} from "../chunk-OXERWBKE.js";
 import {
   describeChart
-} from "../chunk-XDCFJEU7.js";
-import "../chunk-DTSTNRPH.js";
+} from "../chunk-SZA42R4N.js";
+import "../chunk-Z4P2RBMJ.js";
 import {
   normalizeChartSpec,
   parseChartValue
-} from "../chunk-HLOKB7WW.js";
+} from "../chunk-3NEZJCBY.js";
 import {
   getEditorMarkdown,
   getEditorText

package/dist/canvas/index.cjs

@@ -113,10 +113,10 @@ var _chunkPY4GWSE2cjs = require('../chunk-PY4GWSE2.cjs');
 var _chunkN2FGYZ4Qcjs = require('../chunk-N2FGYZ4Q.cjs');
 
 
-var _chunkHDGBM7EAcjs = require('../chunk-HDGBM7EA.cjs');
+var _chunkSBQVEBSUcjs = require('../chunk-SBQVEBSU.cjs');
 
 
-var _chunkLL3H5XUHcjs = require('../chunk-LL3H5XUH.cjs');
+var _chunkR3P2M7HUcjs = require('../chunk-R3P2M7HU.cjs');
 require('../chunk-55AKPTLM.cjs');
 
 
@@ -8871,7 +8871,7 @@ function xyChartSpec(graph, palette) {
     );
   }
   const bars = graph.nodes.some((n3) => n3.shape === "bar");
-  return _chunkLL3H5XUHcjs.createChartSpec.call(void 0, {
+  return _chunkR3P2M7HUcjs.createChartSpec.call(void 0, {
     type: bars ? "bar" : "line",
     title: _nullishCoalesce(graph.title, () => ( "")),
     categories,
@@ -8885,7 +8885,7 @@ function xyChartSpec(graph, palette) {
 }
 function radarChartSpec(graph, palette) {
   const data = _nullishCoalesce(graph.data, () => ( {}));
-  return _chunkLL3H5XUHcjs.createChartSpec.call(void 0, {
+  return _chunkR3P2M7HUcjs.createChartSpec.call(void 0, {
     type: "radar",
     title: _nullishCoalesce(graph.title, () => ( "")),
     categories: Array.isArray(data.axes) ? data.axes.map(String) : [],
@@ -8933,12 +8933,12 @@ function translatePath(d, dx, dy) {
 }
 var xyChartScene = ({ graph, theme }) => {
   const box = _chunkZVNAMTFOcjs.XY_CHART_BOX;
-  const scene = _chunkHDGBM7EAcjs.layoutChart.call(void 0, xyChartSpec(graph, theme.palette), { width: box.width, height: box.height, theme: chartTheme(theme) });
+  const scene = _chunkSBQVEBSUcjs.layoutChart.call(void 0, xyChartSpec(graph, theme.palette), { width: box.width, height: box.height, theme: chartTheme(theme) });
   return toDiagramMarks(scene.marks, box.x, box.y);
 };
 var radarScene = ({ graph, theme }) => {
   const box = _chunkZVNAMTFOcjs.RADAR_CHART_BOX;
-  const scene = _chunkHDGBM7EAcjs.layoutChart.call(void 0, radarChartSpec(graph, theme.palette), { width: box.width, height: box.height, theme: chartTheme(theme) });
+  const scene = _chunkSBQVEBSUcjs.layoutChart.call(void 0, radarChartSpec(graph, theme.palette), { width: box.width, height: box.height, theme: chartTheme(theme) });
   return toDiagramMarks(scene.marks, box.x, box.y);
 };
 

package/dist/canvas/index.js

@@ -113,10 +113,10 @@ import {
 } from "../chunk-5ED73EC6.js";
 import {
   layoutChart
-} from "../chunk-DTSTNRPH.js";
+} from "../chunk-Z4P2RBMJ.js";
 import {
   createChartSpec
-} from "../chunk-HLOKB7WW.js";
+} from "../chunk-3NEZJCBY.js";
 import "../chunk-II2WIF5Z.js";
 import {
   PathOpsError,

package/dist/chart/commands.d.cts

@@ -10,7 +10,8 @@ export interface ChartCommandOptions {
 }
 /**
  * Palette and agent commands for a chart: describe, update presentation, replace data, set
- * values, add / remove series, categories and trendlines, apply presets, switch rows and
+ * values, add / remove series, categories, trendlines and reference lines and bands, pin
+ * callouts, highlight, apply presets, switch rows and
  * columns, import CSV or Mermaid, export SVG, Mermaid or Office XML, recommend types and
  * check colours. Register them in a `CommandRegistry` and agents get them through
  * `createCommandToolProvider`; `createChartToolProvider` offers the same operations as

package/dist/chart/commands.d.ts

@@ -10,7 +10,8 @@ export interface ChartCommandOptions {
 }
 /**
  * Palette and agent commands for a chart: describe, update presentation, replace data, set
- * values, add / remove series, categories and trendlines, apply presets, switch rows and
+ * values, add / remove series, categories, trendlines and reference lines and bands, pin
+ * callouts, highlight, apply presets, switch rows and
  * columns, import CSV or Mermaid, export SVG, Mermaid or Office XML, recommend types and
  * check colours. Register them in a `CommandRegistry` and agents get them through
  * `createCommandToolProvider`; `createChartToolProvider` offers the same operations as

package/dist/chart/controller.d.cts

@@ -1,7 +1,8 @@
 import { HistoryManager } from '../history/HistoryManager.cjs';
 import { type ChartTrendFit } from './trend.cjs';
+import { type ChartTreeRow } from './tree.cjs';
 import { type ChartTableOptions } from './spec.cjs';
-import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.cjs';
+import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartReferenceBand, ChartReferenceLine, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.cjs';
 export interface ChartControllerOptions {
     /** Starting chart (any partial or saved spec; problems are reported in `state.issues`). */
     spec?: Partial<ChartSpec> | unknown;
@@ -54,6 +55,7 @@ export interface ChartSeriesInput {
     x?: readonly unknown[];
     sizes?: readonly unknown[];
     pointColors?: readonly (string | null)[];
+    callouts?: readonly (string | null)[];
     marker?: ChartMarker;
     curve?: ChartCurve;
     dataLabels?: boolean;
@@ -74,6 +76,8 @@ export interface ChartSeriesPatch {
     x?: readonly unknown[] | null;
     sizes?: readonly unknown[] | null;
     pointColors?: readonly (string | null)[] | null;
+    /** One label per category (null: none); `null` removes them all. */
+    callouts?: readonly (string | null)[] | null;
     marker?: ChartMarker | null;
     curve?: ChartCurve | null;
     dataLabels?: boolean | null;
@@ -188,6 +192,9 @@ export declare class ChartController {
     }): {
         ok: true;
         index: number;
+    } | {
+        ok: false;
+        message: string;
     };
     removeCategory(index: number): ChartActionResult;
     renameCategory(index: number, label: string): ChartActionResult;
@@ -213,6 +220,107 @@ export declare class ChartController {
     }): ChartActionResult & {
         issues?: ChartIssue[];
     };
+    /** A refusal while the data is a tree (cell edits would be overwritten by its totals), else null. */
+    private treeLocked;
+    /** Replaces the grouped data (an empty list goes back to the table, keeping the totals as values). One undo step. */
+    setTree(tree: unknown, options?: ChartEditOptions): ChartActionResult;
+    /**
+     * Replaces the grouped data from rows of names and a value (group, …, item, value), as the
+     * data grid edits it; colours of nodes whose path is unchanged are kept. All-or-nothing.
+     */
+    setTreeRows(rows: readonly ChartTreeRow[] | readonly {
+        path: readonly unknown[];
+        value: unknown;
+    }[], options?: ChartEditOptions): ChartActionResult;
+    /** Replaces the data with a table of names and values (group, …, item, value); see `chartTreeFromTable`. */
+    importTreeTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+        header?: boolean | 'auto';
+    }): ChartActionResult;
+    private nodeAt;
+    /** Adds a node under the group at `parent` ([] for the top level) at `at` (default: the end). Returns its path. */
+    addTreeNode(parent: readonly string[], input: {
+        name: string;
+        value?: number;
+        color?: string;
+        children?: unknown[];
+    }, options?: {
+        at?: number;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Renames, revalues (items only) or recolours a node; `color: null` goes back to the palette. Returns its path. */
+    updateTreeNode(path: readonly string[], patch: {
+        name?: string;
+        value?: number;
+        color?: string | null;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Removes a node (with everything under it). A group left empty becomes an item with value 0. */
+    removeTreeNode(path: readonly string[]): ChartActionResult;
+    /** Sets the note written under the chart ("" removes it). */
+    setNote(note: string): ChartActionResult;
+    /**
+     * Draws the named categories (labels) and series (names or ids) normally and mutes the
+     * rest; an empty list shows everything. Unknown names change nothing. Returns the category
+     * indexes and series ids that matched.
+     */
+    setHighlight(names: readonly string[]): {
+        ok: true;
+        categories: number[];
+        series: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Why a reference on `axis` at `values` cannot be drawn on this chart, or null. */
+    private referenceProblem;
+    private editReferences;
+    /** Adds a reference line (a target, floor or average). Returns its index. */
+    addReferenceLine(input: ChartReferenceLine): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference line (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceLine(index: number, patch: {
+        [K in keyof ChartReferenceLine]?: ChartReferenceLine[K] | null;
+    }): ChartActionResult;
+    removeReferenceLine(index: number): ChartActionResult;
+    /** Adds a reference band (a target range). Returns its index. */
+    addReferenceBand(input: ChartReferenceBand): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference band (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceBand(index: number, patch: {
+        [K in keyof ChartReferenceBand]?: ChartReferenceBand[K] | null;
+    }): ChartActionResult;
+    removeReferenceBand(index: number): ChartActionResult;
+    private noReference;
+    /**
+     * Pins a label to one bar or point (`null` or "" removes it) and selects the point. The
+     * point must have a value, on a bar, line, area, scatter or bubble chart.
+     */
+    setCallout(seriesId: string, index: number, label: string | null): ChartActionResult;
     /** Adds a trendline to a series and selects it. Returns its index (and the fit, when it can be computed). */
     addTrendline(seriesId: string, input: ChartTrendline): {
         ok: true;

package/dist/chart/controller.d.ts

@@ -1,7 +1,8 @@
 import { HistoryManager } from '../history/HistoryManager.js';
 import { type ChartTrendFit } from './trend.js';
+import { type ChartTreeRow } from './tree.js';
 import { type ChartTableOptions } from './spec.js';
-import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.js';
+import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartReferenceBand, ChartReferenceLine, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.js';
 export interface ChartControllerOptions {
     /** Starting chart (any partial or saved spec; problems are reported in `state.issues`). */
     spec?: Partial<ChartSpec> | unknown;
@@ -54,6 +55,7 @@ export interface ChartSeriesInput {
     x?: readonly unknown[];
     sizes?: readonly unknown[];
     pointColors?: readonly (string | null)[];
+    callouts?: readonly (string | null)[];
     marker?: ChartMarker;
     curve?: ChartCurve;
     dataLabels?: boolean;
@@ -74,6 +76,8 @@ export interface ChartSeriesPatch {
     x?: readonly unknown[] | null;
     sizes?: readonly unknown[] | null;
     pointColors?: readonly (string | null)[] | null;
+    /** One label per category (null: none); `null` removes them all. */
+    callouts?: readonly (string | null)[] | null;
     marker?: ChartMarker | null;
     curve?: ChartCurve | null;
     dataLabels?: boolean | null;
@@ -188,6 +192,9 @@ export declare class ChartController {
     }): {
         ok: true;
         index: number;
+    } | {
+        ok: false;
+        message: string;
     };
     removeCategory(index: number): ChartActionResult;
     renameCategory(index: number, label: string): ChartActionResult;
@@ -213,6 +220,107 @@ export declare class ChartController {
     }): ChartActionResult & {
         issues?: ChartIssue[];
     };
+    /** A refusal while the data is a tree (cell edits would be overwritten by its totals), else null. */
+    private treeLocked;
+    /** Replaces the grouped data (an empty list goes back to the table, keeping the totals as values). One undo step. */
+    setTree(tree: unknown, options?: ChartEditOptions): ChartActionResult;
+    /**
+     * Replaces the grouped data from rows of names and a value (group, …, item, value), as the
+     * data grid edits it; colours of nodes whose path is unchanged are kept. All-or-nothing.
+     */
+    setTreeRows(rows: readonly ChartTreeRow[] | readonly {
+        path: readonly unknown[];
+        value: unknown;
+    }[], options?: ChartEditOptions): ChartActionResult;
+    /** Replaces the data with a table of names and values (group, …, item, value); see `chartTreeFromTable`. */
+    importTreeTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+        header?: boolean | 'auto';
+    }): ChartActionResult;
+    private nodeAt;
+    /** Adds a node under the group at `parent` ([] for the top level) at `at` (default: the end). Returns its path. */
+    addTreeNode(parent: readonly string[], input: {
+        name: string;
+        value?: number;
+        color?: string;
+        children?: unknown[];
+    }, options?: {
+        at?: number;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Renames, revalues (items only) or recolours a node; `color: null` goes back to the palette. Returns its path. */
+    updateTreeNode(path: readonly string[], patch: {
+        name?: string;
+        value?: number;
+        color?: string | null;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Removes a node (with everything under it). A group left empty becomes an item with value 0. */
+    removeTreeNode(path: readonly string[]): ChartActionResult;
+    /** Sets the note written under the chart ("" removes it). */
+    setNote(note: string): ChartActionResult;
+    /**
+     * Draws the named categories (labels) and series (names or ids) normally and mutes the
+     * rest; an empty list shows everything. Unknown names change nothing. Returns the category
+     * indexes and series ids that matched.
+     */
+    setHighlight(names: readonly string[]): {
+        ok: true;
+        categories: number[];
+        series: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Why a reference on `axis` at `values` cannot be drawn on this chart, or null. */
+    private referenceProblem;
+    private editReferences;
+    /** Adds a reference line (a target, floor or average). Returns its index. */
+    addReferenceLine(input: ChartReferenceLine): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference line (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceLine(index: number, patch: {
+        [K in keyof ChartReferenceLine]?: ChartReferenceLine[K] | null;
+    }): ChartActionResult;
+    removeReferenceLine(index: number): ChartActionResult;
+    /** Adds a reference band (a target range). Returns its index. */
+    addReferenceBand(input: ChartReferenceBand): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference band (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceBand(index: number, patch: {
+        [K in keyof ChartReferenceBand]?: ChartReferenceBand[K] | null;
+    }): ChartActionResult;
+    removeReferenceBand(index: number): ChartActionResult;
+    private noReference;
+    /**
+     * Pins a label to one bar or point (`null` or "" removes it) and selects the point. The
+     * point must have a value, on a bar, line, area, scatter or bubble chart.
+     */
+    setCallout(seriesId: string, index: number, label: string | null): ChartActionResult;
     /** Adds a trendline to a series and selects it. Returns its index (and the fit, when it can be computed). */
     addTrendline(seriesId: string, input: ChartTrendline): {
         ok: true;