@pixerate/editor 0.222.3 → 0.223.1

package/dist/tools/skill-evals.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The evals that workflow skills ship in `skills/<name>/evals/*.json`, for any harness to run.
+ *
+ * An eval is a task a model would be given (`prompt`), the document it starts from
+ * (`fixture`), the checks that decide whether the job was done (`checks`: a read tool, its
+ * arguments and what its result must match) and one known-good answer (`solution`: the tool
+ * calls an expert would make). The package's own tests prove each eval with its `solution`; an
+ * agent harness builds the fixture, gives its model the `prompt` in place of the solution, then
+ * runs `failedEvalChecks`. The format is described in `skills/README.md`.
+ */
+import type { McpToolResult } from './registry.js';
+export interface SkillEvalToolCall {
+    tool: string;
+    args?: Record<string, unknown>;
+}
+export interface SkillEvalCheck extends SkillEvalToolCall {
+    /** What the check is for, shown when it fails. */
+    why: string;
+    expect: unknown;
+}
+export interface SkillEval {
+    prompt: string;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture;
+    checks: SkillEvalCheck[];
+    solution: SkillEvalToolCall[];
+}
+export interface SpreadsheetEvalFixture {
+    editor: 'spreadsheet';
+    /** Raw inputs from A1, row by row, typed as a person would (`'` forces text). */
+    rows: Array<Array<string | number | boolean | null>>;
+}
+export interface ImageEvalFixture {
+    editor: 'image';
+    width: number;
+    height: number;
+    /** RGB background. */
+    background: [number, number, number];
+    /** Shapes painted over it in order, with RGB colours. */
+    shapes: Array<{
+        shape: 'rect' | 'ellipse';
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        color: [number, number, number];
+    }>;
+}
+export interface VectorEvalFixture {
+    editor: 'vector';
+    width: number;
+    height: number;
+    /** Commands that build the starting artwork, run in order (`"$0.id"` refers to an earlier result). */
+    setup?: Array<{
+        id: string;
+        params?: Record<string, unknown>;
+    }>;
+}
+export interface PaintEvalFixture {
+    editor: 'paint';
+    width: number;
+    height: number;
+    /** Tool calls that prepare the canvas (paper, layers, strokes), run in order. */
+    setup?: SkillEvalToolCall[];
+}
+export interface VideoEvalFixture {
+    editor: 'video';
+    /** Tool calls that build the starting project (settings, assets, clips, markers), run in order. */
+    setup?: SkillEvalToolCall[];
+}
+export interface ChartEvalFixture {
+    editor: 'chart';
+    /** Tool calls that build the starting chart (`set_chart_data`, `update_chart`), run in order. */
+    setup?: SkillEvalToolCall[];
+}
+/** One eval file of a skill. */
+export interface SkillEvalFile {
+    skill: string;
+    /** Path relative to the skills directory, e.g. `pixerate-image-selection-masking/evals/local-adjustment.json`. */
+    path: string;
+    eval: SkillEval;
+}
+/**
+ * The evals in a set of skill files (paths relative to the skills directory, contents as text,
+ * like `SkillFiles` but including `evals/*.json`), sorted by path.
+ */
+export declare function listSkillEvals(files: Readonly<Record<string, string>>): SkillEvalFile[];
+/** The RGBA pixels of an image fixture: shapes painted over the background in order. */
+export declare function imageEvalFixturePixels(f: ImageEvalFixture): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+/** Calls a tool by the bare name an eval uses; the harness maps it to its own names if it must. */
+export type SkillEvalToolCaller = (tool: string, args: Record<string, unknown>) => Promise<McpToolResult>;
+/** Calls one eval tool step (resolving `$read` arguments); throws with the tool's error text. */
+export declare function callEvalTool(callTool: SkillEvalToolCaller, { tool, args }: SkillEvalToolCall): Promise<unknown>;
+/**
+ * Whether `actual` matches `expected`. Objects match key by key (other keys are ignored),
+ * arrays element by element with the same length, other values exactly. Operators:
+ * `$min` / `$max` (numbers), `$type`, `$match` (a regular expression, or `[pattern, flags]`), `$in`, `$not`,
+ * `$every` / `$some` (array elements), `$length`, `$unique`, `$distinct` (the distinct
+ * values), `$sum`, `$column: [index, matcher]` (one column of a 2D array), `$nonEmpty`
+ * (the array without empty cells or rows) and `$expr` (a JavaScript expression over `v`).
+ */
+export declare function matchesEvalExpectation(actual: unknown, expected: unknown): boolean;
+/** The checks that fail, each as its `why` with what the tool returned (or its error). */
+export declare function failedEvalChecks(callTool: SkillEvalToolCaller, checks: readonly SkillEvalCheck[]): Promise<string[]>;

