@pixerate/editor 0.162.0 → 0.163.0

package/dist/vector/index.js

@@ -38,7 +38,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-KGTF55R3.js";
+} from "../chunk-QY4KUDMY.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -507,8 +507,8 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-2TKHLX6H.js";
-import "../chunk-A5UCR2TO.js";
+} from "../chunk-SET6KJOP.js";
+import "../chunk-YXKLVD56.js";
 import {
   createProvenance
 } from "../chunk-M6DNZNVY.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.162.0",
+  "version": "0.163.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -371,7 +371,7 @@
     "prosemirror-markdown": "^1.13.9"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.137.0",
+    "@anthropic-ai/sdk": "1.1.0",
     "@dagrejs/dagre": "^1.1.8",
     "@tiptap/core": "^2.27.3",
     "@tiptap/pm": "^2.27.3",
@@ -379,7 +379,7 @@
     "@types/markdown-it": "^14.2.0",
     "@types/node": "^26.6.5",
     "assemblyscript": "0.28.20",
-    "fast-check": "^3.23.2",
+    "fast-check": "^4.10.2",
     "mermaid": "12.2.0",
     "tiptap-markdown": "^0.8.10",
     "tsup": "^9.0.0",

package/skills/pixerate-canvas/SKILL.md

@@ -107,6 +107,19 @@ batching and error codes.
 | `canvas_select` | Replace the selection (an empty list clears it). Use it to show the user a result and to target commands that act on the selection. |
 | `canvas_highlight` | Flash nodes to point the user at them: `color` (default `#3b82f6`), `durationMs` (default 2000, max 60000). Changes nothing. |
 
+### Explode and collapse
+
+Hosts with expandable nodes (a task that opens into subtasks, a Gantt bar into its steps) add these.
+Exploding shows the node's child nodes and moves the surrounding nodes to make room; collapsing
+removes the children and puts the moved nodes back. It is a view change, not an edit: it is not an
+undo step and is not saved with the document. The host decides what the children are.
+
+| Tool | Use it to |
+| --- | --- |
+| `list_explodable_nodes` | List the nodes that can explode (`id`, `label`, `exploded`, `collapsing`), the ids `exploded` and `collapsing` now, whether several can be open at once (`multiple`), and the `readOnly` reason if exploding is disabled. Call it first: it is the only source of explodable ids. |
+| `explode_node` | Explode `node` (an id from `list_explodable_nodes`). Unless `multiple`, the node exploded before collapses (it comes back in `collapsed`). Exploding an exploded node changes nothing (`changed: false`). Returns the ids now `exploded`. Then use `get_editor_state` or `capture_view` to read or see the children. |
+| `collapse_node` | Collapse an exploded `node`. Returns the ids still `exploded` and those still `collapsing` (their children leave when the collapse animation ends). Fails when the node is not exploded. |
+
 ### Write: components
 
 These are strict-schema tools. Each returns `{ ids }` of what it created or changed, or fails with
@@ -288,6 +301,9 @@ effects provider (for example Flair); without one the read tools say so and the
 - With agent playback on, the cursor clicks where `canvas_add_node` will place the node, drags
   `canvas_connect` from source to target, and rings the nodes a layout or arrange command moved.
   Nothing about the calls changes: still read ids with `get_editor_state` and pass them back.
+- **Exploded children are temporary.** Do not edit, connect or lay out nodes that only exist
+  while a node is exploded: they vanish on collapse. Collapse before `canvas_layout`, and do not
+  save positions read while a node is exploded (the moved nodes return to their old places).
 - `canvas_update_node` changes `data` only. Move nodes with layout, align or distribute commands,
   or by the host's own means; do not expect `position` inside `data` to move anything.
 - Align needs at least two nodes and distribute at least three; locked nodes never move. Shape

