@pixerate/editor 0.164.0 → 0.166.0

package/dist/chart/index.js

@@ -2,6 +2,9 @@ import {
   CATEGORY_REF,
   CHART_UPDATE_PROPERTIES,
   HEIGHT,
+  LINK_INDEX,
+  LINK_PROPS,
+  RACE_TIME,
   REFERENCE_BAND_PATCH,
   REFERENCE_BAND_PROPS,
   REFERENCE_INDEX,
@@ -14,7 +17,7 @@ import {
   TRENDLINE_PROPS,
   VALUE,
   WIDTH
-} from "../chunk-5FNGLV2D.js";
+} from "../chunk-5UNQDC3Q.js";
 import {
   CHART_OOXML_CONTENT_TYPE,
   CHART_OOXML_NS,
@@ -22,7 +25,7 @@ import {
   chartFormatToCode,
   chartFromOoxml,
   chartToOoxml
-} from "../chunk-POR54B55.js";
+} from "../chunk-XNU45TYA.js";
 import {
   CHART_COLOR_SCHEMES,
   CHART_LAYOUT_PRESETS,
@@ -44,7 +47,8 @@ import {
   monochromeChartPalette,
   sparklineToSvg,
   summarizeChart
-} from "../chunk-SZA42R4N.js";
+} from "../chunk-YUFTVNLX.js";
+import "../chunk-KGRZMHZB.js";
 import {
   CHART_DATE_STEPS,
   MAX_CHART_DATA_LABELS,
@@ -56,6 +60,9 @@ import {
   chartHistogram,
   chartMovingAverage,
   chartQuantile,
+  chartRaceMoment,
+  chartRaceRanking,
+  chartRaceValueAt,
   chartScaleFromPixel,
   chartScaleToPixel,
   chartSerialToDate,
@@ -84,7 +91,7 @@ import {
   suggestChartReferences,
   summarizeChartSeries,
   trendNumberText
-} from "../chunk-Z4P2RBMJ.js";
+} from "../chunk-ITANXMZD.js";
 import {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -102,6 +109,7 @@ import {
   CHART_PALETTE_SHADES,
   CHART_RADAR_GRATICULES,
   CHART_REFERENCE_AXES,
+  CHART_SANKEY_LINK_COLORS,
   CHART_SERIES_TYPES,
   CHART_STACKINGS,
   CHART_TRENDLINE_TYPES,
@@ -110,8 +118,10 @@ import {
   CSS_VARIABLE_CHART_THEME,
   DEFAULT_CHART_PALETTE,
   DEFAULT_CHART_THEME,
+  MAX_CHART_LINKS,
   MAX_CHART_TREE_DEPTH,
   MAX_CHART_TREE_NODES,
+  addChartLink,
   addChartTreeRow,
   chartColorDistance,
   chartColorInputValue,
@@ -123,10 +133,13 @@ import {
   chartErrorBarsOfType,
   chartFamily,
   chartLikertColor,
+  chartLinksFromTable,
   chartLuminance,
   chartPointColor,
   chartRgbToHex,
   chartRgbToOklab,
+  chartSankeyNodeValues,
+  chartSankeyNodes,
   chartSeriesColor,
   chartSeriesType,
   chartSliceColor,
@@ -155,6 +168,7 @@ import {
   isXyChart,
   normalizeChartAxis,
   normalizeChartErrorBars,
+  normalizeChartLinks,
   normalizeChartReferenceBand,
   normalizeChartReferenceLine,
   normalizeChartSpec,
@@ -165,12 +179,14 @@ import {
   parseChartColor,
   parseChartValue,
   removeChartTreeRow,
+  setChartLinkField,
   setChartTreeRowName,
   setChartTreeRowValue,
   shadeChartColor,
   simulateChartVision,
   uniqueChartSeriesId
-} from "../chunk-3NEZJCBY.js";
+} from "../chunk-FR432ROA.js";
+import "../chunk-O6OGNDND.js";
 import "../chunk-II2WIF5Z.js";
 import {
   parseCsv
@@ -188,11 +204,12 @@ import {
 } from "../chunk-CIQIM2IP.js";
 import {
   defineEditorDocument
-} from "../chunk-NHLYK3AX.js";
+} from "../chunk-XBQX76CT.js";
 import "../chunk-HF5QZS7Z.js";
 import "../chunk-RNSANXPT.js";
-import "../chunk-QYZGBVNC.js";
-import "../chunk-4VU4CP7R.js";
+import "../chunk-7272D3K2.js";
+import "../chunk-YBAPT7NL.js";
+import "../chunk-MHLU6GRJ.js";
 import "../chunk-6ONMQ6WF.js";
 
 // src/chart/raster.ts
@@ -383,6 +400,7 @@ function recommendForShape(shape) {
     add("area", "Area", "Shows change over time with volume.");
     add("bar", "Column", "Compares each period.");
     if (shape.series > 1) add("area", "Stacked area", "Shows how the parts add up over time.", "stacked");
+    if (shape.series >= 5 && shape.points >= 3) add("barrace", "Bar race", "Many series over time: an animated ranking shows who leads when.");
     return out;
   }
   if (shape.series === 1) {
@@ -417,6 +435,7 @@ function recommendForShape(shape) {
     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 >= 5 && shape.points >= 3) add("barrace", "Bar race", "Many series across ordered categories (such as years): an animated ranking shows who leads when.");
     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;
@@ -462,6 +481,12 @@ function createChartCommands(controller, options = {}) {
     if (index < 0 || index >= categories.length || !Number.isInteger(index)) fail(`There is no category ${JSON.stringify(ref)}; expected an index from 0 to ${categories.length - 1} or one of the labels.`);
     return index;
   };
+  const raceFrame = (time) => {
+    const cats = controller.getSpec().categories;
+    const frame = typeof time === "number" ? time : cats.indexOf(time);
+    if (!(Number.isFinite(frame) && frame >= 0 && frame <= cats.length - 1)) fail(`There is no time point ${JSON.stringify(time)}; expected an index from 0 to ${Math.max(0, cats.length - 1)} or a category label.`);
+    return frame;
+  };
   const object = (properties, required) => ({ type: "object", properties, ...required ? { required } : {}, additionalProperties: false });
   return [
     {
@@ -800,6 +825,131 @@ function createChartCommands(controller, options = {}) {
         return { groups: controller.getSpec().tree.map((n) => ({ name: n.name, total: chartTreeTotal(n) })) };
       }
     },
+    {
+      ...base,
+      id: `${prefix}setLinks`,
+      label: "Replace Flows\u2026",
+      keywords: ["chart", "sankey", "flow", "links", "funnel", "budget"],
+      description: "Replaces the data with flows between named nodes for a Sankey diagram; [] goes back to plain data.",
+      params: object(
+        {
+          links: { type: "array", items: { type: "object", properties: LINK_PROPS, required: ["source", "target", "value"], additionalProperties: false }, description: "All the flows; [] removes them." },
+          nodes: { type: "array", items: { type: "string" }, description: "Node names in stacking order." }
+        },
+        ["links"]
+      ),
+      run: (_ctx, params) => {
+        check(controller.setLinks(params.links, { nodes: params.nodes }));
+        return { links: controller.getSpec().links, nodes: controller.getSpec().sankeyNodes };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}importLinksCsv`,
+      label: "Import Flows from CSV\u2026",
+      keywords: ["chart", "sankey", "flow", "csv", "import"],
+      description: "Replaces the data with flows from CSV / TSV rows of source, target and value.",
+      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.importLinksTable(parseCsv(params.csv, { delimiter: params.csv.includes("	") ? "	" : "," }), { header: params.header }));
+        return { links: controller.getSpec().links };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}addLink`,
+      label: "Add Flow\u2026",
+      keywords: ["chart", "sankey", "flow", "link", "add"],
+      description: "Adds a flow between two nodes. Returns its index.",
+      params: object(LINK_PROPS, ["source", "target", "value"]),
+      run: (_ctx, params) => {
+        const result = controller.addLink(params);
+        check(result);
+        return { index: result.index };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}updateLink`,
+      label: "Change Flow\u2026",
+      keywords: ["chart", "sankey", "flow", "link", "value"],
+      description: "Changes a flow by index (color null for the default).",
+      params: object({ index: LINK_INDEX, ...LINK_PROPS, color: { type: ["string", "null"], description: "CSS colour, or null for the default." } }, ["index"]),
+      run: (_ctx, params) => {
+        const { index, ...patch } = params;
+        check(controller.updateLink(index, patch));
+        return { link: controller.getSpec().links[index] };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}removeLink`,
+      label: "Delete Flow",
+      keywords: ["chart", "sankey", "flow", "link", "remove"],
+      description: "Deletes a flow by index.",
+      params: object({ index: LINK_INDEX }, ["index"]),
+      run: (_ctx, params) => {
+        check(controller.removeLink(params.index));
+        return { links: controller.getSpec().links };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}raceRanking`,
+      label: "Bar Race Ranking",
+      readOnly: true,
+      keywords: ["chart", "race", "ranking", "leader", "time"],
+      description: "Returns the top names of a bar race at a moment (default: the one shown).",
+      params: object({ time: RACE_TIME }),
+      run: (_ctx, params = {}) => {
+        const spec = controller.getSpec();
+        const frame = params?.time !== void 0 ? raceFrame(params.time) : controller.getState().raceFrame ?? spec.categories.length - 1;
+        return { frame, ranking: chartRaceRanking(spec, frame).slice(0, spec.raceTopN).map((e) => ({ rank: e.rank + 1, series: e.seriesId, name: e.name, value: e.value })) };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setRaceFrame`,
+      label: "Show Bar Race Moment\u2026",
+      keywords: ["chart", "race", "frame", "time", "scrub"],
+      description: "Shows the bar race at a time point (null for the last) and stops playback. View state, not an undo step.",
+      params: object({ time: { ...RACE_TIME, type: ["string", "number", "null"], description: `${RACE_TIME.description} null shows the last time point.` } }, ["time"]),
+      run: (_ctx, params) => {
+        const frame = params.time === null ? null : raceFrame(params.time);
+        check(controller.setRaceFrame(frame));
+        return { frame };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}playRace`,
+      label: "Play Bar Race",
+      keywords: ["chart", "race", "play", "animate"],
+      description: "Plays the bar race from the moment shown, one time point every msPerStep ms.",
+      params: object({ msPerStep: { type: "number", minimum: 50, maximum: 1e4, description: "Milliseconds per time point (default 1000)." } }),
+      run: (_ctx, params = {}) => {
+        check(controller.playRace({ msPerStep: params?.msPerStep }));
+        return { playing: true };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}pauseRace`,
+      label: "Pause Bar Race",
+      keywords: ["chart", "race", "pause", "stop"],
+      description: "Pauses bar race playback where it is.",
+      enabled: () => controller.getState().racePlaying || "The race is not playing",
+      run: () => {
+        controller.pauseRace();
+        return { frame: controller.getState().raceFrame };
+      }
+    },
     {
       ...base,
       id: `${prefix}applyPreset`,
@@ -851,11 +1001,11 @@ function createChartCommands(controller, options = {}) {
       id: `${prefix}importMermaid`,
       label: "Import Mermaid Chart\u2026",
       keywords: ["chart", "mermaid", "markdown", "xychart", "pie", "radar", "import"],
-      description: "Replaces the chart with Mermaid xychart-beta, pie or radar-beta text (one undo step). Unreadable lines are listed with line numbers.",
+      description: "Replaces the chart with Mermaid xychart-beta, pie, radar-beta, sankey-beta or treemap-beta text (one undo step). Unreadable lines are listed with line numbers.",
       params: object({ mermaid: { type: "string", description: "Mermaid text." } }, ["mermaid"]),
       run: (_ctx, params) => {
         const read = chartFromMermaid(params.mermaid);
-        if (!read.family) fail(read.issues.map((i) => i.message).join(" ") || "Expected Mermaid starting with xychart-beta, pie or radar-beta.");
+        if (!read.family) fail(read.issues.map((i) => i.message).join(" ") || "Expected Mermaid starting with xychart-beta, pie, radar-beta, sankey-beta or treemap-beta.");
         check(controller.update({ ...read.spec }, { label: "Import Mermaid chart" }));
         return { spec: controller.toJSON(), issues: read.issues };
       }
@@ -1366,6 +1516,11 @@ function planChartToolPlayback(tool, args) {
     case "add_chart_tree_node":
     case "update_chart_tree_node":
     case "remove_chart_tree_node":
+    case "set_chart_links":
+    case "import_chart_links_csv":
+    case "add_chart_link":
+    case "update_chart_link":
+    case "remove_chart_link":
     case "import_chart_csv":
     case "import_chart_mermaid":
     case "import_chart_ooxml":
@@ -1392,6 +1547,10 @@ function planChartToolPlayback(tool, args) {
       return click(control("series.callout"));
     case "highlight_chart":
       return click(control("highlight"));
+    case "set_chart_race_frame":
+      return click(control("raceFrame"));
+    case "play_chart_race":
+      return click({ kind: "action", id: "race-play" });
     case "render_chart":
       return [{ type: "target", ref: { kind: "action", id: "download-png" } }];
     case "undo_chart":
@@ -1456,6 +1615,23 @@ function createChartToolProvider(controller, options = {}) {
     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 raceFrameOf = (time) => {
+    const cats = spec().categories;
+    const frame = typeof time === "number" ? time : cats.indexOf(time);
+    if (!(Number.isFinite(frame) && frame >= 0 && frame <= cats.length - 1))
+      fail2(`There is no time point ${JSON.stringify(time)}; expected an index from 0 to ${Math.max(0, cats.length - 1)} or one of ${cats.slice(0, 20).map((c) => JSON.stringify(c)).join(", ")}.`);
+    return frame;
+  };
+  const raceAt = (frame) => {
+    const s = spec();
+    const at = frame ?? s.categories.length - 1;
+    return {
+      frame: at,
+      time: s.categories[Math.round(at)] ?? null,
+      ranking: chartRaceRanking(s, at).slice(0, s.raceTopN).map((e) => ({ rank: e.rank + 1, series: e.seriesId, name: e.name, value: e.value }))
+    };
+  };
+  const linksSummary = () => ({ links: spec().links, nodes: spec().sankeyNodes.map((name, i) => ({ name, value: chartSankeyNodeValues(spec().links, spec().sankeyNodes)[i] })) });
   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 = {
@@ -1486,14 +1662,16 @@ function createChartToolProvider(controller, options = {}) {
       properties: {
         width: WIDTH,
         height: HEIGHT,
-        format: { type: "string", enum: ["svg", "png"], description: "svg (default): the SVG document as text. png: an image to look at (only when the host can rasterize; costs image tokens)." }
+        format: { type: "string", enum: ["svg", "png"], description: "svg (default): the SVG document as text. png: an image to look at (only when the host can rasterize; costs image tokens)." },
+        time: { ...RACE_TIME, description: `Bar race only: the moment to draw (default: the one shown). ${RACE_TIME.description}` }
       },
       additionalProperties: false
     },
     annotations: { title: "Render the chart", ...READ },
-    handler: async ({ width = size.width, height = size.height, format = "svg" }) => {
+    handler: async ({ width = size.width, height = size.height, format = "svg", time }) => {
       const json = controller.toJSON();
-      const scene = layoutChart(json, { width, height, selection: null });
+      const raceFrame = time !== void 0 ? raceFrameOf(time) : controller.getState().raceFrame;
+      const scene = layoutChart(json, { width, height, selection: null, raceFrame });
       const svg = chartSceneToSvg(scene, { ariaLabel: json.title || void 0, description: describeChart(json) });
       const warnings = scene.warnings;
       if (format === "png") {
@@ -1566,6 +1744,14 @@ function createChartToolProvider(controller, options = {}) {
       return { trendline: line, coefficients: fit.coefficients, r2: fit.r2, equation: fit.equation, points: fit.points };
     }
   };
+  const raceRanking = {
+    name: "get_chart_race_ranking",
+    title: "Read a bar race ranking",
+    description: "Returns who leads a bar race at a moment without changing what is shown: the top raceTopN names with their rank, series id and value (eased between time points). Defaults to the moment shown. Works for any chart, reading categories as time points and series as names.",
+    inputSchema: { type: "object", properties: { time: RACE_TIME }, additionalProperties: false },
+    annotations: { title: "Read a bar race ranking", ...READ },
+    handler: ({ time }) => raceAt(time !== void 0 ? raceFrameOf(time) : controller.getState().raceFrame)
+  };
   const listPresets = {
     name: "list_chart_presets",
     title: "List chart presets",
@@ -1580,7 +1766,7 @@ function createChartToolProvider(controller, options = {}) {
   const exportMermaid = {
     name: "export_chart_mermaid",
     title: "Export chart as Mermaid",
-    description: 'Returns the chart as Mermaid text (xychart-beta, pie or radar-beta) for Markdown or chat. With meta (default true) one "%% @pixerate {\u2026}" comment keeps what Mermaid cannot express, so import_chart_mermaid gets the chart back exactly.',
+    description: 'Returns the chart as Mermaid text for Markdown or chat: xychart-beta, pie or radar-beta, sankey-beta for Sankey diagrams with flows, treemap-beta for treemaps and sunbursts (with their levels). With meta (default true) one "%% @pixerate {\u2026}" comment keeps what Mermaid cannot express, so import_chart_mermaid gets the chart back exactly.',
     inputSchema: { type: "object", properties: { meta: { type: "boolean", description: "Include the round-trip comment (default true)." } }, additionalProperties: false },
     annotations: { title: "Export chart as Mermaid", ...READ },
     handler: ({ meta = true }) => ({ mermaid: chartToMermaid(controller.toJSON(), { meta }) })
@@ -1767,13 +1953,13 @@ function createChartToolProvider(controller, options = {}) {
   const importMermaid = {
     name: "import_chart_mermaid",
     title: "Import a Mermaid chart",
-    description: 'Replaces the chart with Mermaid xychart-beta, pie or radar-beta text as one undo step (a "%% @pixerate" comment from export_chart_mermaid restores everything else). Lines that cannot be read are skipped and listed with their line numbers. Returns the spec.',
+    description: 'Replaces the chart with Mermaid xychart-beta, pie, radar-beta, sankey-beta or treemap-beta text as one undo step (a "%% @pixerate" comment from export_chart_mermaid restores everything else). Lines that cannot be read are skipped and listed with their line numbers. Returns the spec.',
     inputSchema: { type: "object", properties: { mermaid: { type: "string", description: "Mermaid text, optionally inside a ```mermaid fence." } }, required: ["mermaid"], additionalProperties: false },
     annotations: { title: "Import a Mermaid chart", ...DESTRUCTIVE },
     handler: ({ mermaid }) => {
       const fenced = /```(?:mermaid)?\s*\n([\s\S]*?)```/.exec(mermaid);
       const read = chartFromMermaid(fenced ? fenced[1] : mermaid);
-      if (!read.family) fail2(read.issues.map((i) => i.message).join(" ") || "Expected Mermaid starting with xychart-beta, pie or radar-beta.");
+      if (!read.family) fail2(read.issues.map((i) => i.message).join(" ") || "Expected Mermaid starting with xychart-beta, pie, radar-beta, sankey-beta or treemap-beta.");
       resolve(controller.update({ ...read.spec }, { label: "Import Mermaid chart" }));
       return { spec: controller.toJSON(), issues: read.issues };
     }
@@ -1982,6 +2168,105 @@ function createChartToolProvider(controller, options = {}) {
       return { groups: treeSummary().groups };
     }
   };
+  const setLinks = {
+    name: "set_chart_links",
+    title: "Replace the flows",
+    description: `Replaces the chart's data with flows between named nodes for a Sankey diagram, as one undo step: each {"source", "target", "value"} with a value above 0. Flows only go forwards (no loops) and a source-target pair appears once. The nodes become the categories and how much passes through each the first series. nodes (optional) sets the stacking order. [] goes back to plain data. Returns the flows and each node's throughput.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        links: { type: "array", items: { type: "object", properties: LINK_PROPS, required: ["source", "target", "value"], additionalProperties: false }, description: "All the flows; [] removes them." },
+        nodes: { type: "array", items: { type: "string" }, description: "Node names in stacking order (default: as the flows first name them)." }
+      },
+      required: ["links"],
+      additionalProperties: false
+    },
+    annotations: { title: "Replace the flows", ...WRITE_IDEMPOTENT },
+    handler: ({ links, nodes }) => {
+      resolve(controller.setLinks(links, { nodes }));
+      return linksSummary();
+    }
+  };
+  const importLinksCsv = {
+    name: "import_chart_links_csv",
+    title: "Import flows from CSV",
+    description: "Replaces the data with flows from CSV or TSV rows of source, target and value (as Mermaid sankey-beta and spreadsheets write them). One undo step. Returns the flows and each node's throughput.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        csv: { type: "string", description: 'CSV or TSV text, e.g. "Website,Signup,120\\nSignup,Paid,30".' },
+        header: { type: ["boolean", "string"], enum: [true, false, "auto"], description: "The first row holds column names (default auto: when its third cell is not a number)." }
+      },
+      required: ["csv"],
+      additionalProperties: false
+    },
+    annotations: { title: "Import flows from CSV", ...WRITE },
+    handler: ({ csv, header }) => {
+      resolve(controller.importLinksTable(parseCsv(csv, { delimiter: csv.includes("	") ? "	" : "," }), { header }));
+      return linksSummary();
+    }
+  };
+  const addLink = {
+    name: "add_chart_link",
+    title: "Add a flow",
+    description: "Adds a flow from one node to another (new names add nodes). Refused when the pair exists already or it would close a loop. Returns its index and the throughput of its two nodes.",
+    inputSchema: { type: "object", properties: LINK_PROPS, required: ["source", "target", "value"], additionalProperties: false },
+    annotations: { title: "Add a flow", ...WRITE },
+    handler: (args) => {
+      const result = resolve(controller.addLink(args));
+      const s = spec();
+      const through = (n) => s.series[0]?.values[s.sankeyNodes.indexOf(n)] ?? 0;
+      const link = s.links[result.index];
+      return { index: result.index, link, nodes: [link.source, link.target].map((name) => ({ name, value: through(name) })) };
+    }
+  };
+  const updateLink = {
+    name: "update_chart_link",
+    title: "Change a flow",
+    description: "Changes a flow by index: its source, target, value or colour (null goes back to the default). Checked like a new flow. Returns the flow as stored.",
+    inputSchema: { type: "object", properties: { index: LINK_INDEX, ...LINK_PROPS, color: { type: ["string", "null"], description: "CSS colour, or null for the default." } }, required: ["index"], additionalProperties: false },
+    annotations: { title: "Change a flow", ...WRITE_IDEMPOTENT },
+    handler: ({ index, ...patch }) => {
+      if (!Object.keys(patch).length) fail2(`Nothing to change: pass source, target, value or color with the index, e.g. {"index": ${index}, "value": 40}.`);
+      resolve(controller.updateLink(index, patch));
+      return { index, link: spec().links[index] };
+    }
+  };
+  const removeLink = {
+    name: "remove_chart_link",
+    title: "Delete a flow",
+    description: "Deletes a flow by index; the ones after it move up one, and nodes no flow uses any more go. Returns the flows left.",
+    inputSchema: { type: "object", properties: { index: LINK_INDEX }, required: ["index"], additionalProperties: false },
+    annotations: { title: "Delete a flow", ...DESTRUCTIVE },
+    handler: ({ index }) => {
+      resolve(controller.removeLink(index));
+      return { links: spec().links };
+    }
+  };
+  const setRaceFrame = {
+    name: "set_chart_race_frame",
+    title: "Show a bar race moment",
+    description: "Shows the bar race at a time point (or between two), and stops playback. This is view state like the selection: it is not an undo step and is not saved in the chart. Returns the moment and the ranking shown.",
+    inputSchema: { type: "object", properties: { time: { ...RACE_TIME, type: ["string", "number", "null"], description: `${RACE_TIME.description} null shows the last time point.` } }, required: ["time"], additionalProperties: false },
+    annotations: { title: "Show a bar race moment", ...WRITE_IDEMPOTENT },
+    handler: ({ time }) => {
+      const frame = time === null ? null : raceFrameOf(time);
+      resolve(controller.setRaceFrame(frame));
+      return raceAt(frame);
+    }
+  };
+  const playRace = {
+    name: "play_chart_race",
+    title: "Play the bar race",
+    description: "Starts playing the bar race for the user from the moment shown (from the start when it is at the end), one time point every msPerStep ms, and returns at once. set_chart_race_frame stops it. Nothing in the chart changes.",
+    inputSchema: { type: "object", properties: { msPerStep: { type: "number", minimum: 50, maximum: 1e4, description: "Milliseconds per time point (default 1000)." } }, additionalProperties: false },
+    annotations: { title: "Play the bar race", ...WRITE },
+    handler: ({ msPerStep }) => {
+      resolve(controller.playRace({ msPerStep }));
+      const n = spec().categories.length;
+      return { playing: true, from: controller.getState().raceFrame ?? 0, durationMs: Math.round((n - 1 - (controller.getState().raceFrame ?? 0)) * (msPerStep ?? 1e3)) };
+    }
+  };
   const applyPreset = {
     name: "apply_chart_preset",
     title: "Apply a chart style",
@@ -2147,7 +2432,7 @@ function createChartToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, listPresets, exportMermaid, exportOoxml];
+  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, raceRanking, listPresets, exportMermaid, exportOoxml];
   const writes = [
     updateChart,
     setData,
@@ -2174,6 +2459,13 @@ function createChartToolProvider(controller, options = {}) {
     addTreeNode,
     updateTreeNode,
     removeTreeNode,
+    setLinks,
+    importLinksCsv,
+    addLink,
+    updateLink,
+    removeLink,
+    setRaceFrame,
+    playRace,
     applyPreset,
     transpose,
     select,
@@ -2186,7 +2478,7 @@ function createChartToolProvider(controller, options = {}) {
     id: options.id ?? "chart",
     namespace: options.namespace,
     title: "Chart editor",
-    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.",
+    description: "One chart: its spec, data and values, series and categories, trendlines, reference lines and bands, callouts, highlight, grouped data, flows, bar race playback and presets, CSV, Mermaid and OOXML import, rendering and colour checks.",
     skill: "pixerate-chart",
     tools: () => {
       if (readOnlyReason()) return reads;
@@ -2669,6 +2961,194 @@ function createChartEditorDocument(controller) {
     }
   });
 }
+
+// src/chart/style.ts
+var CHART_TYPES3 = ["bar", "line", "area", "scatter", "bubble", "pie", "donut", "radar", "waterfall", "histogram", "box", "funnel", "treemap"];
+var COLOR = { type: "string", minLength: 1, description: 'A CSS colour (hex or rgb()), or a { "$token": ... } reference.' };
+function chartColors(spec) {
+  const out = [];
+  const visible = spec.series.map((s, i) => ({ s, i })).filter(({ s }) => !s.hidden);
+  if (chartColorsByCategory(spec.type)) {
+    const first = visible[0];
+    spec.categories.forEach((name, index) => {
+      const color = first?.s.pointColors?.[index] || chartSliceColor(spec, index);
+      out.push({ color, label: `Slice "${name}"`, target: first ? { kind: "point", seriesId: first.s.id, index } : { kind: "category", index } });
+    });
+    return out;
+  }
+  for (const { s, i } of visible) {
+    out.push({ color: chartSeriesColor(spec, i), label: `Series "${s.name}"`, target: { kind: "series", seriesId: s.id } });
+    s.pointColors?.forEach((c, index) => {
+      if (c) out.push({ color: c, label: `Point ${index + 1} of "${s.name}"`, target: { kind: "point", seriesId: s.id, index } });
+    });
+  }
+  return out;
+}
+var paletteOf = (profile) => {
+  const palette = profile.palette;
+  if (!palette?.length) throw new Error("the profile has no palette.");
+  return palette;
+};
+var paletteOnly = {
+  id: "palette-only",
+  description: "Every series, slice and point colour comes from the house palette (or a lighter or darker shade the chart cycles to once the palette runs out).",
+  optionsSchema: {
+    type: "object",
+    properties: { tolerance: { type: "number", minimum: 0, maximum: 1, description: "Largest OKLab distance still counted as the same colour (default 0.02)." } },
+    additionalProperties: false
+  },
+  run(spec, profile, { tolerance = 0.02 }) {
+    const palette = paletteOf(profile);
+    const allowed = palette.flatMap((c) => CHART_PALETTE_SHADES.map((t) => shadeChartColor(c, t))).map((c) => ({ c, rgb: parseChartColor(c) }));
+    return chartColors(spec).flatMap(({ color, label, target }) => {
+      const rgb = parseChartColor(color);
+      if (!rgb) return [];
+      let best = { c: palette[0], d: Infinity };
+      for (const a of allowed) {
+        if (!a.rgb) continue;
+        const d = chartColorDistance(rgb, a.rgb);
+        if (d < best.d) best = { c: a.c, d };
+      }
+      if (best.d <= tolerance) return [];
+      const nearest = palette.map((c) => ({ c, d: parseChartColor(c) ? chartColorDistance(rgb, parseChartColor(c)) : Infinity })).sort((a, b) => a.d - b.d)[0].c;
+      return [{ severity: "error", message: `${label} uses ${color}, which is not in the house palette; use ${nearest} or another palette colour (${palette.join(", ")}).`, target }];
+    });
+  }
+};
+var distinguishable = {
+  id: "distinguishable",
+  description: "Series (or slice) colours can be told apart with normal vision and with protanopia, deuteranopia and tritanopia.",
+  optionsSchema: {
+    type: "object",
+    properties: { minDistance: { type: "number", minimum: 0, maximum: 1, description: "Smallest OKLab distance between two colours after simulation (default 0.08)." } },
+    additionalProperties: false
+  },
+  run(spec, _profile, { minDistance = 0.08 }) {
+    const colors = chartColors(spec).filter((c) => c.target.kind !== "point" || chartColorsByCategory(spec.type));
+    const result = checkChartColors(colors.map((c) => c.color), { minDistance, minContrast: 0 });
+    const findings = [];
+    for (const [vision, pair] of Object.entries(result.closest)) {
+      if (!pair || pair.distance >= minDistance) continue;
+      const who = vision === "normal" ? "" : ` with ${vision}`;
+      findings.push({
+        severity: "warning",
+        message: `${colors[pair.a].label} (${pair.colors[0]}) and ${colors[pair.b].label} (${pair.colors[1]}) are hard to tell apart${who} (distance ${pair.distance}, want ${minDistance}); give the second another palette colour.`,
+        target: colors[pair.b].target
+      });
+    }
+    return findings;
+  }
+};
+var minContrast = {
+  id: "min-contrast",
+  description: "Marks stand out from the background: each series or slice colour against the profile theme's background (or surface, default white).",
+  optionsSchema: {
+    type: "object",
+    properties: { ratio: { type: "number", minimum: 1, maximum: 21, description: "Smallest contrast ratio (default 3, the WCAG ratio for graphics)." } },
+    additionalProperties: false
+  },
+  run(spec, profile, { ratio = 3 }) {
+    const theme = profile.theme ?? {};
+    const background = theme.background && theme.background !== "transparent" ? theme.background : theme.surface ?? "#ffffff";
+    return chartColors(spec).flatMap(({ color, label, target }) => {
+      const r = chartContrastRatio(color, background);
+      if (r === null || r >= ratio) return [];
+      return [{ severity: "warning", message: `${label} (${color}) has contrast ${Math.round(r * 100) / 100}:1 against the background ${background}; want at least ${ratio}:1, so use a darker or lighter palette colour.`, target }];
+    });
+  }
+};
+var allowedType = {
+  id: "allowed-type",
+  description: "The chart is one of the chart types the house style allows.",
+  optionsSchema: {
+    type: "object",
+    properties: { types: { type: "array", items: { type: "string", enum: [...CHART_TYPES3] }, minItems: 1, description: "Allowed chart types." } },
+    required: ["types"],
+    additionalProperties: false
+  },
+  run(spec, _profile, { types }) {
+    const allowed = types;
+    if (allowed.includes(spec.type)) return [];
+    return [{ severity: "error", message: `This is a ${spec.type} chart; the house style allows ${allowed.join(", ")}. Change the type with update_chart.`, target: { kind: "chart" } }];
+  }
+};
+var chartStyleDomain = {
+  id: "chart",
+  title: "Charts",
+  description: "The house palette and theme for charts, which colour schemes and layouts are allowed, defaults for new charts, and the checks to run.",
+  profileSchema: {
+    type: "object",
+    properties: {
+      palette: { type: "array", items: COLOR, minItems: 1, description: "Series colours in order." },
+      colorSchemes: { type: "array", items: { type: "string", enum: CHART_COLOR_SCHEMES.map((s) => s.id) }, description: "Colour scheme ids allowed besides the palette (empty: none)." },
+      layouts: { type: "array", items: { type: "string", enum: CHART_LAYOUT_PRESETS.map((p) => p.id) }, description: "Layout preset ids allowed." },
+      theme: {
+        type: "object",
+        properties: {
+          background: COLOR,
+          surface: COLOR,
+          text: COLOR,
+          mutedText: COLOR,
+          grid: COLOR,
+          axis: COLOR,
+          positive: COLOR,
+          negative: COLOR,
+          fontFamily: { type: "string", minLength: 1, description: "CSS font family." },
+          fontSize: { type: "number", minimum: 6, maximum: 48, description: "Body text size in px." },
+          titleSize: { type: "number", minimum: 6, maximum: 72, description: "Title size in px." }
+        },
+        additionalProperties: false,
+        description: "Colours and type to draw charts with."
+      },
+      defaults: {
+        type: "object",
+        properties: {
+          dataLabels: { type: "boolean", description: "Value labels on." },
+          points: { type: "boolean", description: "Dots on lines." },
+          curve: { type: "string", enum: ["linear", "smooth", "step"], description: "Line interpolation." },
+          stacking: { type: "string", enum: ["none", "stacked", "percent"], description: "Stacking." },
+          orientation: { type: "string", enum: ["vertical", "horizontal"], description: "Bar direction." },
+          labelPosition: { type: "string", enum: ["auto", "inside", "outside", "center"], description: "Bar label position." }
+        },
+        additionalProperties: false,
+        description: "Spec values new charts start from."
+      }
+    },
+    additionalProperties: false
+  },
+  checks: [paletteOnly, distinguishable, minContrast, allowedType]
+};
+function chartStylePatch(profile) {
+  const p = profile;
+  return { ...p.defaults ?? {}, ...p.palette?.length ? { palette: [...p.palette] } : {} };
+}
+function createChartStyleToolProvider(controller, styles, options = {}) {
+  if (!styles.domains.some((d) => d.id === "chart")) throw new Error('The style resolver has no "chart" domain; add chartStyleDomain to its domains.');
+  const check2 = {
+    name: "check_chart_style",
+    title: "Check chart house style",
+    description: 'Checks the chart against the house style (see get_style with domain "chart"): runs the checks its profile turns on (palette-only, distinguishable, min-contrast, allowed-type). Returns findings with a severity, a sentence saying how to fix it, a target selection (series id or point) for update_chart_series or update_chart, and the layer that asked for it; plus the checks that ran and the ones skipped with the reason. Check after a batch of edits and again after fixing.',
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { title: "Check chart house style", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async () => {
+      const { style, ...report } = await styles.check("chart", controller.getSpec());
+      return {
+        ...report,
+        ok: report.findings.length === 0,
+        ...style.skills.length ? {} : { note: "No house style applies to charts." },
+        ...style.issues.length ? { issues: style.issues } : {}
+      };
+    }
+  };
+  return {
+    id: options.id ?? "chart-style",
+    namespace: options.namespace ?? "chart",
+    title: "Chart house style",
+    description: "Check a chart against the house style.",
+    skill: "pixerate-chart",
+    tools: [check2]
+  };
+}
 export {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -2695,6 +3175,7 @@ export {
   CHART_RADAR_GRATICULES,
   CHART_RASTER_MAX_SIZE,
   CHART_REFERENCE_AXES,
+  CHART_SANKEY_LINK_COLORS,
   CHART_SERIES_TYPES,
   CHART_STACKINGS,
   CHART_TRENDLINE_TYPES,
@@ -2709,11 +3190,13 @@ export {
   DEFAULT_CHART_THEME,
   MAX_CHART_DATA_LABELS,
   MAX_CHART_LINE_POINTS,
+  MAX_CHART_LINKS,
   MAX_CHART_MARKERS,
   MAX_CHART_TREE_DEPTH,
   MAX_CHART_TREE_NODES,
   OfficeChartsError,
   RENDER_CHART_INSTRUCTIONS,
+  addChartLink,
   addChartTreeRow,
   analyzeChartTable,
   blendChartScenes,
@@ -2739,6 +3222,7 @@ export {
   chartHistogram,
   chartHitTest,
   chartLikertColor,
+  chartLinksFromTable,
   chartLuminance,
   chartMermaidFamily,
   chartMovingAverage,
@@ -2747,9 +3231,14 @@ export {
   chartPointRef,
   chartPresetPatch,
   chartQuantile,
+  chartRaceMoment,
+  chartRaceRanking,
+  chartRaceValueAt,
   chartRasterSize,
   chartRgbToHex,
   chartRgbToOklab,
+  chartSankeyNodeValues,
+  chartSankeyNodes,
   chartScaleFromPixel,
   chartScaleToPixel,
   chartSceneToDomSpec,
@@ -2760,6 +3249,8 @@ export {
   chartSliceColor,
   chartSpecColorsByCategory,
   chartSquarify,
+  chartStyleDomain,
+  chartStylePatch,
   chartSupportsTrendlines,
   chartTextBaseline,
   chartTextOn,
@@ -2789,6 +3280,7 @@ export {
   createChartEditorDocument,
   createChartRasterizer,
   createChartSpec,
+  createChartStyleToolProvider,
   createChartToolProvider,
   createInstantChartClock,
   createOfficeChartToolProvider,
@@ -2827,6 +3319,7 @@ export {
   niceStep,
   normalizeChartAxis,
   normalizeChartErrorBars,
+  normalizeChartLinks,
   normalizeChartReferenceBand,
   normalizeChartReferenceLine,
   normalizeChartSpec,
@@ -2847,6 +3340,7 @@ export {
   removeChartTreeRow,
   resolveChartSvgPaints,
   sameChartSelection,
+  setChartLinkField,
   setChartTreeRowName,
   setChartTreeRowValue,
   shadeChartColor,