package/dist/tools/skills.d.cts

@@ -13,11 +13,22 @@ export interface SkillInfo {
     description: string;
     /** Other files of the skill relative to its directory, e.g. `references/commands.md`. */
     references: string[];
+    /**
+     * `workflow` for a skill that covers one job from start to finish on a reference skill's tools
+     * (frontmatter `metadata.kind: workflow`); otherwise `reference`.
+     */
+    kind: 'reference' | 'workflow';
+    /** A workflow skill's reference skill (frontmatter `metadata.reference`), whose tools it uses. */
+    reference?: string;
 }
-/** Reads `name` and `description` from a SKILL.md's YAML frontmatter. */
+/**
+ * Reads `name`, `description` and the one-level `metadata` map (`metadata.kind`,
+ * `metadata.reference`, …) from a SKILL.md's YAML frontmatter.
+ */
 export declare function parseSkillFrontmatter(markdown: string): {
     name?: string;
     description?: string;
+    metadata: Record<string, string>;
     body: string;
 };
 /** The skills in a set of skill files, sorted by name. */

package/dist/tools/skills.d.ts

@@ -13,11 +13,22 @@ export interface SkillInfo {
     description: string;
     /** Other files of the skill relative to its directory, e.g. `references/commands.md`. */
     references: string[];
+    /**
+     * `workflow` for a skill that covers one job from start to finish on a reference skill's tools
+     * (frontmatter `metadata.kind: workflow`); otherwise `reference`.
+     */
+    kind: 'reference' | 'workflow';
+    /** A workflow skill's reference skill (frontmatter `metadata.reference`), whose tools it uses. */
+    reference?: string;
 }