package/skills/pixerate-chart/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-chart
-description: How to build, edit and check charts in the Pixerate chart editor through its agent tools and chart.* commands - bar, column, line, area, scatter, bubble, pie, donut, radar, waterfall, histogram, box plot, funnel and treemap charts; series, categories, stacking, secondary axis, log axis, number formats, data labels, legend, trendline, error bars, colour palettes and colour-blind checks, CSV and Mermaid import, Office chart XML export, and reading charts out of open .xlsx, .pptx and .docx files. Use when a chart editor's tools (get_chart, update_chart, set_chart_values, list_file_charts...) are available or the user asks to make, restyle, fix or explain a chart.
+description: How to build, edit and check charts in the Pixerate chart editor through its agent tools and chart.* commands - bar, column, line, area, scatter, bubble, pie, donut, radar, waterfall, histogram, box plot, funnel, treemap (flat or grouped), sunburst, slope, Likert (survey) and parliament charts; series, categories, stacking, secondary axis, log axis, number formats, data labels, legend, trendline, error bars, reference lines and target bands, callouts, highlighting, footnotes, colour palettes and colour-blind checks, CSV and Mermaid import, Office chart XML export, and reading charts out of open .xlsx, .pptx and .docx files. Use when a chart editor's tools (get_chart, update_chart, set_chart_values, list_file_charts...) are available or the user asks to make, restyle, fix or explain a chart.
 ---
 
 # Charts
@@ -10,10 +10,19 @@ A chart editor holds one `ChartSpec`: a `type`, `title` / `subtitle`, `xAxis` /
 a list of `categories` (strings, in order) and a list of `series`. Each series has an `id`
 (such as `series-1`), a `name` and one value per category (`null` is a gap), plus optional
 per-series settings (type for combos, secondary axis, marker, colour, format, trendlines,
-error bars). Tools take a series by id or exact name and a category by 0-based index or
-exact label; `get_chart` returns both. Pie, donut, funnel and treemap draw only the first
-visible series, one slice per category; histogram and box read every value of the visible
-series.
+error bars, callouts). Annotations sit on the spec: `note` (footnote), `highlight` (names of
+categories and series to keep bright), `referenceLines`, `referenceBands` and `varyColors`. Tools take a series by id or exact name and a category by 0-based index or
+exact label; `get_chart` returns both. Pie, donut, funnel, treemap and parliament draw only
+the first visible series, one slice (or group of seats) per category; histogram and box read
+every value of the visible series. A slope chart joins the first series (before) to the
+second (after) for each category; a Likert chart reads each category as a question and the
+series as its answers, ordered from most negative to most positive.
+
+Grouped data lives in `spec.tree` (items `{name, value}`, groups `{name, children}`, up to 6
+levels). When a tree is set it *is* the data: the categories are its top-level group names
+and the first series their totals, so a treemap nests the groups, a sunburst draws them as
+rings, and any other type draws the totals. Nodes are addressed by `path`, the names from the
+top down (`["Europe", "France"]`); `get_chart` returns them as `treeTable`.
 
 Read `pixerate-agent-tools` first for tool naming, errors and `run_commands` batching.
 Charts inside a rich-text document are not edited with these tools: use `insert_chart`,
@@ -34,10 +43,15 @@ Charts inside a rich-text document are not edited with these tools: use `insert_
 4. **Style in one call.** Put type, titles, axes, legend, stacking and labels in a single
    `update_chart`; it is all-or-nothing and one undo step. Use `apply_chart_preset` for a
    coherent layout or colour scheme, `update_chart_series` for per-series settings.
-5. **Check.** Read the `warnings` that `get_chart` and `render_chart` return (hidden or
+5. **Point the reader at the message.** Once the data and style are right, annotate:
+   `add_chart_reference_line` for a target or average, `add_chart_reference_band` for a
+   normal or target range, `set_chart_callout` on the one or two points the title talks
+   about, `highlight_chart` to mute what does not matter, and `note` (in `update_chart`) for
+   the source.
+6. **Check.** Read the `warnings` that `get_chart` and `render_chart` return (hidden or
    thinned labels, crowded legend, skipped values) and run `check_chart_colors`. Fix every
    problem.
-6. **Look once.** `render_chart` with `format: "png"` after a batch of edits, at the size
+7. **Look once.** `render_chart` with `format: "png"` after a batch of edits, at the size
    the chart will be shown, to check overlap and legibility. Use `undo_chart` for your own
    mistakes.
 
@@ -49,7 +63,15 @@ Charts inside a rich-text document are not edited with these tools: use `insert_
   stacked bar or `stacking: "percent"` for shares across groups; pie or donut only for one
   whole with few parts. Distribution: histogram (`bins`, default the square root of n) or
   box. Relationship: scatter with `series.x`, bubble with `sizes` for a third measure.
