@pixerate/editor 0.279.1 → 0.281.0

package/dist/vector/commands.d.cts

@@ -4,6 +4,7 @@ import type { VectorBooleanOperation } from './types.cjs';
 import { type VectorEffect } from './types.cjs';
 import { type VectorBlendMode, type VectorFilter, type VectorPaintLayer, type VectorStrokeLayer } from './types.cjs';
 import { type VectorMaskSummary } from './mask.cjs';
+import { type VectorTracePixels } from './trace.cjs';
 import { type VectorLens, type VectorSymmetry } from './types.cjs';
 import { type VectorConnector } from './types.cjs';
 import { type VectorFrame, type VectorResizing } from './types.cjs';
@@ -14,7 +15,31 @@ export interface VectorCommandOptions {
     group?: string;
     /** Command scope. Omit for global commands. */
     scope?: string;
+    /**
+     * Loads an image that `vector.traceImage` and the stylise commands (`vector.mosaicImage`, …)
+     * are given by reference instead of as a PNG data URL: an http(s) or asset URL, or a host id
+     * such as a canvas node's. Agents can name an image but cannot write out its bytes, so without
+     * this they can only trace PNGs they produced themselves. Return `null` when there is no such
+     * image; throw (or reject) with a sentence when it cannot be loaded. `maxPixels` is the most the
+     * commands trace: scale larger images down to fit.
+     */
+    resolveImage?: VectorImageResolver;
+    /**
+     * What `resolveImage` accepts, for the `image` argument's description (default "an image
+     * URL"), e.g. "the id of an image node on the canvas, or an http(s) URL".
+     */
+    imageReferences?: string;
 }
+/** An image a host loaded for a reference: RGBA pixels, or a PNG (data URL or bytes). */
+export type VectorResolvedImage = {
+    image: VectorTracePixels;
+} | {
+    png: string | Uint8Array;
+};
+/** See `VectorCommandOptions.resolveImage`. */
+export type VectorImageResolver = (ref: string, options: {
+    maxPixels: number;
+}) => VectorResolvedImage | null | undefined | Promise<VectorResolvedImage | null | undefined>;
 /** A node as listed for agents. */
 export interface VectorNodeListing {
     id: string;

package/dist/vector/commands.d.ts

@@ -4,6 +4,7 @@ import type { VectorBooleanOperation } from './types.js';
 import { type VectorEffect } from './types.js';
 import { type VectorBlendMode, type VectorFilter, type VectorPaintLayer, type VectorStrokeLayer } from './types.js';
 import { type VectorMaskSummary } from './mask.js';
+import { type VectorTracePixels } from './trace.js';
 import { type VectorLens, type VectorSymmetry } from './types.js';
 import { type VectorConnector } from './types.js';
 import { type VectorFrame, type VectorResizing } from './types.js';
@@ -14,7 +15,31 @@ export interface VectorCommandOptions {
     group?: string;
     /** Command scope. Omit for global commands. */
     scope?: string;
+    /**
+     * Loads an image that `vector.traceImage` and the stylise commands (`vector.mosaicImage`, …)
+     * are given by reference instead of as a PNG data URL: an http(s) or asset URL, or a host id
+     * such as a canvas node's. Agents can name an image but cannot write out its bytes, so without
+     * this they can only trace PNGs they produced themselves. Return `null` when there is no such
+     * image; throw (or reject) with a sentence when it cannot be loaded. `maxPixels` is the most the
+     * commands trace: scale larger images down to fit.
+     */
+    resolveImage?: VectorImageResolver;
+    /**
+     * What `resolveImage` accepts, for the `image` argument's description (default "an image
+     * URL"), e.g. "the id of an image node on the canvas, or an http(s) URL".
+     */
+    imageReferences?: string;
 }
+/** An image a host loaded for a reference: RGBA pixels, or a PNG (data URL or bytes). */
+export type VectorResolvedImage = {
+    image: VectorTracePixels;
+} | {
+    png: string | Uint8Array;
+};
+/** See `VectorCommandOptions.resolveImage`. */
+export type VectorImageResolver = (ref: string, options: {
+    maxPixels: number;
+}) => VectorResolvedImage | null | undefined | Promise<VectorResolvedImage | null | undefined>;
 /** A node as listed for agents. */
 export interface VectorNodeListing {
     id: string;

package/dist/vector/index.cjs

@@ -16551,17 +16551,72 @@ function createVectorCommands(controller, options = {}) {
       }
     }
   ];
