@pixerate/editor 0.79.0 → 0.81.0

package/skills/pixerate-canvas/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: pixerate-canvas
+description: How to build and edit a Pixerate design canvas or node graph through its agent tools - adding, connecting, updating and laying out nodes (canvas_add_node, canvas_layout), reading state with get_editor_state and looking at it with view_editor, reusable components with variants, instances and overrides (create_component, add_variant, set_instance_properties), align, distribute, lock and layer order, shape boolean operations (unite, subtract, offset path, outline stroke), auto layout frames, and keyframe animation with easing and CSS export. Use when working on a canvas, whiteboard, flow chart, node graph, frame, design system, component library, button variants, layout, alignment, z-order or a canvas animation in a Pixerate editor.
+---
+
+# Pixerate canvas
+
+The canvas is an xyflow (React Flow / SvelteFlow) graph: an array of **nodes** and **edges**.
+A node is `{ id, type, position: { x, y }, width?, height?, parentId?, zIndex?, data }`; edges are
+`{ id, source, target, label? }`. Everything a design feature knows lives in `node.data`, so it
+survives copy, paste and JSON:
+
+- `data.label` / `data.name`: text content and layer name. `data.shape`: a shape node
+  (`{ kind: rect | ellipse | polygon | star | path, fill, stroke, strokeWidth, ... }`).
+- `data.layout`: an auto layout frame (`mode` horizontal / vertical / grid, `gap`, `padding`,
+  `alignMain`, `alignCross`, `sizing`); its children are the nodes whose `parentId` is the frame,
+  in node-array order. `data.childLayout`: a child's sizing (fixed / hug / fill) and constraints.
+- `data.component` (a main component), `data.componentSet` (a set of variants),
+  `data.instance` (`{ componentId, properties }`) and `data.componentOverrides`.
+- `data.locked`, `data.animation` (keyframe tracks), `data.tokenBindings` (design tokens).
+
+Positions are in canvas (flow) units; a child's position is relative to its parent. Node ids come
+from `get_editor_state`; component and set ids from `list_components`. Tools that take `ids` or
+`id` default to the current selection when you leave them out, so pass ids explicitly unless you
+just selected with `canvas_select`. See `pixerate-agent-tools` for namespacing, `run_commands`
+batching and error codes.
+
+## Working method
+
+1. **Read.** `get_editor_state` with `includeDocument: false` returns `canvas.nodes` and
+   `canvas.edges`. For a design system also call `list_components`, and `inspect_instance` before
+   changing an instance.
+2. **Plan the structure first**: which frames, which reusable components and variants, what
+   spacing scale. Build the main component once, then place instances; do not copy nodes by hand.
+3. **Write.** Use the dedicated tools for graph edits (`canvas_add_node`, `canvas_connect`,
+   `canvas_update_node`) and components (`create_component`, `create_instance`, ...). Use
+   `run_commands` with `atomic: true` for arrange, shape and animation commands, and whenever
+   several steps should be one undo step (a param `"$0.ids[0]"` uses an id an earlier step returned).
+4. **Tidy.** `canvas_layout` for graphs; `canvas.align*` / `canvas.distribute*` for designs;
+   layer order with `canvas.bringToFront` and friends; lock finished backgrounds with `canvas.lock`.
+5. **Look.** `view_editor` (default viewport, JPEG, 1024 px) once a batch is done; use
+   `scope: "canvas"` for the whole drawing. Fix overlaps, misalignment and clipped text, then show
+   the user with `canvas_select` or `canvas_highlight`.
+
+## Best practices
+
+- **Design-system thinking.** Anything that appears twice should be a component: build one main,
+  `combine_as_variants` for states and sizes (`State=Default`, `State=Hover`, `Size=Small`), then
+  `create_instance` everywhere. Change the main to change every instance; use overrides only for
+  per-use content (label text, an icon swap). Name variant properties and values consistently
+  (Title Case property, short values) and keep combinations unique.
+- **Name layers that must survive a variant switch** with a stable `data.name`. Matching falls
+  back to `data.label`, which for text is its content and differs between variants.
+- **Use component properties, not detaching.** Switch variants and set text or boolean
+  properties with `set_instance_properties`; `swap_instance` for another component. Detach only
+  when the instance must stop following its main.
+- **Spacing scale.** Pick a base unit (4 or 8) and use multiples for gaps and padding. Put rows
+  and stacks in auto layout frames (`data.layout`) instead of positioning children by hand, so
+  they reflow when content changes.
+- **Alignment and distribution.** Align to a shared edge or centre, then distribute with equal
+  gaps; a design reads as ordered when edges line up. Lock a node you want as the anchor: locked
+  nodes never move but still count towards the selection bounds.
+- **Layering.** Backgrounds at the back, content above, overlays on top. Use the restack
+  commands; they set `zIndex` per sibling group and never reorder the array.
+- **Graph layout.** Lay flows out in one direction (`LR` for pipelines, `TB` for hierarchies),
+  keep edges short, label edges only when the relationship is not obvious.
+- **Motion.** Use ease-out (or `ease-out-back` for a little overshoot) for things arriving,
+  ease-in for things leaving, ease-in-out for moves between two resting places, and `linear` only
+  for continuous motion such as rotation. Keep UI transitions around 150 to 400 ms and entrances
+  under about 600 ms; stagger related elements by 30 to 80 ms with `delay` rather than moving
+  everything at once. Animate `opacity`, `x`, `y`, `scale` and `rotation`; colour tweens
+  interpolate in OKLab.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_editor_state` | Read the canvas graph (`canvas.nodes`, `canvas.edges`) and, by default, the prompt document too. Pass `includeDocument: false` on a canvas-only task to keep the result small, `includeCanvas: false` for only the prompt. Call it first and again after edits made by the user. |
+| `view_editor` | Get an image of the editor: `scope` `viewport` (default) or `canvas` (the whole drawing's bounds), `format` `jpeg` (default) or `png`, `maxEdge` in pixels (default 1024). Use it after a batch to judge overlap, balance and legibility; agent cursors are left out. |
+| `list_components` | List main components (id, name, variant values, instance count) and component sets with their variant options. Call it before `create_instance`, `swap_instance` or any variant tool to get ids and the exact property names and values. |
+| `inspect_instance` | Describe one instance (or a layer inside it; default the first selected node): its main, variant, component property values with types, and per-layer overrides. Call it before `set_instance_properties` or `reset_overrides` so you use the right property names and override groups. |
+
+### Write: graph
+
+| Tool | Use it to |
+| --- | --- |
+| `canvas_add_node` | Add a node: `node` (`id` optional and must be unused, `type` registered by the host, `data`, `position`, `width`, `height`, `parentId` for a frame). Leave `position` out to auto-place it without overlaps beside `nearNodeId` on `side` (default `right`), which also connects an edge from that node, or beside the last node. Returns the new node id and edge id. |
+| `canvas_connect` | Add an edge from `source` to `target` (two different existing nodes), with an optional `label`. Returns the edge id. |
+| `canvas_update_node` | Merge fields into a node's `data` (for example `{ "label": "Checkout" }`). Treat the merge as shallow: pass nested objects such as `shape` or `layout` whole. It does not move or resize nodes. |
+| `canvas_remove_nodes` | Delete nodes and their edges; every id must exist. Destructive: confirm with the user before removing content they made. |
+| `canvas_layout` | Arrange the graph automatically: `direction` `LR` (default), `TB`, `RL` or `BT`. `incremental` (default true) keeps nodes that already have a position; pass `false` to re-lay everything. Nodes at exactly (0, 0) count as unplaced. |
+| `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. |
+
+### Write: components
+
+These are strict-schema tools. Each returns `{ ids }` of what it created or changed, or fails with
+the reason (for example a variant combination that already exists, or a cycle).
+
+| Tool | Use it to |
+| --- | --- |
+| `create_component` | Turn one frame-like node (`ids`) into a main component, or wrap several sibling layers in a new component frame. Returns the component id. |
+| `combine_as_variants` | Wrap sibling components in a component set. Names already in `Property=Value` form become variant values; others get `Property 1=Default`, `Variant2`, ... Rename afterwards with `rename_variant_property` / `rename_variant_value`. |
+| `create_instance` | Place an instance of `componentId` (a component, or a set's default variant), optionally inside frame `parentId`, at `x` / `y` (canvas coordinates, or relative to the parent), with `properties` (variant and component property values). Returns the instance id. |
+| `set_instance_properties` | Set property values on instances (`ids`): a variant property switches the variant (compatible overrides kept), a boolean toggles a layer, a text property sets text, an instance-swap property takes a component id. Get names from `inspect_instance`. |
+| `swap_instance` | Make instances show another component (`componentId`), keeping overrides on layers whose names match. |
+| `reset_overrides` | Reset overrides of a whole instance (default), of one layer (pass the layer as `id`), or one `group` such as `data.label` or `shape.fill`. Destructive. |
+| `push_overrides` | Copy an instance's overrides to its main component, and so to every other instance. Destructive for other instances' look: use it only when the user wants the change everywhere. |
+| `detach_instance` | Turn instances into plain frames that keep their look and stop following the main. Destructive; prefer properties or `swap_instance`. |
+| `go_to_main_component` | Select an instance's main component and get its id, to edit the main itself. |
+| `restore_main_component` | Recreate a deleted main component from one of its instances (its old id comes back, so other instances re-link). |
+| `add_variant` | Add a variant to set `setId` by duplicating `from` (default the set's default variant) with new `variant` values such as `{ "State": "Hover" }`; unnamed properties keep the source's values, a new property name is added to every variant as `Default`. `x` / `y` are optional (default next to the source). Without values the next `VariantN` is used. |
+| `remove_variant` | Remove variant `id` from its set (never the last one); its instances switch to the closest remaining variant, keeping overrides. Destructive. |
+| `set_variant_properties` | Merge `values` into variant `id`'s property values. A combination another variant has is refused. |
+| `rename_variant_property` | Rename property `name` to `newName` across a set; instances keep their variant. |
+| `rename_variant_value` | Rename `value` of `property` to `newValue` across a set; instances keep their variant. |
+
+## Commands
+
+Run these through `run_command` / `run_commands`. Each takes `ids` (default: the selection) unless
+noted, is one undo step, and reports in `list_commands` why it cannot run.
+
+### Arrange
+
+| Command | Use it to |
+| --- | --- |
+| `canvas.alignLeft` | Align the left edges of two or more nodes to the selection bounds. |
+| `canvas.alignCenter` | Align horizontal centres (a vertical centre line). |
+| `canvas.alignRight` | Align right edges. |
+| `canvas.alignTop` | Align top edges. |
+| `canvas.alignMiddle` | Align vertical centres (a horizontal centre line). |
+| `canvas.alignBottom` | Align bottom edges. |
+| `canvas.distributeHorizontal` | Give three or more nodes equal horizontal gaps; the outermost stay put. |
+| `canvas.distributeVertical` | Give three or more nodes equal vertical gaps. |
+| `canvas.lock` | Lock nodes: they cannot be moved, resized, restacked, deleted or combined, but stay selectable and act as alignment anchors. |
+| `canvas.unlock` | Unlock nodes, restoring their previous drag and delete flags. |
+| `canvas.bringForward` | Move nodes one step up among their siblings (past the next overlapping sibling). |
+| `canvas.sendBackward` | Move nodes one step down among their siblings. |
+| `canvas.bringToFront` | Put nodes on top of their siblings. |
+| `canvas.sendToBack` | Put nodes below their siblings (backgrounds). |
+
+### Shapes
+
+These act on shape nodes (`data.shape`) and replace their inputs with a new `path` shape (curves
+are kept exactly). They need unlocked shapes; other selected nodes are ignored.
+
+| Command | Use it to |
+| --- | --- |
+| `canvas.unite` | Merge two or more shapes into one outline. |
+| `canvas.intersect` | Keep only the area all shapes share; refused when they do not overlap. |
+| `canvas.subtract` | Cut every other shape out of the back-most one (stacking order decides which is the base). |
+| `canvas.exclude` | Keep the areas covered an odd number of times (XOR). |
+| `canvas.divide` | Split overlapping shapes into one shape per region, each painted like the top shape covering it. |
+| `canvas.offsetPath` | Grow (`distance` > 0) or shrink (< 0) shapes by `distance` canvas units (default 10), with `join` `miter` (default), `round` or `bevel` and `miterLimit` (default 4). |
+| `canvas.outlineStroke` | Turn shapes' strokes into filled shapes: `join` (default miter), `cap` `butt` (default), `round` or `square`, `miterLimit` (default 4). The fill stays as a separate shape below. |
+
+### Components (command form)
+
+The same operations as the component tools, for command palettes and `run_commands` batches.
+Prefer the dedicated tool for a single operation: its schema is strict and its errors precise. Use
+the command when you need it inside an atomic batch with arrange or animation steps, or when the
+host registered only commands.
+
+| Command | Use it to |
+| --- | --- |
+| `canvas.listComponents` | Read-only; same result as `list_components`. |
+| `canvas.inspectInstance` | Read-only; same as `inspect_instance` (`id`). |
+| `canvas.createComponent` | Same as `create_component` (`ids`). |
+| `canvas.combineAsVariants` | Same as `combine_as_variants` (`ids`). |
+| `canvas.createInstance` | Same as `create_instance` (`componentId`, `parentId`, `x`, `y`, `properties`). |
+| `canvas.setInstanceProperties` | Same as `set_instance_properties` (`properties`, `ids`). |
+| `canvas.swapInstance` | Same as `swap_instance` (`componentId`, `ids`). |
+| `canvas.resetOverrides` | Same as `reset_overrides` (`id`, `group`). |
+| `canvas.pushOverrides` | Same as `push_overrides` (`id`). |
+| `canvas.detachInstance` | Same as `detach_instance` (`ids`). |
+| `canvas.goToMainComponent` | Same as `go_to_main_component` (`id`). |
+| `canvas.restoreMainComponent` | Same as `restore_main_component` (`id`). |
+| `canvas.addVariant` | Same as `add_variant` (`setId`, `from`, `variant`, `x`, `y`). |
+| `canvas.removeVariant` | Same as `remove_variant` (`id`). |
+| `canvas.setVariantProperties` | Same as `set_variant_properties` (`values`, `id`). |
+| `canvas.renameVariantProperty` | Same as `rename_variant_property` (`name`, `newName`, `setId`). |
+| `canvas.renameVariantValue` | Same as `rename_variant_value` (`property`, `value`, `newValue`, `setId`). |
+
+### Animation
+
+A node's animation is a set of property tracks of keyframes `{ time (ms), value, easing }`; the
+easing applies to the segment leaving a keyframe. Animatable properties: `x`, `y`, `width`,
+`height`, `rotation` (degrees), `scale`, `opacity` (0 to 1), `fill`, `stroke`, `strokeWidth`,
+`cornerRadius`, `motionPath` (0 to 1). Easings: `linear`, `ease`, `ease-in`, `ease-out`,
+`ease-in-out`, `ease-in-back`, `ease-out-back`, `spring`, `hold`, or `cubic-bezier(x1, y1, x2, y2)`.
+
+| Command | Use it to |
+| --- | --- |
+| `canvas.animation.animateNode` | The main authoring command: animate `nodeId` from `from` (default: its current values) to `to` over `duration` ms (default 1000), starting at `delay` ms (default 0), with `easing`. Stagger several nodes with increasing `delay` in one atomic `run_commands`. |
+| `canvas.animation.addKeyframe` | Key nodes (`ids`, default selected) at `time` ms (default the playhead): the listed `properties`, else their animated ones, else `x` and `y`. Set the node's values first, then key. |
+| `canvas.animation.setEasing` | Set `easing` on the segments leaving the selected keyframes. Needs a keyframe selection. |
+| `canvas.animation.deleteKeyframes` | Delete the selected keyframes. Needs a keyframe selection. |
+| `canvas.animation.seek` | Move the playhead to `time` ms (required). Returns the time. |
+| `canvas.animation.play` | Start playback (refused when already playing). |
+| `canvas.animation.pause` | Pause playback (refused when not playing). |
+| `canvas.animation.togglePlay` | Play or pause; returns `playing` and `time`. |
+| `canvas.animation.stop` | Stop and return to the start. |
+| `canvas.animation.toggleRecord` | Toggle record mode, in which changing any property at the playhead keys it. Returns `recording`; turn it off when done. |
+| `canvas.animation.nextKeyframe` | Jump the playhead to the next keyframe. |
+| `canvas.animation.previousKeyframe` | Jump the playhead to the previous keyframe. |
+| `canvas.animation.exportCss` | Read-only: CSS `@keyframes` for `nodeId`'s animation, as `{ css, exact }`. `exact: false` means some tracks were sampled (OKLab colour tweens, `x` / `y` with different timing, motion paths). |
+
+## Pitfalls
+
+- `canvas_*` tools validate ids against the current state; an "Unknown node id" error means call
+  `get_editor_state` again, not guess.
+- `canvas_add_node` with `nearNodeId` also adds an edge from that node. Pass an explicit
+  `position` (and no `nearNodeId`) for a free-standing design element.
+- `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
+  booleans refuse locked shapes and empty results, and edges attached to consumed shapes are left
+  dangling: reconnect or remove them.
+- Subtract uses stacking order (back-most is the base), not selection order; restack first.
+- Instances never gain or lose layers. Deleting a layer inside an instance hides it; nodes added
+  inside an instance move out of it. Edit the main to change structure.
+- `push_overrides`, `detach_instance`, `remove_variant` and `reset_overrides` change other
+  instances or discard work; ask before using them on the user's design.
+- Variant edits refuse a combination another variant already has, empty names, and names
+  containing `,` or `=`.
+- An instance cannot be placed inside a component it contains (cycle); place it outside.
+- Animation times are milliseconds; `rotation` is degrees and `opacity` 0 to 1 (token bindings use
+  percent for opacity, animation does not).

package/skills/pixerate-chart/SKILL.md

@@ -0,0 +1,190 @@
+---
+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.
+---
+
+# Charts
+
+A chart editor holds one `ChartSpec`: a `type`, `title` / `subtitle`, `xAxis` / `yAxis` /
+`yAxis2`, `legend`, presentation fields (stacking, orientation, curve, data labels, palette),
+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.
+
+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`,
+`list_document_charts` and `update_chart_in_document` from the `pixerate-rich-text` skill
+(a chart block goes in the prose, never inside a table row).
+
+## Working method
+
+1. **Read.** `get_chart` returns the spec, the data as a table, the selection and a
+   summary at the given size (default 640 x 400): per-series min / max / mean / trend, the
+   axes as drawn, layout warnings, a colour check and a plain-language description. If the
+   data comes from a file, start with `list_open_files` and `list_file_charts`.
+2. **Choose the form.** Decide what question the chart answers, then call `recommend_chart`
+   (on the current data or on CSV you are about to import) and pick from its list.
+3. **Load data in one call.** Use `import_chart_csv` (with `chartType: "auto"` for a fresh
+   chart) or `set_chart_data` for whole tables, `set_chart_values` for individual cells.
+   Avoid adding categories and series one by one when you already have the table.
+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
+   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
+   the chart will be shown, to check overlap and legibility. Use `undo_chart` for your own
+   mistakes.
+
+## Best practices
+
+- **Pick the type by the question.** Comparison across categories: bar (horizontal with
+  `orientation: "horizontal"` for long labels or many categories). Change over time: line
+  (area when volume matters; set `xAxis.kind: "date"` for date categories). Composition:
+  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.
+- **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.
+- **Pie and donut: at most about five slices**, all positive, adding up to a meaningful
+  whole. Beyond that, use a sorted bar chart or merge small slices into "Other".
+- **Sort bars** by value (largest first) unless the categories have a natural order (time,
+  ranks, age bands). Reorder by sending the sorted table through `set_chart_data`.
+- **Limit colours.** Keep to about seven distinct series colours; beyond that, split into
+  small multiples or highlight one series and grey the rest (`color`, `pointColors`).
+  Run `check_chart_colors` after any palette change; the `okabe-ito` scheme in
+  `apply_chart_preset` stays distinct with colour-blindness. Do not encode meaning by
+  colour alone: add labels or markers (`marker`).
+- **Label directly.** With few series or few bars, prefer data labels (`dataLabels`,
+  `labelPosition: "auto"` drops labels that do not fit) and the `labelled` or `minimal`
+  layout over a legend plus grid. Always set a title that states the takeaway and axis
+  titles with units.
+- **Number formats.** Set `format` on the axis (and on series labels when they differ):
+  `style: "percent"` (0.25 shows as 25%), `"currency"` with `currency`, `"compact"` (1.2K),
+  fixed `decimals`, or a spreadsheet `code` such as `#,##0.0,,"M"`. Use the same format on
+  the axis and the labels; avoid more decimals than the data justifies.
+- **Honest dual axes.** Use `axis: "secondary"` only when two series have different units,
+  title both axes with those units, and make the series visibly different (bar plus line
+  via the series `type`). Never use a second axis to make two same-unit series look
+  correlated.
+- **Log scale** (`scale: "log"`) only for data spanning orders of magnitude or for growth
+  rates; say so in the axis title. It skips values of 0 or less and refuses percent
+  stacking.
+- **Trendlines are models, not data.** Add one only when a fit is meaningful, show R2
+  (`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.
+- **Error bars:** say what they are (standard deviation, standard error, confidence) in the
+  title or subtitle.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_chart` | Start here. Returns spec, data table, selection, issues and a summary (min / max / mean / trend, axes as drawn, layout warnings, colour check, description) at `width` x `height` px (default 640 x 400). Also says why when the chart is read-only. Cheaper than rendering. |
+| `render_chart` | Draw without changing anything: SVG text by default, or `format: "png"` for an image (only when the host can rasterize; otherwise it fails and says to use SVG). Returns the layout warnings too. Images cost tokens: render after a batch of edits, at the display size, to check overlapping or cut-off labels, a crowded legend and unreadable colours. |
+| `check_chart_colors` | Check the chart's series (or slice) colours, or a `colors` list, for normal vision, protanopia, deuteranopia and tritanopia, and contrast against `surface` (default white). Returns the closest pair per vision and problems as sentences. Run after any colour change. |
+| `recommend_chart` | Ranked chart types with a reason each, from `csv` when given, else the current data (series count, points, dates, negative values). Use before choosing a type. |
+| `get_chart_trendline` | Read a trendline's fit (`series`, `index`): coefficients, R2, equation and point count, or the moving-average points. Fails when the fit needs more or positive values. |
+| `list_chart_presets` | List the quick layouts (`standard`, `minimal`, `labelled`, `legend-right`, `presentation`, `analysis`) and colour schemes (such as `default`, `okabe-ito`, `office`, monochrome) with what each changes. |
+| `export_chart_mermaid` | Get the chart as Mermaid `xychart-beta`, `pie` or `radar-beta` for Markdown or chat. With `meta` (default true) a `%% @pixerate` comment keeps everything Mermaid cannot express so `import_chart_mermaid` restores it exactly. |
+| `export_chart_ooxml` | Get a DrawingML `c:chartSpace` part for Word or PowerPoint, plus sentences for anything that could not be written. |
+| `list_open_files` | List the Office files the user opened (name, size in bytes). Only registered when the host shares open files; otherwise the file tools take the whole file as base64 `data`. |
+| `list_file_charts` | List every chart in an `.xlsx`, `.pptx` or `.docx` (`file` name or base64 `data`) in file order: id (such as `chart-1`), place (sheet and anchor cell, or slide number), title, type, series names, category count, read problems, unsupported features and whether it reads losslessly. |
+| `get_file_chart` | Return one file chart's full spec (`file` or `data`, `chartId` from `list_file_charts`) with its place and read problems, without touching the editor. Data comes from the chart's cached values, not the embedded workbook. |
+
+### Write
+
+Write tools are hidden while the chart is read-only. Each is one undo step and returns what
+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`. 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. |
+| `update_chart_series` | Rename, recolour, hide, move to the secondary axis, change `type`, `marker`, `curve`, `dataLabels`, `format`, `x`, `sizes`, `pointColors`, `errorBars` / `xErrorBars` of one series; `null` resets a field. Values change with `set_chart_values`. |
+| `remove_chart_series` | Delete a series and its values. Returns the remaining series ids. |
+| `add_chart_category` | Insert a category (`label`, `at`; default the end) as a gap in every series. Returns its index; fill it with `set_chart_values`. |
+| `remove_chart_category` | Delete a category (index or label) and its value in every series. |
+| `import_chart_csv` | Replace the data with CSV or TSV text. Default: first row series names, first column categories (`seriesIn`, `header` change that). `chartType: "auto"` also picks the recommended type (two unlabelled numeric columns become a scatter). Returns the table, the type and cells that were not numbers. |
+| `import_chart_mermaid` | Replace the chart with Mermaid `xychart-beta`, `pie` or `radar-beta` text (fenced or bare). Unreadable lines are skipped and listed with line numbers. |
+| `import_chart_ooxml` | Replace the chart with a raw Office chart part (`c:chartSpace` or chartex XML). Only listed when the host has a `DOMParser` (every browser does). Prefer `load_file_chart` when you have the whole file. |
+| `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`. |
+| `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`. |
+| `drag_chart_point` | Drag a bar or point as the mouse would, with the same snapping (`fine` = Alt, `lockAxis` = Shift on scatter). Positions are 0-1 fractions of the chart at `width` x `height`; use `render_chart` to find marks. Prefer `set_chart_values` for exact numbers. |
+| `press_chart_key` | Send a key to the selection: ArrowLeft / ArrowRight move between categories, ArrowUp / ArrowDown change the value by a tenth of a tick (`shift` a whole tick, `alt` a hundredth), Delete / Backspace remove, Escape clears. |
+| `undo_chart` | Undo the last chart edit. Returns the label of what was undone and the next undo. |
+| `redo_chart` | Redo the last undone chart edit. |
+
+## Commands
+
+The `chart.*` commands (run with `run_command` / `run_commands`) mirror the tools. Prefer
+the dedicated tool: it has a stricter schema and returns more (`get_chart` adds the
+selection and read-only reason; `import_chart_csv` has `chartType: "auto"`;
+`check_chart_colors` takes colours and a surface). Use the commands inside an atomic
+`run_commands` batch when chart edits must roll back together with other edits, and for the
+two operations without a tool: `chart.exportSvg` and its fixed-size accessible SVG. Hosts with
+several charts may register them with another prefix.
+
+| Command | Use it to |
+| --- | --- |
+| `chart.describe` | Read spec, data table and summary (as `get_chart`). |
+| `chart.update` | Change presentation (as `update_chart`). |
+| `chart.setData` | Replace categories and series (as `set_chart_data`). |
+| `chart.setValues` | Set individual values (as `set_chart_values`). |
+| `chart.addSeries` | Add a series; returns its id (as `add_chart_series`). |
+| `chart.updateSeries` | Change a series' settings (as `update_chart_series`). |
+| `chart.removeSeries` | Delete a series by id or name. |
+| `chart.addCategory` | Insert a category at `at` (default the end). |
+| `chart.removeCategory` | Delete a category by index or label. |
+| `chart.addTrendline` | Fit a trendline (as `add_chart_trendline`). |
+| `chart.removeTrendline` | Delete a trendline. |
+| `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). |
+| `chart.importMermaid` | Replace the chart from Mermaid chart text. |
+| `chart.exportMermaid` | Get Mermaid text (with the round-trip comment unless `meta` is false). |
+| `chart.exportOoxml` | Get the DrawingML chart part. |
+| `chart.exportSvg` | Get a standalone, accessible SVG (title and desc) at `width` x `height` (default 640 x 400), for saving or embedding. |
+| `chart.recommend` | Suggest chart types for the data or `csv`. |
+| `chart.checkColors` | Check the chart's own series colours (no parameters). |
+| `chart.undo` | Undo the last chart edit. |
+| `chart.redo` | Redo the last undone chart edit. |
+
+## Pitfalls
+
+- Series values are positional: one value per category, in category order. After
+  `add_chart_category` or `remove_chart_category`, every series shifts with it.
+- `set_chart_data` with only `series` keeps the categories; with only `categories` it keeps
+  the series, whose values stay matched by position. Pass both to replace a table.
+- Non-numeric cells are refused by `set_chart_values` ("Nothing was changed"); CSV import
+  keeps going and lists them in `issues`. Check that list.
+- 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.
+- `transpose_chart` and `load_file_chart` drop or replace styling; restyle and re-check
+  colours afterwards.
+- A `%% @pixerate` comment is what makes Mermaid round-trip exactly. Keep it when the text
+  is going back into a Pixerate editor; pass `meta: false` only for plain Mermaid readers.
+- File charts are read from cached values; if the user edited the workbook without saving
+  the chart cache, the numbers can be stale. Say so when it matters.
+- An atomic `run_commands` batch only rolls back chart edits when the host shares one history
+  between the command registry and the chart; if a batch is refused for that, use the tools
+  one by one and `undo_chart`.
+- When the chart is read-only, only the read tools are listed and `get_chart` returns the
+  reason. Tell the user; do not try to edit around it.

package/skills/pixerate-diagram/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: pixerate-diagram
+description: How to build and edit Mermaid diagrams in the Pixerate diagram editor through its agent tools - flowchart, state, class, ER, sequence, Gantt, pie, mindmap, quadrant, C4, architecture, gitGraph, timeline, journey, XY and radar diagrams; adding, connecting, renaming, reshaping and styling nodes, edge labels, subgraphs and groups, layout direction (LR, TB), node and edge data fields, titles, canvas positions, finding Mermaid in Markdown, and rendering to check the result. Use when diagram tools (get_diagram, add_diagram_node, load_diagram_mermaid...) are available or the user asks for a flowchart, process map, state machine, sequence diagram, org or architecture diagram in Mermaid.
+---
+
+# Mermaid diagrams
+
+The diagram editor holds one Mermaid document. Its text is the source of truth: every edit
+rewrites only the statements it touches, and untouched statements, comments, directives and
+formatting round-trip byte for byte. Canvas positions live in one `%% @pixerate {...}`
+comment that Mermaid ignores.
+
+`get_diagram` describes the document as a graph: the `family` (flowchart, state, class, er,
+pie, mindmap, quadrant, c4, architecture, sequence, gitGraph, gantt, timeline, journey,
+xychart, radar), `direction`, `title`, `nodes` (Mermaid ids such as `A` or `n3`, label,
+shape, `parentId`), `edges` (ids such as `L_A_B_0`, source, target, label), `groups`
+(subgraphs, composite states, namespaces, sections, boxes, boundaries), the `shapes` the
+family allows, its data `fields` and current `settings`. Non-graph families map onto the
+same model: a pie slice, Gantt task, quadrant point or sequence participant is a node
+whose values live in `data`. Sankey, block, packet, kanban and treemap are kept as text
+only (`editable: false`): change them with `load_diagram_mermaid`.
+
+Read `pixerate-agent-tools` first for tool naming, errors and batching. Data charts (bar,
+line, pie with styling, trendlines) belong in the chart editor (`pixerate-chart`); Mermaid
+`xychart-beta`, `pie` and `radar-beta` text can move between the two.
+
+## Working method
+
+1. **Read.** `get_diagram` (with `includeSource: true` when you need the text). Note the
+   family, the ids, the allowed `shapes` and `fields`. For Mermaid in a user's Markdown or
+   chat, `find_mermaid_diagrams` first.
+2. **Plan the structure** before writing: the family, the flow direction, the nodes and
+   their kinds, the groups. Sketch it as Mermaid in your head.
+3. **Write.** For a new diagram or a rewrite, send the whole text once with
+   `load_diagram_mermaid`. For changes to an existing diagram, use the per-operation tools
+   (`add_diagram_node` with `from` to add and connect in one call, `rename_diagram_node`,
+   `connect_diagram_nodes`...): they keep the user's formatting and comments.
+4. **Check.** Read the returned ids and any `diagnostics`; fix parse problems before going
+   on.
+5. **Look.** `render_diagram` (`format: "png"` when offered) after a batch of edits to
+   check crossings, crowding and label length. Undo your own mistakes with `undo_diagram`.
+
+## Best practices
+
+- **Choose the family by the question.** Process or decision logic: flowchart. Lifecycle of
+  one thing with events: state. Messages between parties over time: sequence. Data model:
+  ER (tables and cardinality) or class (types and methods). Schedule: Gantt. System context
+  and containers: C4 or architecture. Brainstorm or hierarchy: mindmap. Two-axis
+  prioritisation: quadrant. History: timeline or gitGraph. Numeric series: the chart editor.
+- **One direction, matched to the content.** `LR` for processes and pipelines read like a
+  sentence; `TB` for hierarchies and decision trees. Set it once (`set_diagram_direction`);
+  do not mix directions except per-subgraph when a group is clearly separate.
+- **Concise labels.** Verb phrases for steps ("Validate order"), noun phrases for things,
+  short questions for decisions ("Paid?"), at most five or six words. Put conditions on the
+  edges leaving a decision ("yes" / "no"), not in the node. Stable short ids (`validate`,
+  `paid`) beat `A`, `B`, `C` when the user will read the source.
+- **Consistent shape semantics.** In flowcharts: `rounded` or `stadium` for start and end,
+  `rect` for steps, `diam` for decisions, `cyl` for data stores, `doc` for documents,
+  `subproc` for a call into another process, `lean-r` / `lean-l` for input and output. Use
+  each shape for one meaning only. In state diagrams use `choice`, `fork` and `join` for
+  branching and concurrency.
+- **Group to reduce noise.** Put related nodes in a subgraph (`group_diagram_nodes`) by
+  owner, system or phase (swimlane style); keep to one or two levels of nesting.
+- **Limit crossings and fan-out.** Keep each node to a few edges; order statements so the
+  main path runs straight; split very large diagrams (more than about 20-30 nodes) into an
+  overview plus detail diagrams rather than one dense graph. Every node should be reachable;
+  remove orphans.
+- **Style sparingly.** `set_diagram_node_style` to highlight the one or two nodes the
+  reader should look at (the error path, the changed step), not to decorate every node.
+  Keep enough contrast between fill and text, and do not rely on colour alone.
+- **Title it** (`set_diagram_title`) with what the diagram shows.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_diagram` | Start here. Returns family, editable flag, direction, title, nodes, edges, groups, allowed shapes, settings, data fields (`fields.node`, `fields.edge`, `fields.diagram` with types and ranges), stored positions, parse diagnostics, the selection and the read-only reason. `includeSource` (default false) adds the Mermaid text. |
+| `export_diagram_mermaid` | Get the Mermaid text to hand back to the user or paste into Markdown. `withLayout` (default true) keeps the `%% @pixerate` positions comment; pass false for plain Mermaid. |
+| `find_mermaid_diagrams` | Find every Mermaid diagram in a piece of `text` (fenced ```mermaid blocks, a chat reply or a bare diagram). Returns each source, family and title; pass one source to `load_diagram_mermaid`. Changes nothing. |
+| `render_diagram` | Draw the diagram without changing it: SVG text by default, `format: "png"` when the host can rasterize; `maxWidth` / `maxHeight` fit it in px. Only listed when the host can render. Refuses text-only families. Render after a batch of edits, not after each one. |
+
+### Write
+
+Write tools are hidden while the diagram is read-only. Each call is checked against the
+diagram first (unknown ids, taken ids, shapes the family lacks), applies as one undo step and
+returns what it created or changed. All but `load_diagram_mermaid` and undo / redo refuse
+text-only families.
+
+| Tool | Use it to |
+| --- | --- |
+| `load_diagram_mermaid` | Replace the whole diagram with Mermaid `source` (fenced or bare; must start with a header such as `flowchart LR`). Use for new diagrams, wholesale rewrites and text-only families. Returns family, editable flag, node and edge counts and diagnostics. Rewrites the user's formatting, so prefer the per-operation tools for small changes. |
+| `add_diagram_node` | Add a node with `label` (required); optional `id` (default the family's next free id), `shape`, `data` (family node fields), `parentId` (group), `from` plus `edgeLabel` to connect from an existing node, and `x` / `y` together in canvas px. Returns the node and any edge created. |
+| `remove_diagram_nodes` | Delete nodes (`ids`) and every edge touching them. A group id removes the group but keeps its contents. Returns removed node and edge ids. |
+| `rename_diagram_node` | Change the label of a node or group (`id`, `label`). |
+| `set_diagram_node_shape` | Change a flowchart or state node's `shape` to one of the names `get_diagram` lists (such as `rect`, `rounded`, `stadium`, `diam`, `cyl`, `circle`, `hex`, `doc`). |
+| `set_diagram_node_style` | Replace a node's inline Mermaid `styles` with `property:value` strings, e.g. `["fill:#fde68a", "stroke:#b45309", "stroke-width:2px"]`; an empty list removes them. |
+| `set_diagram_node_data` | Set node field values (`id`, `data`): a pie slice `value`, Gantt `start` / `end`, quadrant `x` / `y`, journey score, XY series values, C4 technology. Keys and types come from `fields.node`; `null` clears a field. |
+| `connect_diagram_nodes` | Draw an edge from `source` to `target` (existing node ids) with an optional `label`. Returns the edge id. |
+| `remove_diagram_edges` | Delete edges by `ids`; the nodes stay. |
+| `set_diagram_edge_label` | Set an edge's `label` by edge `id`; `""` removes it. |
+| `set_diagram_edge_data` | Set edge field values (`id`, `data`): sequence activation, C4 relation technology, architecture sides. Keys from `fields.edge`; `null` clears. |
+| `reconnect_diagram_edge` | Move an edge to a new `source` and `target`, keeping label and style. The returned edge id may change; use it from then on. |
+| `set_diagram_direction` | Set the flow `direction`: `TB` / `TD`, `BT`, `LR` or `RL`. Refused by families whose layout follows their data (pie, sequence, Gantt...). |
+| `set_diagram_title` | Set the `title` shown above the diagram, or `null` to remove it. |
+| `set_diagram_settings` | Set diagram-level fields (`data`): pie `showData`, Gantt `dateFormat` and `excludes`, quadrant axis labels, XY categories and axis range, sequence autonumbering. Keys from `fields.diagram`; `null` clears. |
+| `group_diagram_nodes` | Put `nodeIds` into a new group with `label` (optional `id`, default the next `G<number>`): a flowchart subgraph, composite state, class namespace, or the family's own group kind. Refused by families without groups (ER, pie, mindmap, quadrant, XY, radar). |
+| `ungroup_diagram_group` | Remove a group by `id`; its nodes move to the group's parent. |
+| `move_diagram_nodes` | Place nodes or groups on the canvas: `moves` of `{ id, x, y }` (top-left, canvas px). Stored in the `%% @pixerate` comment only; Mermaid statements and other renderers are unaffected. |
+| `undo_diagram` | Undo the last diagram edit; returns its label. |
+| `redo_diagram` | Redo the last undone diagram edit. |
+
+## Pitfalls
+
+- Ids are Mermaid ids, not labels. Always take them from `get_diagram` or from what a write
+  returned; a custom `id` must match `^[A-Za-z0-9_][\w.-]*$` and not be taken.
+- `load_diagram_mermaid` takes exactly one diagram. Text with several fenced diagrams is
+  refused; pick one with `find_mermaid_diagrams`. Text without a Mermaid header is refused
+  and nothing changes.
+- Shapes only apply to flowchart and state nodes; class and ER have none. A shape name not
+  in `get_diagram`'s `shapes` is refused.
+- Data tools check keys and types against the family's fields before changing anything.
+  Read `fields` first rather than guessing keys.
+- Moving one node of an auto-laid diagram can shift the others when the host does not pin
+  current positions; check with `render_diagram` after `move_diagram_nodes`, and prefer
+  letting the layout place nodes (omit `x` / `y`) unless the user asked for a position.
+- Mermaid label text with quotes, brackets or `#` may need quoting in the source; the
+  per-operation tools quote flowchart labels when needed, so prefer them over hand-written
+  text when labels contain punctuation, and check `diagnostics` after a `load_diagram_mermaid`.
+- `export_diagram_mermaid` with `withLayout: false` is for plain Mermaid readers; keep the
+  comment when the text will come back into a Pixerate editor.
+- When the diagram is read-only, only the read tools are listed and `get_diagram` returns
+  the reason. Tell the user; do not try to edit around it.