-  Running totals and bridges: waterfall (`showTotal`). Staged drop-off: funnel.
+  Running totals and bridges: waterfall (`showTotal`). Staged drop-off: funnel. What rose
+  and what fell between two points in time: slope (two series, the names are the column
+  captions). Agree-to-disagree survey answers: likert (`likertSort: "positive"` ranks the
+  questions; `likertNeutral: "separate"` keeps the middle answer out of the comparison).
+  Parts of parts (regions → countries, budget → departments → teams): a treemap with grouped
+  data for comparing sizes, a sunburst for showing the levels (`sunburstLabel` captions the
+  total in the middle). Load the levels with `import_chart_tree_csv` or `set_chart_tree`.
+  Seats or votes per group with a majority: parliament (`parliamentMajority`,
+  `parliamentArc`, `parliamentLabel`).
 - **Bars start at zero.** Bar length encodes the value, so never set a non-zero `min` on the
   value axis of a bar, column or area chart. Line and scatter charts may zoom to the data
   range when the change, not the magnitude, is the point.
@@ -81,6 +103,19 @@ Charts inside a rich-text document are not edited with these tools: use `insert_
   (`showR2`) and read it with `get_chart_trendline` before describing the trend; label any
   `forward` forecast as a projection. Exponential, power and log fits need positive values;
   category charts fit against x = 1, 2, 3.
+- **Annotate sparingly.** One or two reference lines, one band and a couple of callouts at
+  most; every label competes with the data. Label every reference line (`label`) so the
+  reader knows what it is, and keep callouts to a few words that say *why* the point
+  matters ("Launch", "Strike"), not its value (that is what data labels are for).
+- **Highlight instead of recolouring.** To show one bar or series against the rest, use
+  `highlight_chart` (it mutes the rest and keeps the palette) rather than greying series by
+  hand. Name categories to pick bars or points, series to pick whole lines. Clear it with
+  `names: []`.
+- **One series, many categories:** `varyColors: true` gives each bar its own palette colour
+  and a category legend. Use it only when colour carries meaning (brands, teams); a ranked
+  bar chart reads better in one colour.
+- **Cite the source** in `note` ("Source: ONS, 2025"); it sits under the chart, apart from
+  the title.
 - **Error bars:** say what they are (standard deviation, standard error, confidence) in the
   title or subtitle.
 
@@ -109,7 +144,7 @@ it changed.
 
 | Tool | Use it to |
 | --- | --- |
-| `update_chart` | Change presentation in one all-or-nothing call: `type`, `title`, `subtitle`, `xAxis` / `yAxis` / `yAxis2` (show, title, min, max, step, gridlines, format, kind `"date"`, scale `"log"`, logBase, reverse), `legend` (show, position top / bottom / left / right), `stacking` (none / stacked / percent), `orientation`, `curve`, `points`, `dataLabels`, `labelPosition`, `palette`, `innerRadius` (donut hole, 0-0.9), `gapWidth`, `overlap`, `bins`, `showTotal`, `radarTicks` (radar ring count 1-50, null for round numbers), `radarGraticule` (radar rings as `polygon` or `circle`). Invalid values change nothing and come back as sentences. Returns the spec. |
+| `update_chart` | Change presentation in one all-or-nothing call: `type`, `title`, `subtitle`, `xAxis` / `yAxis` / `yAxis2` (show, title, min, max, step, gridlines, format, kind `"date"`, scale `"log"`, logBase, reverse), `legend` (show, position top / bottom / left / right), `stacking` (none / stacked / percent), `orientation`, `curve`, `points`, `dataLabels`, `labelPosition`, `palette`, `innerRadius` (donut hole, 0-0.9), `gapWidth`, `overlap`, `bins`, `showTotal`, `radarTicks` (radar ring count 1-50, null for round numbers), `radarGraticule` (radar rings as `polygon` or `circle`), `note` (footnote, "" for none), `highlight` (whole list of names), `referenceLines` / `referenceBands` (whole lists; prefer the add tools), `varyColors` (one colour per category on a one-series chart), `likertNeutral` (`split` / `separate`), `likertSort` (`none` / `positive` / `negative`), `parliamentArc` (90-360 degrees), `parliamentMajority` (seats, null for half plus one), `parliamentLabel` (caption under the total), `sunburstLabel` (caption under a sunburst's total). Invalid values change nothing and come back as sentences. Returns the spec. |
 | `set_chart_data` | Replace `categories` and / or all `series` (each with `name`, `values` and optional settings). Values are padded with gaps to the categories. Use for whole tables and for re-sorting. Returns the table and series ids. |
 | `set_chart_values` | Set individual `cells` (`series`, `category`, `value`) all-or-nothing. Values may be numbers, numeric text (`"1,200"`, `"12%"`, `"$40"`, `"(3)"`) or `null` for a gap. Returns the stored values. Acted out with a cursor when the host has a director. |
 | `add_chart_series` | Add a series (`name` required; `values`, `color`, `type` for a combo, `axis: "secondary"`, `x` / `sizes` for scatter and bubble, marker, format, error bars, `id`, `at`). Selects it and returns its id. |
@@ -123,6 +158,19 @@ it changed.
 | `load_file_chart` | Replace the editor's chart with one from an Office file (`file` or `data`, `chartId`). Returns the spec, read problems and the features the editor could not keep; tell the user about any. |
 | `add_chart_trendline` | Fit a trendline to a series (`type`: linear, exponential, logarithmic, power, polynomial with `order` 2-6, moving-average with `period`; `forward` / `backward` in x units, `intercept`, `showEquation`, `showR2`). Unstacked bar, line, area, scatter and bubble charts only. Returns its index, coefficients, R2 and equation. |
 | `remove_chart_trendline` | Delete a trendline by `series` and `index`. |
+| `add_chart_reference_line` | Draw a dashed line across the plot at `value` (a target, floor or average) with an optional `label`, `color` and `axis` (`y` default, `y2` for the secondary axis, `x` for numeric x on scatter and bubble). Bar, line, area, scatter and bubble charts; the axis grows to keep it in view. Returns its `index`. |
+| `update_chart_reference_line` | Change a reference line by `index` (from `add_chart_reference_line` or `spec.referenceLines`); `null` removes the label, colour or axis. Returns the line as stored. |
+| `remove_chart_reference_line` | Delete a reference line by `index`; later ones move up. Returns the rest. |
+| `add_chart_reference_band` | Shade a range from `from` to `to` (a target or normal range) under the data, with an optional `label`, `color` and `axis`. Same charts as reference lines. Returns its `index`. |
+| `update_chart_reference_band` | Change a reference band by `index`; `null` removes the label, colour or axis. |
+| `remove_chart_reference_band` | Delete a reference band by `index`. Returns the rest. |
+| `set_chart_callout` | Pin a short `label` to one bar or point (`series`, `category`) with a leader line; `label: null` removes it. The point needs a value. Bar, line, area, scatter and bubble charts. Selects the point. |
+| `highlight_chart` | Keep the named categories and series (`names`) bright and mute everything else; `[]` clears it. Unknown names change nothing and are listed. Returns the matched category indexes and series ids. |
+| `set_chart_tree` | Replace the data with grouped data (`tree`: items `{name, value}`, groups `{name, children}`, up to 6 levels, sibling names unique) for grouped treemaps and sunbursts; `[]` goes back to plain data and keeps the totals. Returns the tree, group totals and depth. |
+| `import_chart_tree_csv` | Replace the data with grouped data from CSV / TSV: names in every column but the last (group, ..., item), the value last; a blank group name repeats the one above. The quickest way to load a spreadsheet's hierarchy. |
+| `add_chart_tree_node` | Add an item or a group (`node`) under the group at `parent` (a path; `[]` for the top level) at `at`. Returns its `path` and the parent's new total. |
+| `update_chart_tree_node` | Rename a node, set an item's `value`, or set a node's `color` (null for the palette) by `path`. Groups have no value of their own. Returns the path (new after a rename). |
+| `remove_chart_tree_node` | Delete a node and everything under it by `path`. Returns the group totals left. |
 | `apply_chart_preset` | Apply a quick `layout` and / or a `colors` scheme from `list_chart_presets` in one step. |
 | `transpose_chart` | Swap series and categories. Drops per-series colours and settings, so restyle afterwards. |
 | `select_chart_element` | Select part of the chart (`kind`: none, chart, title, subtitle, legend, axis, series, point, category, trendline) for the user to see or before `press_chart_key`. |
@@ -166,6 +214,19 @@ several charts may register them with another prefix.
 | `chart.removeCategory` | Delete a category by index or label. |
 | `chart.addTrendline` | Fit a trendline (as `add_chart_trendline`). |
 | `chart.removeTrendline` | Delete a trendline. |
+| `chart.addReferenceLine` | Add a reference line (as `add_chart_reference_line`). |
+| `chart.updateReferenceLine` | Change a reference line by index. |
+| `chart.removeReferenceLine` | Delete a reference line by index. |
+| `chart.addReferenceBand` | Add a reference band (as `add_chart_reference_band`). |
+| `chart.updateReferenceBand` | Change a reference band by index. |
+| `chart.removeReferenceBand` | Delete a reference band by index. |
+| `chart.setCallout` | Pin or remove a point's callout (as `set_chart_callout`). |
+| `chart.highlight` | Highlight categories and series (as `highlight_chart`). |
+| `chart.setTree` | Replace the grouped data (as `set_chart_tree`). |
+| `chart.importTreeCsv` | Replace the data with grouped data from CSV / TSV. |
+| `chart.addTreeNode` | Add an item or group; returns its path. |
+| `chart.updateTreeNode` | Rename, revalue or recolour a node by path. |
+| `chart.removeTreeNode` | Delete a node by path. |
 | `chart.applyPreset` | Apply a quick layout and / or colour scheme. |
 | `chart.transpose` | Swap series and categories. |
 | `chart.importCsv` | Replace data from CSV / TSV (no automatic chart type). |
@@ -190,6 +251,28 @@ several charts may register them with another prefix.
 - Percent-stacked charts, pies and gaps cannot be dragged; use `set_chart_values`.
 - Radar needs at least three categories (it draws as a line chart until then); trendlines
   are refused on stacked charts, pies and the other single-series families.
+- Likert answers must be entered in order, most negative first: the chart puts the first
+  half left of the centre line and colours them orange, the last half right in purple.
+  Values are counts or shares; each question is scaled to its own total.
+- A slope chart needs exactly two visible series; with one it draws a line chart (a
+  `type-fallback` warning), and a third is not drawn. Hide the extra series or move them.
+- Parliament seats are rounded to whole numbers; more than 2,000 seats are not drawn.
+- While a chart has grouped data, cell edits (`set_chart_values`, adding, renaming or deleting
+  categories, `transpose_chart`) are refused, because the totals come from the tree. Edit the
+  nodes, or replace the data (`set_chart_data`, `import_chart_csv`), which clears the tree.
+- Highlight, selection and colours work per top-level group: every item in a group selects
+  and highlights that group. Give a node its own `color` with `update_chart_tree_node`.
+- Office export writes a grouped treemap or sunburst as a pie or doughnut of the group totals
+  (DrawingML has no hierarchy); Office chartex imports keep the levels.
+- Reference lines, bands and callouts are drawn on bar, line, area, scatter and bubble
+  charts only. Switching to another type keeps them in the spec but leaves them out of the
+  drawing (an `annotations-skipped` warning says so); they come back when you switch back.
+- Reference values on a log axis must be above 0, and `axis: "y2"` needs a visible series on
+  the secondary axis. A line outside a fixed `min` / `max` is not drawn.
+- Callouts and highlight names follow the data: removing a category drops its callouts and
+  its highlight entry, renaming a category or series keeps it highlighted.
+- Office export has no reference lines, bands, callouts, highlight or note; `export_chart_ooxml`
+  lists them as not written. `varyColors` is kept.
 - Radar `radarTicks` and `radarGraticule` are Mermaid's `ticks` and `graticule`. A
   `radar-beta` block with no `graticule` line imports as `circle`, because that is what
   Mermaid draws; set `radarGraticule: "polygon"` if the user wants the editor's default look.

package/skills/pixerate-paint-editor/SKILL.md

@@ -420,8 +420,6 @@ for the controls and presets.
 | `export_psd` | Export a PSD with every layer, the paper as a locked bottom layer, and the composite. Pigment and painterly modes are written as their nearest standard mode (`list_blend_modes` `psd`). Returns base64, size, `psb` and `warnings`. |
 | `export_time_lapse` | Repaint the painting from its recorded strokes and events as a time-lapse: `frames` (about how many), `fps`, `maxSide`, `wetStepsPerFrame` (frames while wet paint flows), `holdMs`. Returns a contact sheet image, the frame count, size, duration, a video project of the frames and the ffmpeg command that renders `timelapse.mp4`; `includeFrames` adds every frame as base64 PNG. Changes nothing. |
 | `export_high_res` | Repaint the painting from its strokes at `scale` 1..8 (brushes, grain, fills and wet events scaled): a PNG with real detail instead of upscaled pixels. Returns base64, size. Layers not painted with strokes come out empty. |
-| `save_document` | Deprecated, kept for one minor version: use `get_paint_document` or `save_paint_document`. Returns the document JSON with PNG data URLs inline (large). |
-| `open_document` | Deprecated, kept for one minor version: use `load_paint_document` or `open_saved_paint_document`. Opens a document JSON from `save_document`, clearing the undo history. |
 
 ### Save and open