@pixerate/editor 0.80.0 → 0.81.0

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

@@ -0,0 +1,155 @@
+---
+name: pixerate-animation-editor
+description: How to author and edit vector animations (motion graphics, logo reveals, animated icons, explainer scenes, UI micro-interactions) in the Pixerate animation editor through its agent tools - artwork SVG with ids, shots of commands (enter, exit, draw, move, rotate, scale, fade, morph, Smart Animate match, follow a path, pulse, shake, wiggle), easing and springs, stagger, camera, beat and voiceover cues, drivers, reusable clips, checking, rendering frames and contact sheets, and exporting to Flair or Lottie. Use when animation tools such as get_animation, insert_shots or edit_animation are available, or when asked to animate, time, ease, stagger or export vector motion.
+---
+
+# Pixerate animation editor
+
+A scene is **artwork** (an SVG parsed into vector paths and groups, each with an id) plus an
+ordered list of **shots**. A shot optionally moves the camera, plays its `run` of commands,
+then holds (default 600 ms). Commands play one after another unless `"with": "previous"`;
+each has a default length taken from the content (enter 600 ms, exit 450, move 700, draw
+follows the path length), so leave `duration` out unless you mean to change the pace. Every
+frame is a pure function of time.
+
+Ids: element ids come from `get_animation` (`elements`) or `find_animation_elements`; shot ids
+are ones you choose (`"intro"`); commands are addressed by shot id plus their index in the run.
+Times are milliseconds, positions are document units of the artwork. Anything that enters
+later is hidden until its `enter`; anything that never enters is visible from the start.
+
+For errors, namespaced tool names and the generic command tools, see `pixerate-agent-tools`.
+The full command vocabulary (every type, option and default) is in
+[references/commands.md](references/commands.md).
+
+## Working method
+
+1. **Read.** `get_animation` for elements, shots with timing, clips, drivers and issues. If
+   there is no artwork, `set_animation_artwork_svg` first (give every element you will animate
+   an id), or start from `import_flair_effect` / `import_pptx_animation`. For outlined text,
+   `get_text_layout` shows the letter, word and line units.
+2. **Plan shots, one idea each.** Write down what the viewer should notice in each shot and in
+   what order, then map each beat to a command. Hidden end states (morph / match targets,
+   follow paths) must exist in the artwork before you reference them.
+3. **Write in batches.** `insert_shots` for whole shots; `edit_animation` for several related
+   edits as one undo step (`dry_run: true` first when unsure; `"$0.indexes[0]"` and
+   `"$last.shot"` refer to earlier ops). Refine with `add_commands`, `update_command`,
+   `move_command`, `delete_commands`. Use `write_animation` only to replace every shot.
+4. **Fit and cue.** `fit_animation` to hit a length (keep shots whose pace matters). For music
+   or voiceover, `set_animation_settings` with `beat` or `narration`, read cues with
+   `get_timing_grid`, and give shots `"at": { "beat": n }` or `{ "word": i }`.
+5. **Check.** `check_animation`; fix every error and warning (codes such as `too-fast`,
+   `overlap`, `out-of-frame`, `enter-visible`, `cue-missed`). Use `get_motion_path` for
+   spacing and arcs as numbers.
+6. **Look.** `render_animation_frame` with `shot` + `at: "end"`, or `times` for a contact sheet,
+   plus `onion_skin` / `motion_paths` to see motion in one picture. Render after a batch, not
+   after every edit. `seek_animation` shows the person a moment.
+7. **Export** when asked: `export_flair_motion`, `export_flair_effect` (after
+   `set_animation_controls`) or `export_lottie`; read the returned notes on what was sampled
+   or dropped.
+
+## Best practices
+
+- **One idea per shot, one focal motion at a time.** Stage the action so the eye knows where
+  to look; secondary elements move less, later, or not at all. Use the camera (`frame` a
+  node) to direct attention rather than moving everything.
+- **Ease every change.** Arrivals ease out (decelerate into place; the default for `enter`),
+  exits ease in (`exit` with `ease: "ease-in"`), moves ease in-out (the default). Use `linear`
+  only for mechanical motion (a constant spin, a progress bar) or loops.
+- **Timing by size and distance.** Small UI changes 150-300 ms, element entrances 300-600 ms,
+  large moves and camera moves 600-1200 ms. Nothing under 120 ms (`too-fast`). Big things
+  move slower than small things.
+- **Anticipation and follow-through.** `ease-in-back` for a wind-up before a fast exit;
+  `pop`, `rise`, `ease-out-back` or a spring preset (`spring-gentle`, `spring-quick`) for
+  overshoot and settle on arrival. Use `spring-bouncy` sparingly; it reads as playful.
+- **Overlapping action.** Stagger related items 40-120 ms (`stagger`, or `split` with
+  `cascade` for text) instead of moving them in lockstep; start secondary motion with
+  `"with": "previous"` plus a small `delay` so it trails the lead.
+- **Arcs.** Natural movement curves: use `move` with `via` waypoints (one smooth path) instead
+  of chained moves that stop at each point, or `follow` a path node.
+- **Hold long enough to read.** Leave each result on screen (shot `hold`, default 600 ms);
+  roughly 250 ms per word for text that must be read, longer for the final frame or logo.
+- **Exaggeration with restraint.** Emphasis (`pulse`, `shake`, `teeter`, `color-pulse`) is for
+  one thing that needs attention, once; it returns to rest on its own.
+- **Motion blur** only for genuinely fast motion (`motionBlur: { shutter: 180 }`); it affects the
+  stage and rendered frames, not Flair or Lottie exports.
+- **Accessibility.** Avoid flashing: never more than three flashes a second (WCAG 2.3.1), so
+  keep `color-pulse` and fades on large areas slow and few. Avoid large-scale parallax, zooms
+  and spinning for essential UI motion; ship a reduced-motion alternative (the host should
+  swap in a fade or the end state under `prefers-reduced-motion`; this editor does not
+  generate one). Loops that run longer than 5 s need a way to pause (WCAG 2.2.2).
+- **Interactive pieces.** For a button or toggle set `trigger` (`click`, `hover`, `press`,
+  `scroll`); for a click toggle, make the last shot restore the starting state.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_animation` | Start here. Returns name, artwork size, length (ms), loop, elements (id, type, name, parent, bounds, solid paints, live effects with numeric params), every shot with each command's index, start, end and `flairPrimitive`, clips, drivers, controls and an issue summary, plus `readOnly` when edits are refused. `includeElements: false` (default true) skips the element list on large artwork. |
+| `get_shot` | Read one shot as stored (`shot` id) with its start/end and each command's start/end in ms; cheaper than `get_animation` while refining one shot. |
+| `find_animation_elements` | Find elements whose id or name contains `query` (case-insensitive; `limit` default 20, max 200) when the artwork is large. Returns id, type, name, parent, bounds, paints, effects. |
+| `get_text_layout` | Before animating outlined text with `split`: returns the `group`'s lines, words and letter ids in reading order. Errors if the element is not a group of paths (convert text to outlines, one path a letter, and group it). |
+| `get_motion_path` | Check spacing, arcs and landing points as numbers: samples a `node`'s centre (document units) from `from` to `to` ms every `step` ms (default 33, at most 400 samples), with where each moving change starts and ends. |
+| `get_timing_grid` | List beats (number, ms, bar, beat in bar) and narration words (index, text, start, end) between `from` and `to` (`limit` default 200), and which shot plays at each, to choose `at` cues. Empty, with a hint, when no beat grid or narration is set. |
+| `check_animation` | After every batch of writes. Lists issues with a code, severity, shot, command index, node ids, measured vs needed values and how to fix it. Fix errors and warnings; notes are advisory. |
+| `render_animation_frame` | Look at the result: `time` (ms) or `shot` + `at` (`start`, `middle`, `end`; default end). `times` (2-16 moments) makes a labelled contact sheet (`columns` 1-8). `onion_skin` adds ghost frames (`before` default 2, `after` 0, `spacing` ms or `"commands"`); `motion_paths` (true or ids) draws travel paths. SVG by default; `format: "png"` only when the host can rasterize. |
+| `export_flair_motion` | Get the scene as a Flair SvgMotion `{ svg, animate }` with hold, sampled-step count and notes. `fps` (default scene fps, else 30), `curves` and `behaviors` (default true), `flair` target version (default 0.39; older versions get springs, steps, behaviours and curves sampled). |
+| `export_flair_effect` | Get a Flair catalog vector effect (`id` kebab-case, `name`, `description`, `category` default icon, `tags`, plus `curves` / `behaviors` / `flair` as above). Call `set_animation_controls` first so colours become `{{name: color}}` controls. |
+| `export_lottie` | Get Lottie (Bodymovin v5) JSON for lottie-web and mobile players, with a marker per shot, `fps` (default scene fps, else 30), the sampled keyframe count and notes on what was not carried over (gradients, dashes, reveal clips, morphs that change point counts). |
+
+### Write
+
+| Tool | Use it to |
+| --- | --- |
+| `seek_animation` | Show the person a moment: `time` (ms) or the start of a `shot`, with `play` true or false. Does not change the scene. |
+| `set_animation_artwork_svg` | Replace the artwork with a standalone `svg` (with a viewBox) as one undo step. Put an id on every element you will animate; refused if existing shots name ids the new artwork lacks. Returns the elements. |
+| `import_pptx_animation` | Replace the whole scene with a PowerPoint slide's shapes and animation pane (`data` base64 .pptx, `slide` default 1): one shot per click, delays, repeats and acceleration kept; text, pictures and charts are left out with notes. Run with `dry_run: true` first. |
+| `set_animation_drivers` | Replace all drivers (empty list clears): a target's `x`, `y`, `rotation`, `scaleX`, `scaleY` or `opacity` follows a source node's property as change · `factor` + `offset`, optionally `clamp`ed. For parallax, wheels that turn as they roll, shadows that fade as something rises. |
+| `set_animation_clip` | Define, replace or (with `clip: null`) delete a named reusable clip whose `run` targets `"$"`; play it with a `play` command on any nodes. Prefer a clip over repeated identical commands. |
+| `copy_animation` | Give the nodes in `to` every command that animates `from` (all shots or `shots`), each copy starting with its original, optionally `stagger`ed (ms). Quick for one-off duplication; use a clip for motion you will reuse. |
+| `fit_animation` | Make the scene last `seconds` by setting shot `speed`, keeping proportions; shots in `keep` play as written. `dry_run: true` reports the new length and speeds first. |
+| `import_flair_effect` | Replace the whole scene with a Flair vector `effect` or SvgMotion `motion` (give exactly one; optional `name`). Placeholders become colour controls; each Flair step becomes a shot. Use `dry_run: true` first. |
+| `insert_shots` | Add one or more complete shots (`id`, `run`, optional `label`, `camera`, `hold`, `speed`, `at`) at position `at` (default the end). Returns every shot's timing and issues. |
+| `update_shot` | Change one shot's `label`, `camera`, `run`, `hold`, `speed`, `at` or `id` via `set`, and clear `label`, `camera`, `hold`, `speed` or `at` via `remove`. |
+| `delete_shots` | Remove shots by id (one undo step). |
+| `move_shot` | Reorder a shot to index `to` (0 = first). |
+| `add_commands` | Add commands to a shot's run at index `at` (default the end). Returns the indexes they got and their timing; use those indexes for later updates. |
+| `update_command` | Change one command (by `shot` and `command` index): fields in `set` replace, names in `remove` clear (e.g. `"delay"`). Returns the command and its timing. |
+| `delete_commands` | Remove commands from a shot by index; later commands move up, so re-read indexes afterwards. |
+| `move_command` | Move one command to index `to` in its run; a `"with": "previous"` command then starts with its new neighbour. |
+| `set_animation_settings` | Set `name`, `description`, `loop` (none, loop, ping-pong), `trigger` (click, hover, press, scroll, or null), export `fps` (default 30), scene `steps` (12 = on twos; null smooth), `motionBlur`, `beat` (`bpm`, `offset`, `meter`), `narration` word timings, or `target` length [min, max] seconds. |
+| `set_animation_controls` | Set the colour controls (`name`, `type: "color"`, `default` #rrggbb used in the scene, `label`) and `presets` a Flair effect exposes. Replaces existing controls; an empty list clears. |
+| `edit_animation` | Apply several ops (`set_settings`, `insert_shots`, `update_shot`, `delete_shots`, `move_shot`, `add_commands`, `update_command`, `move_command`, `delete_commands`, `set_controls`) as one all-or-nothing undo step; refer to earlier outcomes with `"$0.indexes[0]"`, `"$last.shot"`. `dry_run: true` validates without applying. The default for multi-step changes. |
+| `write_animation` | Replace every shot (and optionally settings, controls, presets) while keeping the artwork. Only for a full rewrite; per-operation tools give better errors. |
+| `undo_animation` | Undo your last edit (one tool call or one `edit_animation` batch). |
+| `redo_animation` | Redo the edit you just undid. |
+
+## Pitfalls
+
+- **Unknown ids are refused** with a "did you mean" suggestion. Take ids from `get_animation` or
+  the elements `set_animation_artwork_svg` returns; never guess them.
+- **`enter-visible`**: an element that enters while already showing blinks out first. Give an
+  element that should appear later an `enter` before anything else moves it; do not `enter` an
+  element that should be visible from the start. `exit-hidden` is the reverse: enter it first.
+- **`overlap`**: two commands changing the same property at once; the later takes over. Sequence
+  them, or use `"blend": "add"` on move, rotate or scale to stack. Emphasis already stacks.
+- **Reveals need a box**: `wipe`, `iris`, `split` on a lone straight line fade instead
+  (`reveal-no-box`); use `draw` / `undraw` for lines.
+- **Morph and match targets stay hidden.** Draw the end state as a separate hidden node or group;
+  for `match`, parts the end state adds need a partner (same name) in the start group, or they
+  never appear (`match-unpaired`).
+- **Draw a group one way.** Do not mix per-stroke drawing (`order`, `pace`, `comet`) with a plain
+  `draw` on the same group in one scene.
+- **Indexes shift.** After `delete_commands` or `move_command`, indexes change; use what the write
+  returned or `get_shot` before the next index-based edit.
+- **Springs set their own length.** Leave `duration` out with a spring; a short `duration` cuts it
+  off (`spring-cut-short`).
+- **Click triggers** play nothing until the first click; each click plays the next shot. A
+  triggered scene ignores `loop` (`trigger-loop`), and clicks decide when shots start, so do not
+  give its shots `at` cues (`click-cue`).
+- **Exports approximate.** Motion blur is never exported; Lottie drops gradients, dashes and reveal
+  clips; back eases on colours or opacity are sampled for Flair. Read the notes and tell the
+  user what changed.
+- **Read-only**: when `get_animation` returns `readOnly`, write tools are hidden; read, render and
+  export still work. Tell the user rather than working around it.

package/skills/pixerate-animation-editor/references/commands.md

@@ -0,0 +1,123 @@
+# Animation command vocabulary
+
+Every command is an object with a `type` and (except `wait`) `targets`: element ids from
+`get_animation`. A group animates as one. Times are ms, distances document units, angles
+degrees clockwise. Commands share names and defaults with Flair's motion primitives
+(`get_animation` shows each command's `flairPrimitive`).
+
+## Fields every command takes
+
+- `targets`: element ids (at least one).
+- `duration`: length per target. Leave it out: each type has a default (below) and `draw`
+  follows the path length. With `repeat`, it is one cycle.
+- `delay`: wait before starting (default 0).
+- `stagger`: start each further target this much later (default 0).
+- `with`: `"after"` (default) starts when the commands before it finish; `"previous"` starts
+  together with the command before.
+- `ease`: a preset (`linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, `ease-in-back`,
+  `ease-out-back`, `ease-out-elastic`, `ease-in-elastic`, `ease-in-out-elastic`, `elastic`,
+  `spring`, `spring-gentle`, `spring-quick`, `spring-bouncy`, `spring-slow`, `hold`), or
+  `{ "type": "cubic-bezier", x1, y1, x2, y2 }`, `{ "type": "spring", stiffness (170),
+  damping (26), mass (1), velocity (0) }`, `{ "type": "elastic", amplitude (1), period (0.3),
+  mode (out | in | in-out) }`. Default: cubic ease-out for entrances, ease-in-out for moves.
+  A spring with no `duration` lasts until it settles.
+- `note`: why the command is there, in a few words.
+- `split`: `letter`, `word` or `line` for outlined text (a group of letter paths), staggered
+  40 / 120 / 300 ms per unit; `cascade`: `forward` (default), `backward`, `center`, `edges`,
+  `random` (deterministic).
+- `repeat` (1-1000, not for enter or exit) and `repeatMode`: `loop` (default), `mirror`
+  (every other cycle backwards), `offset` (carry on: rotate by 90 with repeat 4 is a full turn).
+- `steps`: hold poses on a grid of this many frames per second (12 = on twos).
+
+## Default lengths (ms)
+
+enter 600, exit 450, move 700 (+400 per `via` point), rotate 700, scale 500, fade 400,
+style 500, morph 900, match 900, follow 1400, pulse 600, shake 500, teeter 600, wave 1000,
+wiggle 1500, color-pulse 600, effect 900, play (the clip's own length). Shot hold 600,
+camera move 1000.
+
+## Entrances and exits
+
+- `enter` brings hidden targets in. `style`:
+  - `fade` (default); `pop` (scales up past full size and settles; `scale` start, default 0.5);
+    `grow` (from nothing); `slide` (`direction` of travel, default up; `distance` default 40);
+    `draw` (outline drawn on, then the fill fades in); `zoom` (settles from larger; `scale`
+    default 1.6); `rise` (rises a short way, overshooting a touch; `distance` default 20).
+  - Reveals through a clip over the target's box: `wipe` (edge travels `direction`, default
+    right), `iris` (from the centre; `shape` circle or box), `split` (from a line through the
+    middle; `orientation` horizontal or vertical). Need a box with width and height.
+  - Drawing options for groups: `order` (`together` default, or `sequence`), `pace` (`time`
+    or `speed`), `align` (`start` / `end`, with speed), `sortBy` (`document` or `distance`,
+    with sequence), `origin` { x, y } for a radial reveal.
+- `exit` takes targets out. `style`: `fade` (default), `shrink`, `slide` (default down,
+  `distance` 40), `undraw`, `wipe`. Same drawing options as enter.
+
+## Pose and paint
+
+- `move`: `by` { x, y } offset or `to` { x, y } for the centre. `via`: up to 64 waypoints the
+  centre passes through smoothly without overshoot; `pacing` `even` (default, steady speed)
+  or `equal` (same time per stretch). `blend` default replace.
+- `rotate`: `by` degrees or `to` degrees from rest. `blend` default replace.
+- `scale`: `to` a factor or { x, y } (required); `geometric: true` for an even-rate zoom.
+- `fade`: `to` opacity 0-1 (required).
+- `style`: blends solid `fill`, `stroke` (CSS colours, mixed in OKLab) and `strokeWidth`. On a
+  group it changes every path in it.
+- `draw`: draws strokes to `to` (default 1) from `from` (default what is drawn now);
+  `comet`: a travelling stroke this fraction long that runs off the end. Drawing options as
+  enter.
+
+## Shape change and paths
+
+- `morph`: each target takes the shape and paint of node `into` (keep `into` hidden).
+- `match` (Smart Animate): tweens a group into group `into`, part by part. Parts pair by name,
+  then by id with the group ids taken out (`card-a-title` and `card-b-title`), then by kind in
+  order. Unpaired parts fade out; parts of `into` with no partner never appear.
+- `follow`: moves targets along path node `path` (it can be hidden), `from` / `to` fractions
+  (default 0 / 1); `rotate: true` turns with the path, and moves or shakes made meanwhile turn
+  with it.
+
+## Emphasis (returns to rest; `blend` default add, so it stacks on other motion)
+
+- `pulse`: scales up and back; `amount` extra scale (0.15), `count` (1).
+- `shake`: side to side, settling; `amount` (8), `count` (3), `axis` horizontal or vertical.
+- `teeter`: rocks about the centre; `angle` (8), `count` (3).
+- `wave`: bobs without settling; `amount` (6), `count` (2).
+- `wiggle`: smooth seeded noise; `amount` (6), `frequency` Hz (3), `octaves` (2), `rotate`
+  degrees (0), `seed` (default from the target id; the same seed wanders the same way).
+- `color-pulse`: tints `fill` or `stroke` (`paint`) toward `color` (default #f59e0b) and back;
+  `count` (1).
+
+`blend: "add"` on move, rotate or scale makes them a stacking layer too (what they add stays);
+`blend: "replace"` on emphasis makes it take over instead.
+
+## Other
+
+- `effect`: tweens numeric `param` of live path effect `effect` (ids from the element's
+  `effects` in `get_animation`) `to` a value.
+- `play`: plays clip `clip` (defined with `set_animation_clip`, commands targeting `"$"`) on
+  the targets; `speed` (0.05-20, default 1), `delay`, `stagger`, `with`. Clips cannot play clips.
+- `wait`: waits `duration` ms (no targets).
+
+## Shots
+
+`{ id, run, label?, camera?, hold?, speed?, at? }`
+
+- `id` matches `^[A-Za-z0-9_][\w.-]*$` and is unique.
+- `camera`: `{ x, y, width, height }` or `{ frame: "<node id>", padding (24) }`, with `ms`
+  (default 1000), `ease`, `geometric`. The first shot cuts to its camera.
+- `hold`: ms after the commands (default 600).
+- `speed`: plays the whole shot this many times as fast (0.05-20; `fit_animation` sets it).
+- `at`: `{ beat: n }` (2.5 is the "and" of beat 3), `{ word: i }` or `{ ms: t }`; the shot
+  before holds until the cue. Needs a `beat` grid or `narration` set with
+  `set_animation_settings`; `check_animation` reports `cue-missed` when the previous shot runs
+  past it.
+
+## Drivers
+
+`set_animation_drivers({ drivers: [{ target, property, source: { node, property }, factor (1),
+offset (0), clamp: [min, max] }] })`, properties `x`, `y`, `rotation`, `scaleX`, `scaleY`,
+`opacity`. The target's change from rest = source change · factor + offset, added to offsets
+and turns, multiplied into scales and opacity, on top of the target's own commands. Examples:
+parallax (`x` follows `x` · 0.5), a rolling wheel (`rotation` follows `x` · 360 / (2π · radius)),
+a shadow that fades as a ball rises (`opacity` follows `y` · 0.005). Cycles are reported by
+`check_animation` (`driver-cycle`).

package/skills/pixerate-canvas/SKILL.md

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