-/** Reads `name` and `description` from a SKILL.md's YAML frontmatter. */
+/**
+ * Reads `name`, `description` and the one-level `metadata` map (`metadata.kind`,
+ * `metadata.reference`, …) from a SKILL.md's YAML frontmatter.
+ */
 export declare function parseSkillFrontmatter(markdown: string): {
     name?: string;
     description?: string;
+    metadata: Record<string, string>;
     body: string;
 };
 /** The skills in a set of skill files, sorted by name. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.222.3",
+  "version": "0.223.1",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -53,6 +53,8 @@ request like "clean up this export" finds it.
 | [`pixerate-video-social-cut`](pixerate-video-social-cut/SKILL.md) | Video (`pixerate-video-editor`) | Vertical or square reframes that fill the frame, the hook first, platform lengths, titles in the safe area. |
 | [`pixerate-video-colour-grade`](pixerate-video-colour-grade/SKILL.md) | Video (`pixerate-video-editor`) | Correct and match shots, then one look on an adjustment clip; LUTs at moderate strength with skin protected. |
 | [`pixerate-video-montage`](pixerate-video-montage/SKILL.md) | Video (`pixerate-video-editor`) | Selects on the beat, varied pacing, short transitions with handles, music under everything and a clean ending. |
+| [`pixerate-chart-choose-and-build`](pixerate-chart-choose-and-build/SKILL.md) | Chart (`pixerate-chart`) | From the question to the type, clean ordered data, honest axes, units and colour-blind-safe colours. |
+| [`pixerate-chart-annotate`](pixerate-chart-annotate/SKILL.md) | Chart (`pixerate-chart`) | A takeaway title, highlights, labelled targets and ranges, callouts and a source note, kept few. |
 | [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Video (`pixerate-video-editor`) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. Owns the dialogue tools. |
 | [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Video (`pixerate-video-editor`) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. Owns the music tools. |
 
@@ -117,11 +119,14 @@ same change.
   user's words), a `fixture` (the starting document: `{ "editor": "spreadsheet", "rows" }`,
   `{ "editor": "image", "width", "height", "background", "shapes" }` or `{ "editor":
   "vector", "width", "height", "setup" }` with commands that draw the starting art, 
-  `{ "editor": "paint", "width", "height", "setup" }` or `{ "editor": "video", "setup" }` with tool calls), `checks` (a read-only
+  `{ "editor": "paint", "width", "height", "setup" }` `{ "editor": "video", "setup" }` or `{ "editor":
+  "chart", "setup" }` with tool calls), `checks` (a read-only
   tool, or `run_command` with a read-only command such as `vector.list`, its `args`, what its result must match in `expect`, and `why`) and a `solution` (the
   tool calls an expert would make). The test proves each eval: some check fails on the fixture,
   and all pass after the solution. A model harness runs the same file with the model in place
-  of the solution. In `expect`, objects match key by key and arrays element by element, with
+  of the solution, using `@pixerate/editor/tools`: `listSkillEvals` reads the eval files,
+  `imageEvalFixturePixels` paints an image fixture, and `failedEvalChecks` runs the checks
+  through the harness's own tool calls (`matchesEvalExpectation` is the matcher on its own). In `expect`, objects match key by key and arrays element by element, with
   operators for ranges and lists (`$min`, `$max`, `$match`, `$every`, `$some`, `$length`,
   `$unique`, `$distinct`, `$sum`, `$column`, `$nonEmpty`, `$not`, `$in`, `$type`); a check's
   argument can read a value the job created with `{ "$read": "list_layers", "path":

package/skills/pixerate-agent-tools/SKILL.md

@@ -42,7 +42,9 @@ editor's, or (in discovery mode) only `list_toolsets`, `search_tools`, `enable_t
    toolset when you will use many of its tools). The tools then appear in your list. Use
    `disable_tools` to drop a toolset you are done with.
 4. **Read the skill before working in a toolset.** `get_skill` with the skill `list_toolsets`
-   names (or the MCP prompt / `skill://` resource of the same name).
+   names (or the MCP prompt / `skill://` resource of the same name). When the task is a whole
+   job one of the toolset's `workflows` covers (a cutout, a photo correction, an icon set), read
+   that workflow skill too: it has the steps in order and the check after each.
 5. **Read the house style when there is one.** A toolset with a `style` field in
    `list_toolsets` (or an `enable_tools` result with a `style` line) has house-style skills:
    call `get_style` with that domain before you make or change work there.
@@ -149,11 +151,11 @@ Never repeat an identical failing call. Never work around a read-only refusal; t
 | Tool | Use it to |
 | --- | --- |
 | `list_editors` | See which editors are open in the browser and connected to the MCP bridge (id, name, kind, tool count, last activity). Call it first when tools come through the bridge; pass an id or part of a name as `editor` to any tool to pick one when several are open, otherwise the most recently active editor with that tool answers. If none is connected, ask the user to open the app and connect it. |
-| `list_toolsets` | See the toolsets open now: name, title, what each covers, its skill, how many tools it has and whether they are in your tool list (`enabled`: all, some, none). Call it first in a discovery view, then `search_tools` or `enable_tools`. |
+| `list_toolsets` | See the toolsets open now: name, title, what each covers, its skill, its workflow skills (`workflows`), how many tools it has and whether they are in your tool list (`enabled`: all, some, none). Call it first in a discovery view, then `search_tools` or `enable_tools`. |
 | `search_tools` | Find the tool for a task: pass `query` in plain words (and `toolset` to search one editor, `limit` for more than 10). Returns the best matches first with name, toolset, title, one-sentence summary, whether it only reads and whether it is listed. Follow with `enable_tools`. |
 | `enable_tools` | Add tools to your tool list by full name (`tools`, from `search_tools`) and/or whole `toolsets` (from `list_toolsets`). Returns the names added and how many are listed. Prefer single tools to large toolsets. Unknown names fail and change nothing. Allowed tools can also be called by name without enabling them. |
 | `disable_tools` | Drop tools or whole toolsets you are done with from your tool list, to keep it short. Returns the names removed. |
-| `get_skill` | Read a toolset's skill (markdown) before working with it; pass `file` for one of its reference files (listed at the top). The note at the top says how names are prefixed here. |
+| `get_skill` | Read a toolset's skill (markdown) before working with it, and the workflow skill for the job when one fits; pass `file` for one of its reference files (listed at the top). The note at the top says how names are prefixed here. |
 | `list_styles` | See the house-style skills here, general layer first: name, description, layer, the domains each applies to, which have a profile, whether each is on, and issues that leave all or part of one out. Pass `domain` to see one domain's. Follow with `get_style`. |
 | `get_style` | Read the house style for a `domain` before you make or change work there: each skill's preferences as a `<style_skill>` block naming its layer, the merged profile (tokens resolved), `sources` (which layer set each field) and `issues`. Then check your work with the domain's `check_<domain>_style`. |
 | `get_style_file` | Read one file of a house-style skill (`name`, `file`), such as a `references/*.md` its preferences point to, or its raw profile (`chart.json`) before tokens are resolved. An unknown file fails with the list of its files. |

package/skills/pixerate-chart/SKILL.md

@@ -44,6 +44,14 @@ Charts inside a rich-text document are not edited with these tools: use `insert_
 `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).
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-chart-choose-and-build`: the type from the question, clean data, honest axes, units, colours.
+- `pixerate-chart-annotate`: a takeaway title, highlights, targets, ranges, callouts and the source.
+
 ## Working method
 
 0. **House style.** When the host has one (`list_toolsets` shows a `style` field on the chart

package/skills/pixerate-chart-annotate/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pixerate-chart-annotate
+description: The annotation workflow in the Pixerate chart editor - turning a correct chart into one that makes its point - a title that states the takeaway, highlighting the categories or series that matter, reference lines for targets and averages, bands for ranges, callouts on the points that need explaining, units, a source note and a check that the annotations stay few and honest. Use when asked to make a chart tell a story, highlight or call out a point, show a target, goal, threshold, average or range, add a source or footnote, or make a chart ready for a report, slide or board pack, or when highlight_chart, add_chart_reference_line, add_chart_reference_band or set_chart_callout are available. Load with pixerate-chart, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-chart
+---
+
+# Annotating a chart
+
+A chart for a report or a slide should say what it means, not leave the reader to find it. Once
+the type and data are right (`pixerate-chart-choose-and-build`), add the few marks that point at
+the message: a title that states it, a highlight on what matters, a reference line or band for
+the benchmark, a callout where something needs explaining, and a source note. Fewer is better:
+every annotation competes with the data.
+
+This skill is the method. `pixerate-chart` has the full tool reference.
+
+## Goal and quality bar
+
+- The title states the takeaway ("Q3 was our record quarter"), the subtitle the measure and
+  units if the axis does not.
+- What matters stands out (`highlight`), and everything else recedes.
+- Benchmarks are drawn, labelled, on the right axis: a target line, an average, a normal range.
+- At most one or two reference lines, one band and a couple of callouts.
+- The source is cited in `note`; units are stated.
+- The data is unchanged by annotating.
+
+## Inputs to confirm
+
+- **The message:** the one thing the reader should take away.
+- **Benchmarks:** targets, averages, thresholds or ranges, with their values and units.
+- **Source** of the data, and the audience (report, slide, dashboard).
+
+## Working method
+
+1. **Read.** `get_chart`: the type, categories, series, existing annotations and warnings.
+   **Check:** the chart is already the right type with clean data; if not, fix that first.
+2. **Title the takeaway.** `update_chart` `title` with the message, `subtitle` with the measure
+   and units.
+3. **Highlight.** `highlight_chart` with the category labels or series names that carry the
+   message; the rest dims.
+   **Check:** `get_chart` `spec.highlight`.
+4. **Benchmarks.** `add_chart_reference_line` for a target or average (`value`, `label`, `axis`);
+   `add_chart_reference_band` for a range (`from`, `to`, `label`).
+   **Check:** `spec.referenceLines` / `referenceBands` have the values and labels.
+5. **Callouts** for points that need a word (`set_chart_callout` on a series and category), such
+   as "Launch" or "Strike".
+6. **Source and units.** `update_chart` `note` ("Source: …"); the axis `format` or title for
+   units.
+7. **Review.** `render_chart`; remove any annotation that does not help the message.
+
+## Decision table
+
+| Want to say | Annotation |
+| --- | --- |
+| This one is the point | `highlight_chart` on it; title states it |
+| Above or below a goal | `add_chart_reference_line` at the target, labelled |
+| Inside or outside a normal range | `add_chart_reference_band`, labelled |
+| Compared with the average | Reference line at the average, labelled "Average" |
+| Something happened here | `set_chart_callout` on that point |
+| Where the numbers came from | `note` |
+| The trend, not the noise | `add_chart_trendline` (say what it models) |
+
+## Recipes
+
+**Record quarter.** `highlight_chart` `{ names: ["Q3"] }` → `update_chart` `{ title: "Q3 was our
+record quarter" }`.
+
+**Target.** `add_chart_reference_line` `{ value: 100000, label: "Target" }`.
+
+**Board-ready.** `update_chart` `{ note: "Source: internal CRM, 2026", yAxis: { format: { style:
+"currency", currency: "USD" } } }`.
+
+## Pitfalls
+
+- **Neutral titles** ("Quarterly revenue") make the reader do the work; state the finding when
+  the chart has one.
+- **Annotation clutter**: many lines, bands and callouts hide the data.
+- **Recolouring instead of highlighting**: changing one series' colour by hand breaks palettes
+  and colour checks; `highlight_chart` keeps them.
+- **Unlabelled lines**: a line without a label is a puzzle.
+- **Targets on the wrong axis**: put a reference line on the axis of the series it belongs to
+  (`axis: "y2"` for a secondary-axis series).
+- **Claims the data does not support**: the title must be true of the chart as drawn.
+
+## Tools used
+
+- `get_chart`, `render_chart`: read and look
+- `update_chart`: title, subtitle, note and axis formats
+- `highlight_chart`: what stands out
+- `add_chart_reference_line`, `update_chart_reference_line`, `remove_chart_reference_line`: targets and averages
+- `add_chart_reference_band`, `update_chart_reference_band`, `remove_chart_reference_band`: ranges
+- `set_chart_callout`: notes on points
+- `add_chart_trendline`: a fitted trend
+- `undo_chart`: take back a step

package/skills/pixerate-chart-annotate/evals/highlight-the-point.json

@@ -0,0 +1,78 @@
+{
+	"prompt": "Make this chart tell the reader that Q3 was our record quarter.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"Q1",
+						"Q2",
+						"Q3",
+						"Q4"
+					],
+					"series": [
+						{
+							"name": "Revenue",
+							"values": [
+								82000,
+								91000,
+								118000,
+								96000
+							]
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "bar",
+					"title": "Quarterly revenue"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "Q3 stands out",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"$expr": "v.highlight.includes('Q3') || v.series.some((s) => (s.callouts || [])[2]) || v.series.some((s) => s.pointColors && s.pointColors[2] && s.pointColors.filter(Boolean).length === 1)"
+				}
+			}
+		},
+		{
+			"why": "the title states the takeaway",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"title": {
+						"$match": [
+							"q3|third quarter",
+							"i"
+						]
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "highlight_chart",
+			"args": {
+				"names": [
+					"Q3"
+				]
+			}
+		},
+		{
+			"tool": "update_chart",
+			"args": {
+				"title": "Q3 was our record quarter"
+			}
+		}
+	]
+}

package/skills/pixerate-chart-annotate/evals/source-and-units.json

@@ -0,0 +1,76 @@
+{
+	"prompt": "Before this chart goes in the board report, add the source (internal CRM, 2026) and make the units clear.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"Q1",
+						"Q2",
+						"Q3",
+						"Q4"
+					],
+					"series": [
+						{
+							"name": "Revenue",
+							"values": [
+								82000,
+								91000,
+								118000,
+								96000
+							]
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "bar",
+					"title": "Quarterly revenue"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "a source note",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"note": {
+						"$match": [
+							"crm",
+							"i"
+						]
+					}
+				}
+			}
+		},
+		{
+			"why": "the units are stated (axis title, format or subtitle)",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"$expr": "/usd|\\$|dollar/i.test(v.yAxis.title + ' ' + v.subtitle) || v.yAxis.format.style === 'currency'"
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "update_chart",
+			"args": {
+				"note": "Source: internal CRM, 2026",
+				"yAxis": {
+					"format": {
+						"style": "currency",
+						"currency": "USD"
+					}
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-chart-annotate/evals/target-line.json

@@ -0,0 +1,85 @@
+{
+	"prompt": "Show our quarterly target of 100,000 on the revenue chart so it's clear which quarters hit it.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"Q1",
+						"Q2",
+						"Q3",
+						"Q4"
+					],
+					"series": [
+						{
+							"name": "Revenue",
+							"values": [
+								82000,
+								91000,
+								118000,
+								96000
+							]
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "bar",
+					"title": "Quarterly revenue"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "a labelled reference line at 100,000 on the value axis",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"referenceLines": {
+						"$some": {
+							"value": 100000,
+							"label": {
+								"$match": [
+									"target",
+									"i"
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "the data is unchanged",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"series": [
+						{
+							"values": [
+								82000,
+								91000,
+								118000,
+								96000
+							]
+						}
+					]
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "add_chart_reference_line",
+			"args": {
+				"value": 100000,
+				"label": "Target"
+			}
+		}
+	]
+}