@pixerate/editor 0.223.8 → 0.223.9

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

@@ -20,7 +20,7 @@ export interface SkillEvalCheck extends SkillEvalToolCall {
 }
 export interface SkillEval {
     prompt: string;
-    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture;
     checks: SkillEvalCheck[];
     solution: SkillEvalToolCall[];
 }
@@ -109,6 +109,13 @@ export interface EffectEvalFixture {
     /** Tool calls that prepare the session, run in order. */
     setup?: SkillEvalToolCall[];
 }
+export interface CanvasEvalFixture {
+    editor: 'canvas';
+    /** The starting nodes (React Flow style: `id`, `type`, `position`, `width`, `height`, `data`, `parentId`). */
+    nodes: Array<Record<string, unknown>>;
+    /** Tool calls that prepare the canvas (components, instances), run in order. */
+    setup?: SkillEvalToolCall[];
+}
 /** One eval file of a skill. */
 export interface SkillEvalFile {
     skill: string;

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

@@ -20,7 +20,7 @@ export interface SkillEvalCheck extends SkillEvalToolCall {
 }
 export interface SkillEval {
     prompt: string;
-    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture;
     checks: SkillEvalCheck[];
     solution: SkillEvalToolCall[];
 }
@@ -109,6 +109,13 @@ export interface EffectEvalFixture {
     /** Tool calls that prepare the session, run in order. */
     setup?: SkillEvalToolCall[];
 }
+export interface CanvasEvalFixture {
+    editor: 'canvas';
+    /** The starting nodes (React Flow style: `id`, `type`, `position`, `width`, `height`, `data`, `parentId`). */
+    nodes: Array<Record<string, unknown>>;
+    /** Tool calls that prepare the canvas (components, instances), run in order. */
+    setup?: SkillEvalToolCall[];
+}
 /** One eval file of a skill. */
 export interface SkillEvalFile {
     skill: string;

package/package.json

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

package/skills/README.md

@@ -67,6 +67,8 @@ request like "clean up this export" finds it.
 | [`pixerate-effect-look-development`](pixerate-effect-look-development/SKILL.md) | Effects (`pixerate-effect-authoring`) | Tune a look in a few moves, save it as a preset, animate with eased keyframes, seamless loops. |
 | [`pixerate-accessibility-audit`](pixerate-accessibility-audit/SKILL.md) | Cross-domain (`pixerate-color`) | Text and non-text contrast, colour-blind-safe meaning, both modes, smallest fixes and a report, in any editor. |
 | [`pixerate-brand-application`](pixerate-brand-application/SKILL.md) | Cross-domain (`pixerate-color`) | Brand roles mapped to exact palette values, near-misses snapped, readable text on brand colours, derivatives and house-style checks. |
+| [`pixerate-canvas-design-system-components`](pixerate-canvas-design-system-components/SKILL.md) | Canvas (`pixerate-canvas`) | Main components and linked instances, component sets with named variant properties, overrides kept linked. |
+| [`pixerate-canvas-layout`](pixerate-canvas-layout/SKILL.md) | Canvas (`pixerate-canvas`) | Align, distribute, order and lock with the arrange commands, changing only the intended axis. |
 | [`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. |
 
@@ -135,7 +137,8 @@ same change.
   "chart", "setup" }` `{ "editor": "diagram", "setup" }` with tool calls,
   `{ "editor": "rich-text", "html" }`, 
   `{ "editor": "animation", "setup" }`, `{ "editor": "generation", "models", "prices", "history" }`
-  (a fake host that records each generation) or `{ "editor": "effect", "effectId", "setup" }`), `checks` (a read-only
+  (a fake host that records each generation) `{ "editor": "effect", "effectId", "setup" }` or `{ "editor": "canvas",
+  "nodes", "setup" }` (a headless canvas with the component, arrange and document tools)), `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

package/skills/pixerate-canvas/SKILL.md

@@ -25,6 +25,14 @@ from `get_editor_state`; component and set ids from `list_components`. Tools tha
 just selected with `canvas_select`. See `pixerate-agent-tools` for namespacing, `run_commands`
 batching and error codes.
 
+## 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-canvas-design-system-components`: components, instances, variant sets and overrides.
+- `pixerate-canvas-layout`: align, distribute, order and lock.
+
 ## Working method
 
 1. **Read.** `get_editor_state` with `includeDocument: false` returns `canvas.nodes` and

package/skills/pixerate-canvas-design-system-components/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: pixerate-canvas-design-system-components
+description: The design system components workflow in the Pixerate canvas - turning repeated design into main components, placing instances instead of copies, combining versions into a component set with named variant properties and values, adding variants, keeping instances linked, swapping, resetting and pushing overrides, and keeping the library tidy and named. Use when asked to build or tidy a design system, component library or UI kit, make a component, instance, variant or component set, add a state (hover, disabled) or size, rename variant properties, or replace copies with instances, or when create_component, combine_as_variants, add_variant or create_instance are available. Load with pixerate-canvas, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-canvas
+---
+
+# Building design system components
+
+A design system replaces copies with components. A main component holds the design; instances
+show it elsewhere and update when it changes, with per-instance overrides where they differ.
+Versions of one thing (styles, states, sizes) become variants in a component set, described by
+properties ("Style=Primary, State=Disabled") a person or agent can switch between. Names and
+properties are the interface: keep them clear and consistent.
+
+This skill is the method. `pixerate-canvas` has the full tool reference.
+
+## Goal and quality bar
+
+- Anything used more than once is a main component; its uses are linked instances
+  (`inspect_instance` `status: "linked"`), not copies.
+- Versions of one element are variants in one component set, with named properties (Style,
+  State, Size) and named values (Primary, Disabled, Large), never "Property 1" and "Variant2".
+- Every combination of property values is unique; the default variant is the most common one.
+- Instances keep their link; detach only when one must diverge for good.
+- Components are named by what they are ("Button", "Card"), sets list their options clearly.
+
+## Inputs to confirm
+
+- **What becomes a component**, and which existing copies should become its instances.
+- **Properties and values** for variants (Style: Primary / Secondary; State: Default / Hover /
+  Disabled; Size: Small / Medium / Large).
+- **Naming conventions** of the team's library.
+
+## Working method
+
+1. **Read.** `list_components` (components, sets, their variants and options) and
+   `get_canvas_document` for the nodes.
+   **Check:** you know which nodes are already components and which are copies.
+2. **Make components.** `create_component` with the frame's id(s).
+   **Check:** `list_components` lists it with its name.
+3. **Replace copies with instances.** `create_instance` with `componentId`, `x`, `y`; remove the
+   copies once instances stand in their place.
+   **Check:** `get_canvas_document` shows instance nodes where the copies were.
+4. **Combine versions into variants.** `create_component` each version, then
+   `combine_as_variants` with their ids; the set gets generic names ("Property 1", "Default",
+   "Variant2"). Rename at once: `rename_variant_property` (`name`, `newName`, `setId`) and
+   `rename_variant_value` (`property`, `value`, `newValue`, `setId`).
+   **Check:** `list_components` `sets[].options` shows the real names; each variant's `variant`
+   map is right.
+5. **Add variants.** `add_variant` with `setId` and the new `variant` values (it duplicates the
+   default, or `from`); `set_variant_properties` to change a variant's values.
+   **Check:** the set lists every combination once.
+6. **Maintain instances.** `swap_instance` to another component or variant, `reset_overrides` to
+   go back to the main, `push_overrides` to promote an instance's change to the main,
+   `go_to_main_component` to edit the source.
+
+## Decision table
+
+| Situation | Tool |
+| --- | --- |
+| The same element appears several times | `create_component`, then `create_instance` for each use |
+| Versions of one element (styles, states, sizes) | `combine_as_variants`, then rename properties and values |
+| A new state or size | `add_variant` with `variant` values |
+| An instance should look like another variant | `set_instance_properties` or `swap_instance` |
+| An instance's change belongs in the main | `push_overrides` |
+| An instance drifted by accident | `reset_overrides` |
+| One copy must diverge permanently | `detach_instance` (last resort) |
+
+## Recipes
+
+**Card component with two instances.** `create_component` `{ ids: ["card"] }` →
+`create_instance` `{ componentId: "card", x: 0, y: 150 }` and `{ componentId: "card", x: 240,
+y: 150 }`.
+
+**Primary and Secondary variants.** `create_component` each button → `combine_as_variants`
+`{ ids }` → `rename_variant_property` `{ name: "Property 1", newName: "Style", setId }` →
+`rename_variant_value` `Default` → `Primary`, `Variant2` → `Secondary`.
+
+**A Disabled variant.** `add_variant` `{ setId, variant: { Style: "Disabled" } }`.
+
+## Pitfalls
+
+- **Copies instead of instances** drift apart and cannot be updated together.
+- **Generic variant names** ("Property 1", "Variant2") left after combining make the set unusable;
+  rename right away.
+- **The rename and add tools need the set** (`setId` from `list_components`) when nothing is
+  selected.
+- **Duplicate combinations** are refused; every variant needs a unique set of values.
+- **Detaching to make a small change** loses future updates; override instead.
+- **Combining unrelated components** into one set; a set is one element's versions.
+
+## Tools used
+
+- `list_components`, `inspect_instance`: components, sets, variants and instance status
+- `get_canvas_document`: the nodes, to check placement
+- `create_component`, `create_instance`: components and their instances
+- `combine_as_variants`, `add_variant`, `remove_variant`, `set_variant_properties`: component sets
+- `rename_variant_property`, `rename_variant_value`: clear property and value names
+- `set_instance_properties`, `swap_instance`, `reset_overrides`, `push_overrides`: instances and overrides
+- `detach_instance`, `go_to_main_component`, `restore_main_component`: break links, edit or restore mains
+- `undo_canvas`: take back a step

package/skills/pixerate-canvas-design-system-components/evals/add-variant.json

@@ -0,0 +1,172 @@
+{
+	"prompt": "Add a Disabled style to the button component set, as a third variant of its Style property.",
+	"fixture": {
+		"editor": "canvas",
+		"nodes": [
+			{
+				"id": "primary",
+				"type": "group",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Button / Primary"
+				}
+			},
+			{
+				"id": "pbg",
+				"type": "shape",
+				"parentId": "primary",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Bg",
+					"shape": {
+						"kind": "rect",
+						"fill": "#1d3557"
+					}
+				}
+			},
+			{
+				"id": "secondary",
+				"type": "group",
+				"position": {
+					"x": 0,
+					"y": 60
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Button / Secondary"
+				}
+			},
+			{
+				"id": "sbg",
+				"type": "shape",
+				"parentId": "secondary",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Bg",
+					"shape": {
+						"kind": "rect",
+						"fill": "#ffffff"
+					}
+				}
+			}
+		],
+		"setup": [
+			{
+				"tool": "create_component",
+				"args": {
+					"ids": [
+						"primary"
+					]
+				}
+			},
+			{
+				"tool": "create_component",
+				"args": {
+					"ids": [
+						"secondary"
+					]
+				}
+			},
+			{
+				"tool": "combine_as_variants",
+				"args": {
+					"ids": [
+						"primary",
+						"secondary"
+					]
+				}
+			},
+			{
+				"tool": "rename_variant_property",
+				"args": {
+					"name": "Property 1",
+					"newName": "Style",
+					"setId": {
+						"$read": "list_components",
+						"path": "sets.0.id"
+					}
+				}
+			},
+			{
+				"tool": "rename_variant_value",
+				"args": {
+					"property": "Style",
+					"value": "Default",
+					"newValue": "Primary",
+					"setId": {
+						"$read": "list_components",
+						"path": "sets.0.id"
+					}
+				}
+			},
+			{
+				"tool": "rename_variant_value",
+				"args": {
+					"property": "Style",
+					"value": "Variant2",
+					"newValue": "Secondary",
+					"setId": {
+						"$read": "list_components",
+						"path": "sets.0.id"
+					}
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "three variants: Primary, Secondary and Disabled",
+			"tool": "list_components",
+			"expect": {
+				"sets": [
+					{
+						"variants": {
+							"$length": 3
+						},
+						"options": [
+							{
+								"name": "Style",
+								"values": {
+									"$expr": "[...v].sort().join() === 'Disabled,Primary,Secondary'"
+								}
+							}
+						]
+					}
+				]
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "list_components"
+		},
+		{
+			"tool": "add_variant",
+			"args": {
+				"setId": {
+					"$read": "list_components",
+					"path": "sets.0.id"
+				},
+				"variant": {
+					"Style": "Disabled"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-canvas-design-system-components/evals/combine-variants.json

@@ -0,0 +1,172 @@
+{
+	"prompt": "These two buttons are versions of one button. Combine them into a single component with a 'Style' property whose values are Primary and Secondary.",
+	"fixture": {
+		"editor": "canvas",
+		"nodes": [
+			{
+				"id": "primary",
+				"type": "group",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Button / Primary"
+				}
+			},
+			{
+				"id": "pbg",
+				"type": "shape",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Bg",
+					"shape": {
+						"kind": "rect",
+						"fill": "#1d3557"
+					}
+				},
+				"parentId": "primary"
+			},
+			{
+				"id": "secondary",
+				"type": "group",
+				"position": {
+					"x": 0,
+					"y": 60
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Button / Secondary"
+				}
+			},
+			{
+				"id": "sbg",
+				"type": "shape",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 120,
+				"height": 40,
+				"data": {
+					"label": "Bg",
+					"shape": {
+						"kind": "rect",
+						"fill": "#ffffff"
+					}
+				},
+				"parentId": "secondary"
+			}
+		],
+		"setup": [
+			{
+				"tool": "create_component",
+				"args": {
+					"ids": [
+						"primary"
+					]
+				}
+			},
+			{
+				"tool": "create_component",
+				"args": {
+					"ids": [
+						"secondary"
+					]
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "one component set with a Style property whose values are Primary and Secondary",
+			"tool": "list_components",
+			"expect": {
+				"sets": {
+					"$length": 1,
+					"$some": {
+						"options": [
+							{
+								"name": "Style",
+								"values": {
+									"$expr": "[...v].sort().join() === 'Primary,Secondary'"
+								}
+							}
+						]
+					}
+				}
+			}
+		},
+		{
+			"why": "the primary button is the Primary variant",
+			"tool": "list_components",
+			"expect": {
+				"components": {
+					"$some": {
+						"id": "primary",
+						"variant": {
+							"Style": "Primary"
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "combine_as_variants",
+			"args": {
+				"ids": [
+					"primary",
+					"secondary"
+				]
+			}
+		},
+		{
+			"tool": "list_components"
+		},
+		{
+			"tool": "rename_variant_property",
+			"args": {
+				"name": "Property 1",
+				"newName": "Style",
+				"setId": {
+					"$read": "list_components",
+					"path": "sets.0.id"
+				}
+			}
+		},
+		{
+			"tool": "rename_variant_value",
+			"args": {
+				"property": "Style",
+				"value": "Default",
+				"newValue": "Primary",
+				"setId": {
+					"$read": "list_components",
+					"path": "sets.0.id"
+				}
+			}
+		},
+		{
+			"tool": "rename_variant_value",
+			"args": {
+				"property": "Style",
+				"value": "Variant2",
+				"newValue": "Secondary",
+				"setId": {
+					"$read": "list_components",
+					"path": "sets.0.id"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-canvas-design-system-components/evals/make-component.json

@@ -0,0 +1,103 @@
+{
+	"prompt": "Turn the card into a reusable component and place two instances of it below the original, side by side.",
+	"fixture": {
+		"editor": "canvas",
+		"nodes": [
+			{
+				"id": "card",
+				"type": "group",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 200,
+				"height": 100,
+				"data": {
+					"label": "Card"
+				}
+			},
+			{
+				"id": "bg",
+				"type": "shape",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 200,
+				"height": 100,
+				"data": {
+					"label": "Bg",
+					"shape": {
+						"kind": "rect",
+						"fill": "#eeeeee"
+					}
+				},
+				"parentId": "card"
+			},
+			{
+				"id": "title",
+				"type": "text",
+				"parentId": "card",
+				"position": {
+					"x": 10,
+					"y": 10
+				},
+				"data": {
+					"label": "Hello",
+					"name": "Title"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "one component, made from the card",
+			"tool": "list_components",
+			"expect": {
+				"components": {
+					"$length": 1,
+					"$some": {
+						"id": "card"
+					}
+				}
+			}
+		},
+		{
+			"why": "two instances below the card",
+			"tool": "get_canvas_document",
+			"expect": {
+				"document": {
+					"nodes": {
+						"$expr": "v.filter((n) => n.data && n.data.instance && n.position.y >= 100).length === 2"
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "create_component",
+			"args": {
+				"ids": [
+					"card"
+				]
+			}
+		},
+		{
+			"tool": "create_instance",
+			"args": {
+				"componentId": "card",
+				"x": 0,
+				"y": 150
+			}
+		},
+		{
+			"tool": "create_instance",
+			"args": {
+				"componentId": "card",
+				"x": 240,
+				"y": 150
+			}
+		}
+	]
+}

package/skills/pixerate-canvas-layout/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: pixerate-canvas-layout
+description: The layout workflow in the Pixerate canvas - tidying a board or screen by aligning edges and centres, distributing elements evenly, keeping consistent spacing on a grid, ordering layers so the right things are on top, grouping related elements, locking backgrounds and guides, and checking the result. Use when asked to align, line up, centre, distribute, space evenly, tidy, clean up or lay out elements on a canvas, board, screen, slide or wireframe, bring something to the front or send it back, or lock a layer, or when canvas.alignLeft, canvas.distributeHorizontal, canvas.bringToFront or canvas.lock are available. Load with pixerate-canvas, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-canvas
+---
+
+# Laying out a canvas
+
+A tidy layout comes from a few relations applied deliberately: shared edges and centres,
+equal gaps, a consistent spacing scale, and a stacking order where what matters is on top.
+Use the arrange commands rather than moving nodes by hand: they act on exact geometry, keep
+other axes untouched, and are one undo step each.
+
+This skill is the method. `pixerate-canvas` has the full tool reference; run the `canvas.*`
+commands with `run_command` (`params: { ids }`) or several in one `run_commands` batch.
+
+## Goal and quality bar
+
+- Elements in a row share a top, centre or bottom; elements in a column share a left, centre or
+  right edge.
+- Gaps between repeated elements are equal, on the spacing scale (multiples of 4 or 8).
+- The stacking order matches meaning: backgrounds at the back, content above, badges, overlays
+  and annotations on top.
+- Backgrounds, guides and finished areas are locked so they cannot be moved by accident.
+- Only the intended axis changes: aligning tops does not move anything sideways.
+
+## Inputs to confirm
+
+- **Which elements** belong together (a row of cards, a form column) and the anchor (the first
+  element, the container, the canvas).
+- **Spacing:** equal distribution between fixed ends, or a set gap.
+- **What must stay put**, and what to lock.
+
+## Working method
+
+1. **Read.** `get_canvas_document` for node ids, positions, sizes, parents and z-order.
+   **Check:** you know the rows, columns and stacking you want.
+2. **Align** rows and columns: `canvas.alignTop`, `canvas.alignMiddle`, `canvas.alignBottom`,
+   `canvas.alignLeft`, `canvas.alignCenter`, `canvas.alignRight` with the group's `ids`.
+   **Check:** the shared coordinate is equal; the other axis is unchanged.
+3. **Distribute** repeated elements: `canvas.distributeHorizontal` or `canvas.distributeVertical`
+   (the outer elements stay, the gaps between them become equal).
+   **Check:** the gaps are equal within a pixel.
+4. **Order layers.** `canvas.bringToFront`, `canvas.bringForward`, `canvas.sendBackward`,
+   `canvas.sendToBack`; order is by `zIndex`, then document order.
+   **Check:** what must be on top has the highest effective order.
+5. **Lock** backgrounds and finished parts: `canvas.lock` (`canvas.unlock` to edit again).
+   **Check:** locked nodes are no longer draggable in `get_canvas_document`.
+6. **Look** with the host's view (`capture_view`, `view_editor`) when available.
+
+## Decision table
+
+| Want | Command |
+| --- | --- |
+| A row lined up | `canvas.alignTop` (or `canvas.alignMiddle` for mixed heights) |
+| A column lined up | `canvas.alignLeft` (or `canvas.alignCenter`) |
+| Even gaps between fixed ends | `canvas.distributeHorizontal` / `canvas.distributeVertical` |
+| Something hidden behind | `canvas.bringToFront` |
+| A background covering content | `canvas.sendToBack` |
+| One step up or down | `canvas.bringForward` / `canvas.sendBackward` |
+| Protect a background or guide | `canvas.lock` |
+
+## Recipes
+
+**Line up a row of cards.** `run_command` `{ id: "canvas.alignTop", params: { ids: ["a", "b",
+"c"] } }`.
+
+**Even spacing.** `run_command` `{ id: "canvas.distributeHorizontal", params: { ids } }`; the
+leftmost and rightmost stay where they are.
+
+**Badge on top, background locked.** `run_commands` with `canvas.bringToFront` `{ ids: ["badge"]
+}` and `canvas.lock` `{ ids: ["backdrop"] }`.
+
+## Pitfalls
+
+- **Moving by hand** with rounded numbers drifts; align and distribute act on exact geometry.
+- **Distributing two elements** does nothing; it needs at least three.
+- **Aligning across different parents** aligns in each parent's own space; group or reparent
+  first.
+- **Stacking by array order only**: `zIndex` wins over order; read the effective order.
+- **Locked nodes** refuse moves; unlock, change, lock again.
+- **Aligning everything to one edge** of the canvas when the group should align to itself.
+
+## Tools used
+
+- `get_canvas_document`: node positions, sizes, parents, z-order and locks
+- `canvas.alignLeft`, `canvas.alignCenter`, `canvas.alignRight`: column alignment
+- `canvas.alignTop`, `canvas.alignMiddle`, `canvas.alignBottom`: row alignment
+- `canvas.distributeHorizontal`, `canvas.distributeVertical`: even gaps
+- `canvas.bringToFront`, `canvas.bringForward`, `canvas.sendBackward`, `canvas.sendToBack`: stacking order
+- `canvas.lock`, `canvas.unlock`: protect backgrounds and finished parts
+- `capture_view`, `view_editor`: look at the result
+- `undo_canvas`: take back a step

package/skills/pixerate-canvas-layout/evals/align-tops.json

@@ -0,0 +1,98 @@
+{
+	"prompt": "Line up the tops of the three cards.",
+	"fixture": {
+		"editor": "canvas",
+		"nodes": [
+			{
+				"id": "a",
+				"type": "shape",
+				"position": {
+					"x": 0,
+					"y": 10
+				},
+				"width": 100,
+				"height": 80,
+				"data": {
+					"label": "Card A",
+					"shape": {
+						"kind": "rect",
+						"fill": "#eeeeee"
+					}
+				}
+			},
+			{
+				"id": "b",
+				"type": "shape",
+				"position": {
+					"x": 130,
+					"y": 30
+				},
+				"width": 100,
+				"height": 80,
+				"data": {
+					"label": "Card B",
+					"shape": {
+						"kind": "rect",
+						"fill": "#eeeeee"
+					}
+				}
+			},
+			{
+				"id": "c",
+				"type": "shape",
+				"position": {
+					"x": 300,
+					"y": 0
+				},
+				"width": 100,
+				"height": 80,
+				"data": {
+					"label": "Card C",
+					"shape": {
+						"kind": "rect",
+						"fill": "#eeeeee"
+					}
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "all three tops at the same y",
+			"tool": "get_canvas_document",
+			"expect": {
+				"document": {
+					"nodes": {
+						"$expr": "new Set(v.map((n) => n.position.y)).size === 1"
+					}
+				}
+			}
+		},
+		{
+			"why": "the horizontal positions are unchanged",
+			"tool": "get_canvas_document",
+			"expect": {
+				"document": {
+					"nodes": {
+						"$expr": "v.map((n) => n.position.x).join() === '0,130,300'"
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "canvas.alignTop",
+				"params": {
+					"ids": [
+						"a",
+						"b",
+						"c"
+					]
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-canvas-layout/evals/distribute-evenly.json

@@ -0,0 +1,98 @@
+{
+	"prompt": "Space the three cards evenly across, keeping the first and last where they are.",
+	"fixture": {
+		"editor": "canvas",
+		"nodes": [
+			{
+				"id": "a",
+				"type": "shape",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 100,
+				"height": 80,
+				"data": {
+					"label": "Card A",
+					"shape": {
+						"kind": "rect",
+						"fill": "#eeeeee"
+					}
+				}
+			},
+			{
+				"id": "b",
+				"type": "shape",
+				"position": {
+					"x": 120,
+					"y": 0
+				},
+				"width": 100,
+				"height": 80,
+				"data": {
+					"label": "Card B",
+					"shape": {
+						"kind": "rect",
+						"fill": "#eeeeee"
+					}
+				}
+			},
+			{
+				"id": "c",
+				"type": "shape",
+				"position": {
+					"x": 300,
+					"y": 0
+				},
+				"width": 100,
+				"height": 80,
+				"data": {
+					"label": "Card C",
+					"shape": {
+						"kind": "rect",
+						"fill": "#eeeeee"
+					}
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "equal gaps between the cards",
+			"tool": "get_canvas_document",
+			"expect": {
+				"document": {
+					"nodes": {
+						"$expr": "(() => { const xs = v.map((n) => n.position.x).sort((p, q) => p - q); return Math.abs((xs[1] - xs[0]) - (xs[2] - xs[1])) <= 1; })()"
+					}
+				}
+			}
+		},
+		{
+			"why": "the outer cards stay put",
+			"tool": "get_canvas_document",
+			"expect": {
+				"document": {
+					"nodes": {
+						"$expr": "v.find((n) => n.id === 'a').position.x === 0 && v.find((n) => n.id === 'c').position.x === 300"
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "canvas.distributeHorizontal",
+				"params": {
+					"ids": [
+						"a",
+						"b",
+						"c"
+					]
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-canvas-layout/evals/order-and-lock.json

@@ -0,0 +1,110 @@
+{
+	"prompt": "The badge is hidden behind the card: bring it to the front, and lock the background so it can't be moved by accident.",
+	"fixture": {
+		"editor": "canvas",
+		"nodes": [
+			{
+				"id": "backdrop",
+				"type": "shape",
+				"position": {
+					"x": 0,
+					"y": 0
+				},
+				"width": 400,
+				"height": 300,
+				"data": {
+					"label": "Background",
+					"shape": {
+						"kind": "rect",
+						"fill": "#f1faee"
+					}
+				}
+			},
+			{
+				"id": "badge",
+				"type": "shape",
+				"position": {
+					"x": 280,
+					"y": 20
+				},
+				"width": 40,
+				"height": 40,
+				"data": {
+					"label": "Badge",
+					"shape": {
+						"kind": "rect",
+						"fill": "#e63946"
+					}
+				}
+			},
+			{
+				"id": "card",
+				"type": "shape",
+				"position": {
+					"x": 40,
+					"y": 20
+				},
+				"width": 300,
+				"height": 200,
+				"data": {
+					"label": "Card",
+					"shape": {
+						"kind": "rect",
+						"fill": "#ffffff"
+					}
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the badge is drawn last (on top)",
+			"tool": "get_canvas_document",
+			"expect": {
+				"document": {
+					"nodes": {
+						"$expr": "(() => { const z = (n) => (typeof n.zIndex === 'number' ? n.zIndex : 0); const order = v.map((n, i) => ({ id: n.id, z: z(n), i })).sort((a, b) => a.z - b.z || a.i - b.i); return order[order.length - 1].id === 'badge'; })()"
+					}
+				}
+			}
+		},
+		{
+			"why": "the background is locked",
+			"tool": "get_canvas_document",
+			"expect": {
+				"document": {
+					"nodes": {
+						"$some": {
+							"id": "backdrop",
+							"$expr": "v.draggable === false || (v.data && v.data.locked === true) || v.locked === true"
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "canvas.bringToFront",
+				"params": {
+					"ids": [
+						"badge"
+					]
+				}
+			}
+		},
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "canvas.lock",
+				"params": {
+					"ids": [
+						"backdrop"
+					]
+				}
+			}
+		}
+	]
+}