@pixerate/editor 0.222.3 → 0.223.0

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

@@ -0,0 +1,102 @@
+/**
+ * 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;
+    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[];
+}
+/** 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.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -121,7 +121,9 @@ same change.
   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. |