@pixerate/editor 0.80.0 → 0.81.0

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.

package/skills/pixerate-generation/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: pixerate-generation
+description: How to generate images, video, audio or text through Pixerate's AI generation tools safely - discovering models and their request schemas with list_models, checking a request with plan_generation (aspect ratio, resolution, quality, count, duration, seed, references with roles such as start_frame, style_ref, character_ref or mask, edit and inpaint modes), estimating cost and time with estimate_generation, starting a paid generation with generate and an idempotency key so retries never bill twice, and reusing past generations from the history (list_generations, recreate_generation, vary_generation) with drift reports. Use when asked to generate, render, create or edit media with an AI model, text-to-image, image-to-video, inpainting, or when list_models or generate are available.
+---
+
+# AI generation
+
+The generation tools front a host's model catalogue. Each model is a capability record (id,
+media kind `image` / `video` / `audio` / `text`, which request fields it supports and their
+options or ranges, which reference roles it accepts). A request is a plain object (`prompt`,
+`aspectRatio`, `resolution`, `quality`, `count`, `duration`, `seed`, `mode`, `references`,
+`params`, …); the planner checks it against the model, adjusts unsupported values per a
+`strategy`, and reports every change. `generate` costs money or quota and cannot be undone.
+See `pixerate-agent-tools` for errors and namespacing.
+
+- **Model ids** come only from `list_models`. Never guess one from a brand name.
+- **References** are assets the host already knows: `{ id, role, url?, mediaType?,
+  contentHash? }`. Ids come from the host (an asset library, an upload, a mention in the
+  prompt), never invented. Roles: `start_frame`, `end_frame`, `style_ref`, `character_ref`,
+  `background_ref`, `mask`, `image_ref`, `video_ref`, `audio_ref`, plus any role a model
+  declares; each model lists the roles it accepts and their min/max counts.
+
+## Working method
+
+1. **Discover.** `list_models` (filter with `media`) and read each candidate's `requestSchema`:
+   supported fields, enum options, ranges, prompt limits, reference roles.
+2. **Plan.** Build the request from the user's intent and call `plan_generation`. Read every
+   `adjustments` entry (`field`, `from`, `to`, `kind`, `reason`) and every `errors` entry. If
+   an adjustment changes what the user asked for (a different aspect ratio, a dropped
+   reference, fewer outputs), choose another model or tell the user before going on.
+3. **Estimate.** When `estimate_generation` is offered, call it with the same arguments. Report
+   the cost and time to the user and get confirmation when it is significant, when the user has
+   not already agreed to spend, or for any batch, high count, long video or top quality tier.
+4. **Generate once.** Call `generate` with the same `model`, `request`, `strategy` and a fresh
+   `idempotencyKey`. Return what it returns (typically a job id inside `result`) to the user.
+5. **On a timeout or transport error,** retry with the identical arguments and the same key.
+   Only change the key when you intend a new, separate generation.
+
+To redo or vary an earlier result ("make that one again", "same but wider", "another take"),
+find it with `list_generations`, inspect it with `get_generation`, and build the request with
+`recreate_generation` or `vary_generation`. They return `model` and `request` ready for
+`generate`, plus `drift`: tell the user about every `warning` or `error` item (an edited
+template, a model that changed, a missing reference) before spending. Then continue from step 3.
+
+## Best practices
+
+- **Plan before you pay.** `plan_generation` and `estimate_generation` are free and read-only;
+  `generate` is not. Never call `generate` to discover what a model supports.
+- **Pick the strategy deliberately.** `nearest` (default) snaps and clamps, ties up, and may
+  drop unsupported references; `downgrade` ties down (cheaper, smaller); `upgrade` never drops
+  references, so a lost reference becomes an error; `error` changes nothing and fails on any
+  mismatch. Use `error` or `upgrade` when exact settings or every reference matter (brand
+  work, a required start frame); use `nearest` for exploration.
+- **Write prompts for the medium.** Subject, then setting, composition and framing, lighting,
+  style and lens or medium; for video add camera motion and action over time. Put exclusions
+  in `negativePrompt` only when the model supports it (its schema says so). Keep the prompt
+  within the model's limit as resolved, not as written (see Pitfalls).
+- **Match the deliverable.** Choose `aspectRatio` and `resolution` for where the result will be
+  used (16:9 video, 9:16 stories, 1:1 thumbnails, 4:5 feeds) rather than cropping later.
+- **Explore cheap, finish expensive.** Draft at a low `quality` or `resolution` and small
+  `count`, then re-run the chosen direction at full quality with the same `seed` (when the
+  model supports seeds) for a closer match.
+- **Batch sensibly.** Prefer one request with `count: n` over n requests when the model
+  supports it. For genuinely different requests, give each its own key and estimate the total
+  first. Do not fan out dozens of paid calls without the user's go-ahead.
+- **Pass references with the right role.** A start frame for image-to-video as `start_frame`,
+  a look to copy as `style_ref`, a person or product to keep consistent as `character_ref`.
+  Editing needs `mode: "edit"` and a model with editing; inpainting needs `mode: "inpaint"`
+  plus a `mask` reference.
+- **Keep provenance.** Record the model id, the planned request and seed the tools returned,
+  so the user can reproduce or vary a result.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `list_models` | List available models: `id`, `media`, optional `name`, `description`, `badges`, and the `requestSchema` (JSON Schema of the request fields, options, ranges and reference roles it accepts). Optional `media` filter: image, video, audio or text. Call first; the list can change while you work. |
+| `plan_generation` | Check a request without generating. Takes `model`, `request`, optional `strategy` (nearest default, upgrade, downgrade, error) and `resolvedPrompt`. Returns `plan`: `ok`, the adjusted `request`, `adjustments` (snapped, clamped, truncated, dropped, defaulted, each with a reason) and `errors`. Fix every error before estimating or generating. |
+| `list_generations` | Find past generations (newest first): id, model, kind (generate, recreate, variation), parent, time, templates, assets and a 160-character prompt preview. Filter by `model`, `template`, `text`, `kind` or `parentId`; page with `limit` (default 20, max 100) and `offset`. Returns `total` too. |
+| `get_generation` | Read one record by `id`: raw and resolved prompt, the settings as the user set them, strategy, the seed used, assets, templates and parent. Use it to answer what was used, or before a recreate. |
+| `recreate_generation` | Build (not run) the request that reproduces a record. `mode` `exact` (default) keeps the recorded prompt and settings; `latest` uses current templates and re-plans for the current model. Returns `ok`, `model`, `request`, `resolvedPrompt`, `drift` and any `planErrors`. Pass `model` and `request` to `generate` with a new key. |
+| `vary_generation` | Build (not run) a variation: the same prompt, settings and assets with a new `seed` (random unless given, `null` for none), `values` for prompt variables, `settings` merged over the recorded ones, or a new `rawPrompt`. Same result shape as `recreate_generation`. |
+| `estimate_generation` | Get the host's cost and/or time estimate for the planned request (same arguments as `plan_generation`). Returns `plan` and `estimate`; nothing is generated. Only present when the host provides estimates; when it is missing, say you cannot quote a cost. A request that fails planning returns an `isError` result with code `plan_failed`. |
+
+### Write
+
+| Tool | Use it to |
+| --- | --- |
+| `generate` | Plan and start a generation (paid, irreversible). Takes `model`, `request`, optional `strategy` and `resolvedPrompt`, and a required `idempotencyKey` (1..200 chars, unique per intended generation). Returns `result` (the host's value, e.g. a job id), the `plan` actually sent and the key; a retry with the same key and arguments returns the first result with `deduplicated: true`. Planning errors return `plan_failed` and generate nothing. |
+
+## Pitfalls
+
+- **Idempotency keys:** the same key with different arguments is rejected ("already used with
+  different arguments"); use a new key for a new generation. A failed call forgets its key, so
+  retrying a failure with the same key does generate. Never reuse a key to "regenerate" or to
+  get a variation: that returns the old result.
+- **Templates:** when `request.prompt` contains template variables, pass the expanded text as
+  `resolvedPrompt`. Limits count the resolved text; when it is over the limit the plan errors
+  under every strategy and the prompt is not truncated. Shorten the resolved prompt yourself.
+- **Read adjustments, not just `ok`.** `ok: true` under `nearest` can still mean a reference was
+  dropped or the count reduced. Compare the adjusted request with what the user asked for.
+- **Unknown model:** a model id not in the current catalogue fails validation; call
+  `list_models` again (the catalogue may have changed) instead of retrying the same id.
+- `generate` only starts the job; the result may be a job id rather than media. Do not call it
+  again to "check" progress; that is a new paid request unless the key and arguments match.
+- `idempotencyKey` belongs only on `generate`; `plan_generation` and `estimate_generation`
+  reject it as an unknown argument.

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

@@ -0,0 +1,139 @@
+---
+name: pixerate-image-editor
+description: How to colour-correct and retouch a photo in the Pixerate image editor through its agent tools - base adjustments (exposure, contrast, white balance temperature and tint, saturation, blur), non-destructive adjustment layers (curves, levels, hue/saturation, vibrance, color balance, black and white, photo filter, invert, posterize, threshold) with blend modes and opacity, selections (rectangle, ellipse, magic wand, color range, grow, shrink, feather, refine edge) and layer masks, crop, rotate and flip, undo, reading the histogram for clipping, and rendering a PNG preview to check the result. Use when asked to edit, grade, correct, brighten, warm up, desaturate, crop, straighten or mask an image, or when get_adjustments, set_adjustments, add_adjustment_layer, select_by_color or render_preview are available.
+---
+
+# Image editor
+
+The image editor holds one source image plus a stack of edits that never touch the source
+pixels: base adjustments (one value per control id), adjustment layers applied bottom to top
+on top of the base, an optional selection, crop/rotate/flip and annotations. Rendering order:
+base adjustments, then layers bottom to top (each through its mask, opacity and blend mode),
+then blur. See `pixerate-agent-tools` for errors, namespacing and command batching.
+
+- **Control ids** for base adjustments: `brightness`, `contrast`, `exposure`, `temperature`,
+  `tint`, `saturation` (all -100..100, default 0), `blur` (0..30 px) and `opacity` (0..1).
+  `list_controls` is the source of truth for ranges, steps and defaults.
+- **Layer ids** (e.g. `adj_1`) come from `add_adjustment_layer` / `apply_selection_as_mask`
+  and `get_adjustments`. Layer parameters are addressed as `layers.<layerId>.<controlId>`,
+  where nested params use dots: `layers.adj_2.master.gamma` (levels),
+  `layers.adj_3.ranges.0.saturation` (hue/saturation reds), `layers.adj_4.shadows.2`
+  (color balance yellow-blue), `layers.adj_1.opacity`.
+- **Coordinates** for selections are natural pixels of the source image (before crop, rotate
+  or flip). Read `get_selection` bounds or the image size, never screen pixels.
+
+## Working method
+
+1. **Read.** `get_adjustments` for the current values, process version and layers;
+   `get_image_info` for the image size, crop and rotation; `list_controls` once for control
+   ids, ranges, layer kinds and blend modes; `render_preview` (default 512 px) to see the
+   image, then `get_histogram` to judge exposure and clipping in numbers.
+2. **Plan the order of corrections** (see Best practices): straighten and crop first (so
+   later judgements are on the final frame), then global tone and white balance,
+   then contrast and tone curves, then colour, then local fixes through masks, then creative
+   looks.
+3. **Write in few steps.** Put every base change of one correction into one `set_adjustments`
+   call (one undo step) with a `label`. Create layers with their `params` in the same
+   `add_adjustment_layer` call rather than adding a neutral layer and then setting it.
+4. **Local edits:** select (`select_region`, `select_by_color`), refine (`modify_selection`,
+   `refine_selection`), check with `get_selection` (area, percent, bounds), then
+   `apply_selection_as_mask` with a `kind` to create the masked layer in one step.
+5. **Verify.** `render_preview` after each group of corrections, not after each slider, then
+   `get_histogram` (it reads the last render) for clipping. Compare against the previous
+   preview; read the `applied` and `clamped` lists that writes return. `undo_image` takes back a
+   step that made things worse.
+
+## Best practices
+
+- **Non-destructive first.** Prefer an adjustment layer over pushing a base slider to its
+  limit: layers can be masked, faded with `opacity`, blended and stacked. Use base sliders for
+  global exposure and white balance, layers for everything you may want to tune later.
+- **Order of corrections** (as in a raw / Photoshop workflow): exposure and white balance
+  (`exposure`, `temperature`, `tint`) → black and white points and contrast (a `levels` layer,
+  then a gentle S-curve `curves` layer) → colour (`vibrance` before `saturation`,
+  `hueSaturation` per range, `colorBalance`) → local adjustments through masks → creative looks
+  (`photoFilter`, `blackWhite`, `posterize`). Correct before you stylise.
+- **Avoid clipping.** Set levels black and white points (`master.inBlack`, `master.inWhite`)
+  just inside where the image data starts (the histogram's `p1` / `p99`), not past it; large
+  `exposure` or `contrast` values blow highlights and crush shadows in the output. More than
+  about 0.5% of pixels in `clipping.highlightsPercent` or `shadowsPercent` on a normal photo
+  means detail is lost; check bright skies, skin and deep shadows in `render_preview` too.
+- **Straighten, then crop.** Level horizons with `set_rotation` (small angles such as -2.5);
+  any angle that is not a quarter turn leaves transparent corners, so crop inside them with
+  `set_crop` afterwards. Keep a standard aspect ratio (3:2, 4:3, 16:9, 1:1, 4:5) unless asked
+  otherwise, and do not crop away the subject's space to look or move into.
+- **Small moves.** Real corrections are usually within ±10..30 on these scales. Prefer
+  `vibrance` over `saturation` for portraits (it protects already-saturated colours and skin).
+- **Contrast through curves.** A curves S-curve keeps endpoints fixed and avoids the flat
+  greys that a big `contrast` value with low `exposure` produces. Curve points are levels
+  0..255 (`{ input, output }`); keep `(0,0)` and `(255,255)` and move quarter-tones by 10..25.
+- **Neutral greys.** Use `temperature` / `tint` (or `colorBalance` midtones) so known-neutral
+  areas (white walls, grey roads, clouds) have no cast; then add warmth deliberately if wanted.
+- **Masks: select, refine, then mask.** Clean the selection before masking: `smooth` for
+  jagged wand edges, `refine_selection` for hair and soft edges, feather in proportion to the
+  image (a few px for hard objects, tens of px for sky or vignette transitions). Use the mask's
+  own `feather` and `density` on `apply_selection_as_mask` so softening stays adjustable.
+- **Blend modes for tone-only or colour-only changes:** `luminosity` applies a curves or
+  levels layer without shifting hue or saturation; `color` applies a tint without changing
+  brightness; `soft-light` / `overlay` for gentle contrast.
+- **Name layers** (`name`) by intent ("Sky darken", "Warm skin"), so the stack stays readable.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_adjustments` | Read the current state: `values` by control id, `process` version (1 or 2), and `layers` bottom to top with id, kind, params, opacity, blend, enabled and mask. Call first, and to find layer ids. |
+| `list_controls` | Get every base control (id, label, section, min, max, step, default, `requiresProcess`), each layer kind's settable controls (plus `opacity`), the blend mode ids and the `layers.<layerId>.<controlId>` path format. Call once per session before writing. |
+| `get_selection` | Read the active selection: `empty`, `bounds` (natural pixels), `area` in pixels, `percent` of the image and a description. Check it after every select or modify step and before masking: a wand that covered 90% of the image is the wrong selection. |
+| `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |
+| `get_histogram` | Judge exposure numerically: per channel and luminance `mean`, `p1` and `p99` (0..255), and `clipping` percent at pure black and white per channel. Reads the last render, so call `render_preview` first. `bins` (16, 32, 64 or 256) adds the counts. Cheaper than another image for checking a tonal change. |
+| `render_preview` | See the edited image (crop, adjustments, layers, annotations) as a PNG. `maxSide` 16..2048 px, default 512. Images cost tokens: render after a group of edits, use 512 for overall look and 1024+ to judge clipping, edges and masks. Fails in environments without rendering. |
+
+### Write
+
+| Tool | Use it to |
+| --- | --- |
+| `set_adjustments` | Set base controls and existing layer parameters in one undo step: `values` is a map of control id or `layers.<layerId>.<controlId>` path to number; `label` is echoed. Values are clamped to range; returns `applied` and `clamped` (and a note when `tint` is set on a process 1 edit). Unknown ids fail and change nothing. Cannot set curves points, booleans or colours. |
+| `add_adjustment_layer` | Add a layer on top of the stack: `kind` (curves, levels, hueSaturation, vibrance, colorBalance, blackWhite, photoFilter, invert, posterize, threshold), optional `params` merged with neutral defaults, `opacity` 0..1 (default 1), `blend` (default normal), `name`. Returns the layer (with its new id) and its stack index. The only tool that sets curves points, `colorize`, `preserveLuminosity`, a black and white `tint` or a photo filter `color`. |
+| `select_region` | Select by `shape`: `rect` or `ellipse` (with `x`, `y`, `width`, `height` in natural pixels), `all`, `none` or `invert`. `mode` replace (default), add, subtract or intersect; `feather` px (default 0). Returns the selection summary. |
+| `select_by_color` | Magic wand from a seed (`x`, `y`, `tolerance` 0..255 default 32, `contiguous` default true) or Color Range for every similar pixel (`color` "#rrggbb", `fuzziness` 0..200 default 40). `sampleMerged: true` samples the adjusted image instead of the source. `mode` as above. Use it for skies, backdrops and flat-coloured objects. |
+| `modify_selection` | Grow, shrink, feather, border or smooth the selection (`op`) by `radius` px (0..500). Use shrink then feather to keep an adjustment from bleeding over an edge; smooth to remove wand speckle. Fails when nothing is selected. |
+| `refine_selection` | Refine Edge: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %. Use on hair, fur, foliage or after loading a coarse AI mask. |
+| `update_adjustment_layer` | Change a layer's `enabled` (false hides it without deleting), `blend`, `opacity` (0..1) or `name` in one undo step. Returns the layer. Its parameters change with `set_adjustments`. Toggle `enabled` to compare a layer's effect before and after. |
+| `move_adjustment_layer` | Move a layer to index `to` (0 = bottom, applied first; past the top means top). Order matters: a curves layer above a hue/saturation layer works on its output. Fails when the layer is already there. Returns the ids bottom to top. |
+| `remove_adjustment_layer` | Delete a layer and its mask. Prefer hiding it with `update_adjustment_layer` when the user may want it back. Returns the remaining ids. |
+| `set_crop` | Crop to `x`, `y`, `width`, `height` in source pixels of the un-rotated image (see `get_image_info`). Non-destructive; refused if the box leaves the image. For an aspect ratio, compute the largest box of that ratio inside the image and centre it on the subject. Returns the geometry. |
+| `reset_crop` | Remove the crop and show the whole image again. |
+| `set_rotation` | Set the absolute rotation in degrees clockwise (-360..360). Quarter turns keep every pixel; small angles straighten a horizon but add transparent corners to crop away. Returns the geometry. |
+| `flip_image` | Mirror the image `horizontal` (left-right) or `vertical`. Avoid flipping images with text, logos or recognisable places. |
+| `undo_image` | Undo the last edit (one tool call is one step). Returns `canUndo` / `canRedo`. |
+| `redo_image` | Redo the edit you just undid. |
+| `apply_selection_as_mask` | Mask a layer with the current selection: pass `layerId` to mask an existing layer, or `kind` (plus optional `params`) to create a new masked layer in one step. `density` 0..1 and `feather` px soften the mask non-destructively. Returns `layerId`, kind, mask info and the selection summary. |
+
+## Pitfalls
+
+- A layer's `kind` cannot change; to switch kinds add a new layer and remove the old one.
+  Curves points, `colorize` and colours are only set when the layer is added, so get them
+  right in `add_adjustment_layer` (or replace the layer).
+- `get_histogram` describes the last render, not the current state: render after edits, then
+  read it.
+- Crop coordinates are always in the un-rotated source; after `set_rotation` the output size
+  swaps for quarter turns, but the crop box does not.
+- `set_adjustments` clamps silently: always read `clamped`. If a value you needed was clamped,
+  the correction needs a layer (e.g. levels or curves), not a bigger number.
+- `tint` has no effect on process 1 edits (older saved documents); the result carries a note.
+  Do not keep raising it; correct the green-magenta cast with a `colorBalance` layer instead.
+- Base `opacity` fades the whole image, not an adjustment. Base `blur` blurs the whole output
+  after all layers; it is not a local softening tool.
+- `invert` and `threshold` are destructive-looking creative effects; never use them for a
+  correction the user did not ask for. Posterize `levels` below ~8 bands visibly.
+- Selection coordinates ignore crop and rotation: they are source-image pixels. A rectangle in
+  the cropped preview's coordinates lands in the wrong place on a cropped image.
+- `select_by_color` without `x`/`y` or `color` fails. Large `tolerance` / `fuzziness` floods the
+  selection: start low (wand 20..40, range 30..60), check `percent`, and add with `mode: add`.
+- `modify_selection`, `refine_selection` and `apply_selection_as_mask` fail with "Nothing is
+  selected." when the selection is empty; select first.
+- Opacity values are 0..1, not percent. Curves and levels points are 0..255 levels; levels
+  `gamma` is 0.1..9.99 (1 = neutral); hue is degrees -180..180.