+  const resolveImage = options.resolveImage;
+  const IMAGE_WHAT = resolveImage ? "an image (a PNG data URL, or a reference the editor loads)" : "a PNG (base64 data URL)";
+  const IMAGE_PARAM = {
+    type: "string",
+    description: resolveImage ? `The image: a data:image/png;base64,\u2026 URL, or ${_nullishCoalesce(options.imageReferences, () => ( "an image URL"))} (up to ${_chunkMNHP3AQTcjs.VECTOR_TRACE_MAX_PIXELS / 1e6} million pixels).` : "The image as a data:image/png;base64,\u2026 URL (up to 4 million pixels)."
+  };
+  const decodePngBytes = (bytes, what) => {
+    if (!_chunkW5M3J7PVcjs.isPng.call(void 0, bytes)) fail(`${what} is not a PNG.`);
+    try {
+      return _chunkW5M3J7PVcjs.decodePng.call(void 0, bytes, { maxPixels: _chunkMNHP3AQTcjs.VECTOR_TRACE_MAX_PIXELS });
+    } catch (e) {
+      return fail(`The PNG could not be read: ${e.message}`);
+    }
+  };
+  const fromResolved = (ref, resolved) => {
+    if (!resolved || typeof resolved !== "object") return fail(`There is no image "${ref}".`);
+    if ("image" in resolved && resolved.image) return resolved.image;
+    if ("png" in resolved && typeof resolved.png === "string") {
+      const parsed = _chunkW5M3J7PVcjs.parseDataUrl.call(void 0, resolved.png);
+      if (!parsed) fail(`The image "${ref}" was loaded as something other than a PNG data URL.`);
+      return decodePngBytes(parsed.bytes, `The image "${ref}"`);
+    }
+    if ("png" in resolved && resolved.png instanceof Uint8Array) return decodePngBytes(resolved.png, `The image "${ref}"`);
+    return fail(`The image "${ref}" was loaded as nothing usable (expected { image } or { png }).`);
+  };
+  const withImage = (image, use) => {
+    if (typeof image !== "string" || !image.trim()) fail("image is empty.");
+    if (/^data:/i.test(image)) {
+      const parsed = _chunkW5M3J7PVcjs.parseDataUrl.call(void 0, image);
+      if (!parsed || !_chunkW5M3J7PVcjs.isPng.call(void 0, parsed.bytes)) fail(resolveImage ? "image must be a PNG data URL (data:image/png;base64,\u2026) or a reference to an image." : "image must be a PNG data URL (data:image/png;base64,\u2026).");
+      return use(decodePngBytes(parsed.bytes, "image"));
+    }
+    if (!resolveImage) return fail("image must be a PNG data URL (data:image/png;base64,\u2026).");
+    const ref = image.trim();
+    const load = async () => {
+      let resolved;
+      try {
+        resolved = await resolveImage(ref, { maxPixels: _chunkMNHP3AQTcjs.VECTOR_TRACE_MAX_PIXELS });
+      } catch (e) {
+        return fail(`The image "${ref}" could not be loaded: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      return use(fromResolved(ref, resolved));
+    };
+    return load();
+  };
+  const imageResult = (r) => {
+    check2(r);
+    return {
+      id: r.id,
+      paths: r.ids.map((id) => {
+        const n2 = controller.getNode(id);
+        return { id, name: n2.name, fill: n2.fill, subpaths: n2.subpaths.length };
+      })
+    };
+  };
   const traceCommands = () => [
     {
       ...base,
       id: `${prefix}traceImage`,
       label: "Image Trace\u2026",
       keywords: ["trace", "image trace", "live trace", "vectorize", "bitmap to vector", "png to svg", "autotrace", "posterize"],
-      description: "Traces a PNG (base64 data URL) into vector paths and adds them as one group: `threshold` mode makes one even-odd path where the image is dark (or opaque with channel alpha); `color` mode makes a stacked path per colour (median-cut to `colors`, the most common at the bottom). Placed with its top-left at x, y and `width` wide (default one unit per pixel). One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.",
+      description: "Traces " + IMAGE_WHAT + " into vector paths and adds them as one group: `threshold` mode makes one even-odd path where the image is dark (or opaque with channel alpha); `color` mode makes a stacked path per colour (median-cut to `colors`, the most common at the bottom). Placed with its top-left at x, y and `width` wide (default one unit per pixel). One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.",
       params: {
         type: "object",
         properties: {
-          image: { type: "string", description: "The image as a data:image/png;base64,\u2026 URL (up to 4 million pixels)." },
+          image: IMAGE_PARAM,
           mode: { type: "string", enum: ["threshold", "color"], description: "threshold (one colour, default) or color (a path per colour)." },
           channel: { type: "string", enum: ["luminance", "alpha"], description: "Threshold mode: trace dark pixels (luminance, default) or opaque ones (alpha)." },
           threshold: { type: "number", minimum: 0, maximum: 1, description: "Threshold mode: inside where darkness (or alpha) reaches this (default 0.5)." },
@@ -16581,61 +16636,28 @@ function createVectorCommands(controller, options = {}) {
       undoable: true,
       run: (_ctx, params) => {
         const { image, ...options2 } = params;
-        const parsed = _chunkW5M3J7PVcjs.parseDataUrl.call(void 0, image);
-        if (!parsed || !_chunkW5M3J7PVcjs.isPng.call(void 0, parsed.bytes)) fail("image must be a PNG data URL (data:image/png;base64,\u2026).");
-        let decoded2;
-        try {
-          decoded2 = _chunkW5M3J7PVcjs.decodePng.call(void 0, parsed.bytes, { maxPixels: _chunkMNHP3AQTcjs.VECTOR_TRACE_MAX_PIXELS });
-        } catch (e) {
-          return fail(`The PNG could not be read: ${e.message}`);
-        }
-        const r = controller.traceImage(decoded2, options2);
-        check2(r);
-        return {
-          id: r.id,
-          paths: r.ids.map((id) => {
-            const n2 = controller.getNode(id);
-            return { id, name: n2.name, fill: n2.fill, subpaths: n2.subpaths.length };
-          })
-        };
+        return withImage(image, (pixels) => imageResult(controller.traceImage(pixels, options2)));
       }
     }
   ];
   const IMAGE_PLACE = {
-    image: { type: "string", description: "The picture as a data:image/png;base64,\u2026 URL (up to 4 million pixels)." },
+    image: resolveImage ? IMAGE_PARAM : { type: "string", description: "The picture as a data:image/png;base64,\u2026 URL (up to 4 million pixels)." },
     x: { type: "number", description: "Left edge in document units (default 0)." },
     y: { type: "number", description: "Top edge in document units (default 0)." },
     width: { type: "number", exclusiveMinimum: 0, description: "Width in document units (default: the image width in pixels)." },
     name: { type: "string", description: "Group name (default: the style's name)." }
   };
-  const decodeImage = (image) => {
-    const parsed = _chunkW5M3J7PVcjs.parseDataUrl.call(void 0, image);
-    if (!parsed || !_chunkW5M3J7PVcjs.isPng.call(void 0, parsed.bytes)) fail("image must be a PNG data URL (data:image/png;base64,\u2026).");
-    try {
-      return _chunkW5M3J7PVcjs.decodePng.call(void 0, parsed.bytes, { maxPixels: _chunkMNHP3AQTcjs.VECTOR_TRACE_MAX_PIXELS });
-    } catch (e) {
-      return fail(`The PNG could not be read: ${e.message}`);
-    }
-  };
   const stylize = (style, label2, keywords, description, props) => ({
     ...base,
     id: `${prefix}${style}Image`,
     label: label2,
     keywords: ["stylize", "stylise", "bitmap to vector", "artistic", "png to svg", ...keywords],
-    description: `${description} Added as one group placed with its top-left at x, y and width wide; colours of one kind share a compound path. One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.`,
+    description: `${resolveImage ? description.replace("a PNG", IMAGE_WHAT) : description} Added as one group placed with its top-left at x, y and width wide; colours of one kind share a compound path. One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.`,
     params: { type: "object", properties: { ...IMAGE_PLACE, ...props }, required: ["image"], additionalProperties: false },
     undoable: true,
     run: (_ctx, params) => {
       const { image, ...options2 } = params;
-      const r = controller.stylizeImage(decodeImage(image), style, options2);
-      check2(r);
-      return {
-        id: r.id,
-        paths: r.ids.map((id) => {
-          const n2 = controller.getNode(id);
-          return { id, name: n2.name, fill: n2.fill, subpaths: n2.subpaths.length };
-        })
-      };
+      return withImage(image, (pixels) => imageResult(controller.stylizeImage(pixels, style, options2)));
     }
   });
   const CELL = (dflt, what) => ({ type: "number", minimum: 1, description: `${what} in image pixels (default ${dflt}); larger draws fewer, bigger shapes.` });

package/dist/vector/index.js

@@ -16551,17 +16551,72 @@ function createVectorCommands(controller, options = {}) {
       }
     }
   ];
+  const resolveImage = options.resolveImage;
+  const IMAGE_WHAT = resolveImage ? "an image (a PNG data URL, or a reference the editor loads)" : "a PNG (base64 data URL)";
+  const IMAGE_PARAM = {
+    type: "string",
+    description: resolveImage ? `The image: a data:image/png;base64,\u2026 URL, or ${options.imageReferences ?? "an image URL"} (up to ${VECTOR_TRACE_MAX_PIXELS / 1e6} million pixels).` : "The image as a data:image/png;base64,\u2026 URL (up to 4 million pixels)."
+  };
+  const decodePngBytes = (bytes, what) => {
+    if (!isPng(bytes)) fail(`${what} is not a PNG.`);
+    try {
+      return decodePng(bytes, { maxPixels: VECTOR_TRACE_MAX_PIXELS });
+    } catch (e) {
+      return fail(`The PNG could not be read: ${e.message}`);
+    }
+  };
+  const fromResolved = (ref, resolved) => {
+    if (!resolved || typeof resolved !== "object") return fail(`There is no image "${ref}".`);
+    if ("image" in resolved && resolved.image) return resolved.image;
+    if ("png" in resolved && typeof resolved.png === "string") {
+      const parsed = parseDataUrl(resolved.png);
+      if (!parsed) fail(`The image "${ref}" was loaded as something other than a PNG data URL.`);
+      return decodePngBytes(parsed.bytes, `The image "${ref}"`);
+    }
+    if ("png" in resolved && resolved.png instanceof Uint8Array) return decodePngBytes(resolved.png, `The image "${ref}"`);
+    return fail(`The image "${ref}" was loaded as nothing usable (expected { image } or { png }).`);
+  };
+  const withImage = (image, use) => {
+    if (typeof image !== "string" || !image.trim()) fail("image is empty.");
+    if (/^data:/i.test(image)) {
+      const parsed = parseDataUrl(image);
+      if (!parsed || !isPng(parsed.bytes)) fail(resolveImage ? "image must be a PNG data URL (data:image/png;base64,\u2026) or a reference to an image." : "image must be a PNG data URL (data:image/png;base64,\u2026).");
+      return use(decodePngBytes(parsed.bytes, "image"));
+    }
+    if (!resolveImage) return fail("image must be a PNG data URL (data:image/png;base64,\u2026).");
+    const ref = image.trim();
+    const load = async () => {
+      let resolved;
+      try {
+        resolved = await resolveImage(ref, { maxPixels: VECTOR_TRACE_MAX_PIXELS });
+      } catch (e) {
+        return fail(`The image "${ref}" could not be loaded: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      return use(fromResolved(ref, resolved));
+    };
+    return load();
+  };
+  const imageResult = (r) => {
+    check2(r);
+    return {
+      id: r.id,
+      paths: r.ids.map((id) => {
+        const n2 = controller.getNode(id);
+        return { id, name: n2.name, fill: n2.fill, subpaths: n2.subpaths.length };
+      })
+    };
+  };
   const traceCommands = () => [
     {
       ...base,
       id: `${prefix}traceImage`,
       label: "Image Trace\u2026",
       keywords: ["trace", "image trace", "live trace", "vectorize", "bitmap to vector", "png to svg", "autotrace", "posterize"],
-      description: "Traces a PNG (base64 data URL) into vector paths and adds them as one group: `threshold` mode makes one even-odd path where the image is dark (or opaque with channel alpha); `color` mode makes a stacked path per colour (median-cut to `colors`, the most common at the bottom). Placed with its top-left at x, y and `width` wide (default one unit per pixel). One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.",
+      description: "Traces " + IMAGE_WHAT + " into vector paths and adds them as one group: `threshold` mode makes one even-odd path where the image is dark (or opaque with channel alpha); `color` mode makes a stacked path per colour (median-cut to `colors`, the most common at the bottom). Placed with its top-left at x, y and `width` wide (default one unit per pixel). One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.",
       params: {
         type: "object",
         properties: {
-          image: { type: "string", description: "The image as a data:image/png;base64,\u2026 URL (up to 4 million pixels)." },
+          image: IMAGE_PARAM,
           mode: { type: "string", enum: ["threshold", "color"], description: "threshold (one colour, default) or color (a path per colour)." },
           channel: { type: "string", enum: ["luminance", "alpha"], description: "Threshold mode: trace dark pixels (luminance, default) or opaque ones (alpha)." },
           threshold: { type: "number", minimum: 0, maximum: 1, description: "Threshold mode: inside where darkness (or alpha) reaches this (default 0.5)." },
@@ -16581,61 +16636,28 @@ function createVectorCommands(controller, options = {}) {
       undoable: true,
       run: (_ctx, params) => {
         const { image, ...options2 } = params;
-        const parsed = parseDataUrl(image);
-        if (!parsed || !isPng(parsed.bytes)) fail("image must be a PNG data URL (data:image/png;base64,\u2026).");
-        let decoded2;
-        try {
-          decoded2 = decodePng(parsed.bytes, { maxPixels: VECTOR_TRACE_MAX_PIXELS });
-        } catch (e) {
-          return fail(`The PNG could not be read: ${e.message}`);
-        }
-        const r = controller.traceImage(decoded2, options2);
-        check2(r);
-        return {
-          id: r.id,
-          paths: r.ids.map((id) => {
-            const n2 = controller.getNode(id);
-            return { id, name: n2.name, fill: n2.fill, subpaths: n2.subpaths.length };
-          })
-        };
+        return withImage(image, (pixels) => imageResult(controller.traceImage(pixels, options2)));
       }
     }
   ];
   const IMAGE_PLACE = {
-    image: { type: "string", description: "The picture as a data:image/png;base64,\u2026 URL (up to 4 million pixels)." },
+    image: resolveImage ? IMAGE_PARAM : { type: "string", description: "The picture as a data:image/png;base64,\u2026 URL (up to 4 million pixels)." },
     x: { type: "number", description: "Left edge in document units (default 0)." },
     y: { type: "number", description: "Top edge in document units (default 0)." },
     width: { type: "number", exclusiveMinimum: 0, description: "Width in document units (default: the image width in pixels)." },
     name: { type: "string", description: "Group name (default: the style's name)." }
   };
-  const decodeImage = (image) => {
-    const parsed = parseDataUrl(image);
-    if (!parsed || !isPng(parsed.bytes)) fail("image must be a PNG data URL (data:image/png;base64,\u2026).");
-    try {
-      return decodePng(parsed.bytes, { maxPixels: VECTOR_TRACE_MAX_PIXELS });
-    } catch (e) {
-      return fail(`The PNG could not be read: ${e.message}`);
-    }
-  };
   const stylize = (style, label2, keywords, description, props) => ({
     ...base,
     id: `${prefix}${style}Image`,
     label: label2,
     keywords: ["stylize", "stylise", "bitmap to vector", "artistic", "png to svg", ...keywords],
-    description: `${description} Added as one group placed with its top-left at x, y and width wide; colours of one kind share a compound path. One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.`,
+    description: `${resolveImage ? description.replace("a PNG", IMAGE_WHAT) : description} Added as one group placed with its top-left at x, y and width wide; colours of one kind share a compound path. One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.`,
     params: { type: "object", properties: { ...IMAGE_PLACE, ...props }, required: ["image"], additionalProperties: false },
     undoable: true,
     run: (_ctx, params) => {
       const { image, ...options2 } = params;
-      const r = controller.stylizeImage(decodeImage(image), style, options2);
-      check2(r);
-      return {
-        id: r.id,
-        paths: r.ids.map((id) => {
-          const n2 = controller.getNode(id);
-          return { id, name: n2.name, fill: n2.fill, subpaths: n2.subpaths.length };
-        })
-      };
+      return withImage(image, (pixels) => imageResult(controller.stylizeImage(pixels, style, options2)));
     }
   });
   const CELL = (dflt, what) => ({ type: "number", minimum: 1, description: `${what} in image pixels (default ${dflt}); larger draws fewer, bigger shapes.` });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.279.1",
+  "version": "0.281.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -494,7 +494,7 @@
   ],
   "sideEffects": false,
   "devDependencies": {
-    "@anthropic-ai/sdk": "1.1.0",
+    "@anthropic-ai/sdk": "1.6.0",
     "@dagrejs/dagre": "^1.1.8",
     "@tiptap/core": "^2.27.3",
     "@tiptap/extension-character-count": "^2.27.3",
@@ -521,17 +521,17 @@
     "@tiptap/suggestion": "^2.27.3",
     "@types/dagre": "^0.7.54",
     "@types/markdown-it": "^14.2.0",
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "assemblyscript": "0.28.20",
     "fast-check": "^4.10.2",
     "markdown-it": "^15.0.3",
     "markdown-it-task-lists": "^2.1.1",
-    "mermaid": "12.2.0",
+    "mermaid": "12.3.0",
     "prosemirror-markdown": "^1.13.9",
     "tiptap-markdown": "^0.8.10",
     "tsup": "^9.0.0",
     "typescript": "^5.7.3",
-    "vitest": "^5.0.5",
+    "vitest": "^5.1.0",
     "@pixerate/markdown-conformance": "0.2.0"
   },
   "peerDependencies": {

package/skills/pixerate-canvas/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: pixerate-canvas
-description: How to build and edit a Pixerate design canvas or node graph through its agent tools - drawing freehand pen, highlighter and dry-brush strokes (canvas.drawFreehand), annotating with hand-drawn circles, underlines, arrows, brackets, strikes, crosses and ticks (canvas.circle, canvas.arrow), 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.
+description: How to build and edit a Pixerate design canvas or node graph through its agent tools - drawing freehand pen, highlighter and dry-brush strokes (canvas.drawFreehand), annotating with hand-drawn circles, underlines, arrows, brackets, strikes, crosses and ticks (canvas.circle, canvas.arrow), 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, keyframe animation with easing and CSS export, animated edges (dots, dashes, beams: set_edge_animation). Use when working on a canvas, whiteboard, flow chart, node graph, frame, design system, component library, button variants, layout, alignment, z-order, a canvas animation or animated connections 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
+`{ id, source, target, label?, data? }`, with `edge.data.animation` holding an edge's animation
+(dots, dash, beam or pulse; not the keyframe tracks of a node's `data.animation`). 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
@@ -161,6 +162,20 @@ undo step and is not saved with the document. The host decides what the children
 | `explode_node` | Explode `node` (an id from `list_explodable_nodes`). Unless `multiple`, the node exploded before collapses (it comes back in `collapsed`). Exploding an exploded node changes nothing (`changed: false`). Returns the ids now `exploded`. Then use `get_editor_state` or `capture_view` to read or see the children. |
 | `collapse_node` | Collapse an exploded `node`. Returns the ids still `exploded` and those still `collapsing` (their children leave when the collapse animation ends). Fails when the node is not exploded. |
 
+### Animate edges
+
+Hosts that draw edges with `<AnimatedEdge>` (or `<EdgeAnimation>` in their own edge) add these.
+An edge's animation is data (`edge.data.animation`): it saves, copies and undoes with the edge.
+Use motion to say something: dots for data or messages flowing, dashes for "live" or "pending",
+a beam for a request or trigger, a pulse for the active or highlighted path. Animate the few
+edges that matter, not the whole graph.
+
+| Tool | Use it to |
+| --- | --- |
+| `list_edge_animations` | List the edges (`id`, `source`, `target`, `label`, `animation` or null), the animation `kinds` with their `defaults`, and the `readOnly` reason if edges cannot change. Call it first: it is the source of edge ids. |
+| `set_edge_animation` | Animate `edges` (ids from `list_edge_animations`) with one `animation`: `kind` (dots, dash, beam, pulse) and optional `speed` (canvas units per second), `duration` (ms per cycle), `direction` (forward = source to target, reverse, alternate), `color`, `size`, `count`, `length`, `gap`, `glow`, `trackOpacity`, `paused`. Replaces what those edges had; all of them change in one undo step. Returns the ids, the `animation` stored and `resolved`, with every default filled in. Then `capture_view` to see it. |
+| `clear_edge_animation` | Stop the animation on `edges`, leaving the plain edge. One undo step. Returns the ids `cleared` and those `unchanged` (they had none). |
+
 ### Proposals (suggest, don't edit)
 
 Hosts that let agents suggest additions add these. A proposal is new nodes and edges shown as ghosts
@@ -354,6 +369,14 @@ effects provider (for example Flair); without one the read tools say so and the
 
 ## Pitfalls
 
+- **Direction follows the edge, not the screen.** `forward` runs from the edge's `source` to its
+  `target`; read them from `list_edge_animations` before choosing, and use `reverse` rather than
+  re-connecting the edge to flip the flow.
+- **Keep speeds comparable.** `speed` is in canvas units per second, so edges of different lengths
+  move at the same pace; `duration` makes a long edge move faster than a short one. Use the same
+  speed for edges that carry the same kind of flow. Users who ask for reduced motion see the first
+  frame, held still, so motion must not be the only sign of state: pair it with a colour or label.
+
 - **Proposals are not on the canvas.** Their ids are not in `get_editor_state` until accepted, and
   `canvas_connect` or `canvas_update_node` on them fails. Put the whole idea in one proposal (an
   edge between two proposed nodes goes in its `edges`), or wait for the user to accept it.

package/skills/pixerate-vector/SKILL.md

@@ -131,7 +131,7 @@ the pitfalls, and uses the commands below.
 
 | Command | Use it to |
 | --- | --- |
-| `vector.traceImage` | Turn a PNG (data URL) into vector paths in one group: `threshold` mode for one-colour art (logos, scans, silhouettes; `channel: "alpha"` for cut-outs), `color` mode for a stacked path per colour (`colors` 2–32). Raise `tolerance` for fewer anchors, `cornerRoundness` 0 for sharp polygons. Place it with `x`, `y`, `width`. Returns `{ id, paths }`; check `subpaths` counts and simplify or delete specks after. |
+| `vector.traceImage` | Turn a PNG (data URL) into vector paths in one group, or an image the host loads by reference (its `image` description says which: a canvas image node's id, a URL); pass the reference instead of writing the image out: `threshold` mode for one-colour art (logos, scans, silhouettes; `channel: "alpha"` for cut-outs), `color` mode for a stacked path per colour (`colors` 2–32). Raise `tolerance` for fewer anchors, `cornerRoundness` 0 for sharp polygons. Place it with `x`, `y`, `width`. Returns `{ id, paths }`; check `subpaths` counts and simplify or delete specks after. |
 | `vector.mosaicImage` | Stylise a PNG as mosaic tiles (`cell` px, `shape` square / circle, `gap`, `colors`): pixel art, tiled murals. Returns `{ id, paths }`, one compound path per colour. |
 | `vector.halftoneImage` | Stylise a PNG as halftone dots on a turned screen (`cell`, `angle`, ink `color` or null for the picture's colours): comic and pop-art looks, print effects. |
 | `vector.lowPolyImage` | Stylise a PNG as low-poly triangles (`cell`, `jitter`, `seed`, `colors`): geometric portraits and backdrops. |