@pixerate/editor 0.280.0 → 0.282.0

package/dist/brushes/types.d.ts

@@ -16,7 +16,7 @@ import type { MixingModel } from '../paint/exchange.js';
 import type { BlendMode } from '../raster/blend.js';
 import type { BrushRotation, ImpastoTool, LivePatternKind, PaintBrush, WetMediumKind } from '../paint-editor/brushes.js';
 import type { PaintEffectPaint } from '../paint-editor/effect-paint.js';
-import type { DotRotation, DotTextureOrder, ParticleKind, ParticleRender, RibbonPairs } from '../paint-editor/mark-settings.js';
+import type { DotRotation, DotTextureOrder, InvertMode, ParticleKind, ParticleRender, RibbonPairs } from '../paint-editor/mark-settings.js';
 import type { StickerRef } from '../stickers/types.js';
 /** `mark`: lays a material; `tool`: works on paint already down (erases, blends, smudges, wets…). */
 export type BrushKind = 'mark' | 'tool';
@@ -35,7 +35,7 @@ export declare const BRUSH_TOOLS: readonly BrushTool[];
 export type BrushTipShape = 'round' | 'flat' | 'chisel' | 'bristle' | 'stamp';
 export declare const BRUSH_TIP_SHAPES: readonly BrushTipShape[];
 /** How the tip is laid along the path. */
-export type BrushMarksKind = 'continuous' | 'scatter' | 'particles' | 'objects';
+export type BrushMarksKind = 'continuous' | 'scatter' | 'particles' | 'objects' | 'antimatter';
 export declare const BRUSH_MARKS_KINDS: readonly BrushMarksKind[];
 /** What the material does on the surface: stays where it lands (`dry`), flows and dries (`wet`) or stands up in relief (`thick`). */
 export type BrushSurface = 'dry' | 'wet' | 'thick';
@@ -178,7 +178,33 @@ export interface BrushObjectMarks {
     /** Random colour change, hue and lightness (default 0.2). */
     colourJitter?: number;
 }
-export type BrushMarks = BrushContinuousMarks | BrushScatterMarks | BrushParticleMarks | BrushObjectMarks;
+/** Animated blasts that invert, scorch and destroy paint across every visible layer where the tip touches paint. */
+export interface BrushAntimatterMarks {
+    kind: 'antimatter';
+    /** Blast size, in tip radii, 1..6 (default 2.5). */
+    blastRadius?: number;
+    /** Stroke travel between blasts, in tip diameters, 0.5..8 (default 2). */
+    blastSpacing?: number;
+    /** Paint needed under the tip to fire, 0..1 (default 0.1). */
+    threshold?: number;
+    /** Strength of the colour inversion in the blast core, 0..1 (default 1). */
+    invert?: number;
+    /** Colour inversion mode: `rgb` (default) or `oklab` (flips lightness and hue so mid-grey changes too). */
+    invertMode?: InvertMode;
+    /** Strength of the soot ring, 0..1 (default 0.6). */
+    scorch?: number;
+    /** Paint destroyed at the centre — alpha removed, 0..1 (default 0.25). */
+    annihilate?: number;
+    /** How many sparks fly out from each blast, 0..1 (default 0.5). */
+    sparks?: number;
+    /** How far sparks fly, in tip diameters, 0.5..8 (default 3). */
+    sparkReach?: number;
+    /** Depth of the dent on layers with relief, 0..1 (default 0.5). */
+    crater?: number;
+    /** Seconds a blast plays on screen, 0..2 (default 0.7; 0 shows the result at once). */
+    duration?: number;
+}
+export type BrushMarks = BrushContinuousMarks | BrushScatterMarks | BrushParticleMarks | BrushObjectMarks | BrushAntimatterMarks;
 /** Pen feel. Every amount is 0 (off) .. 1 unless noted. */
 export interface BrushDynamics {
     /** Pressure scales the size (default true). */

package/dist/{brushstrokeRender-EIK3625T.js → brushstrokeRender-4MA5CBW3.js}

@@ -1,9 +1,9 @@
 import {
   brushPreviewColours
-} from "./chunk-ROURHJYT.js";
+} from "./chunk-NEDS6DSC.js";
 import {
   pathDataToPolyline
-} from "./chunk-LZE2QZCT.js";
+} from "./chunk-IHMMHZGP.js";
 import {
   BRUSH_PRESETS,
   BUILTIN_BRUSHES,
@@ -14,7 +14,7 @@ import {
   normalizeBrushSpec,
   resolveBrush,
   resolveCategory
-} from "./chunk-PPDUCZZV.js";
+} from "./chunk-YRGTQLDN.js";
 import "./chunk-JL6YH5WD.js";
 import {
   formatNumber,

package/dist/{brushstrokeRender-7HOMKZNO.cjs → brushstrokeRender-JVKVKWDA.cjs}

@@ -1,9 +1,9 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkH3EME3S5cjs = require('./chunk-H3EME3S5.cjs');
+var _chunkMRIAR5DYcjs = require('./chunk-MRIAR5DY.cjs');
 
 
-var _chunkWFSYZO5Zcjs = require('./chunk-WFSYZO5Z.cjs');
+var _chunkDFZ4I7EZcjs = require('./chunk-DFZ4I7EZ.cjs');
 
 
 
@@ -14,7 +14,7 @@ var _chunkWFSYZO5Zcjs = require('./chunk-WFSYZO5Z.cjs');
 
 
 
-var _chunkHRUK5TFWcjs = require('./chunk-HRUK5TFW.cjs');
+var _chunkIUKPQCYQcjs = require('./chunk-IUKPQCYQ.cjs');
 require('./chunk-RDFHWAHL.cjs');
 
 
@@ -48,17 +48,17 @@ require('./chunk-5UEFBM2M.cjs');
 require('./chunk-IPJ3TEYR.cjs');
 
 // src/canvas/brushstrokeRender.ts
-var PRESETS = _chunkHRUK5TFWcjs.listPresets.call(void 0, _chunkHRUK5TFWcjs.CANVAS_PROFILE).map((spec) => _chunkHRUK5TFWcjs.BUILTIN_BRUSHES.find((b) => b.id === spec.id));
+var PRESETS = _chunkIUKPQCYQcjs.listPresets.call(void 0, _chunkIUKPQCYQcjs.CANVAS_PROFILE).map((spec) => _chunkIUKPQCYQcjs.BUILTIN_BRUSHES.find((b) => b.id === spec.id));
 var presetIds = () => PRESETS.map((b) => b.id).join(", ");
-var refusal = (brush) => _chunkHRUK5TFWcjs.checkBrush.call(void 0, brush, _chunkHRUK5TFWcjs.CANVAS_PROFILE).issues.filter((i) => i.severity === "error").map((i) => `${i.reason} ${i.fix}`).join(" ");
+var refusal = (brush) => _chunkIUKPQCYQcjs.checkBrush.call(void 0, brush, _chunkIUKPQCYQcjs.CANVAS_PROFILE).issues.filter((i) => i.severity === "error").map((i) => `${i.reason} ${i.fix}`).join(" ");
 function readCanvasBrushSpec(spec) {
   let brush;
   try {
-    brush = _chunkHRUK5TFWcjs.normalizeBrushSpec.call(void 0, spec);
+    brush = _chunkIUKPQCYQcjs.normalizeBrushSpec.call(void 0, spec);
   } catch (e) {
     throw new Error(`Not a brush: ${e.message}`);
   }
-  if (!_chunkHRUK5TFWcjs.checkBrush.call(void 0, brush, _chunkHRUK5TFWcjs.CANVAS_PROFILE).ok) throw new Error(`Brush '${brush.id}' (${brush.name}) can't brush a canvas stroke: ${refusal(brush)}`);
+  if (!_chunkIUKPQCYQcjs.checkBrush.call(void 0, brush, _chunkIUKPQCYQcjs.CANVAS_PROFILE).ok) throw new Error(`Brush '${brush.id}' (${brush.name}) can't brush a canvas stroke: ${refusal(brush)}`);
   return brush;
 }
 function listCanvasBrushes(user = []) {
@@ -66,12 +66,12 @@ function listCanvasBrushes(user = []) {
     const d = _optionalChain([spec, 'access', _2 => _2.colour, 'optionalAccess', _3 => _3.default]);
     return typeof d === "string" || _chunkMLLTWAXHcjs.isDualColor.call(void 0, d) ? { defaultColor: d } : {};
   };
-  const out = PRESETS.map((b) => ({ id: b.id, name: b.name, category: b.category, size: b.tip.size, builtin: true, ...colourOf(_chunkHRUK5TFWcjs.BRUSH_PRESETS.find((p) => p.id === b.id)) }));
+  const out = PRESETS.map((b) => ({ id: b.id, name: b.name, category: b.category, size: b.tip.size, builtin: true, ...colourOf(_chunkIUKPQCYQcjs.BRUSH_PRESETS.find((p) => p.id === b.id)) }));
   for (const raw of user) {
     try {
       const brush = readCanvasBrushSpec(raw);
       if (out.some((b) => b.id === brush.id)) continue;
-      out.push({ id: brush.id, name: brush.name, category: _chunkHRUK5TFWcjs.resolveCategory.call(void 0, brush), size: _chunkHRUK5TFWcjs.resolveBrush.call(void 0, brush).tip.size, builtin: false, spec: brush, ...colourOf(brush) });
+      out.push({ id: brush.id, name: brush.name, category: _chunkIUKPQCYQcjs.resolveCategory.call(void 0, brush), size: _chunkIUKPQCYQcjs.resolveBrush.call(void 0, brush).tip.size, builtin: false, spec: brush, ...colourOf(brush) });
     } catch (e2) {
     }
   }
@@ -82,15 +82,15 @@ function resolveCanvasBrush(brush, width, spec) {
   const sized = (b) => given === void 0 ? b : { ...b, tip: { ...b.tip, size: given } };
   if (typeof brush === "string") {
     if (spec !== void 0 && spec !== null) {
-      const saved = _chunkHRUK5TFWcjs.resolveBrush.call(void 0, readCanvasBrushSpec(spec));
+      const saved = _chunkIUKPQCYQcjs.resolveBrush.call(void 0, readCanvasBrushSpec(spec));
       if (!_chunkNPPMKMCUcjs.isBrushstrokeBrush.call(void 0, saved)) throw new Error(`Brush '${saved.id}' (${saved.name}) can't brush a canvas stroke: it is not a dry dab brush.`);
       return sized(saved);
     }
     const preset = PRESETS.find((b) => b.id === brush);
     if (preset) return sized(preset);
-    const other = _chunkHRUK5TFWcjs.BRUSH_PRESETS.find((b) => b.id === brush);
+    const other = _chunkIUKPQCYQcjs.BRUSH_PRESETS.find((b) => b.id === brush);
     if (other) throw new Error(`Brush '${brush}' (${other.name}) can't brush a canvas stroke: ${refusal(other)} Use one of: ${presetIds()}, or a saved brush the canvas can paint.`);
-    throw new Error(`Unknown brush '${brush}'. ${_chunkHRUK5TFWcjs.closest.call(void 0, brush, PRESETS.map((b) => b.id))}Use one of the dry presets (${presetIds()}), a saved brush from the brush library, or tip settings ({ hardness, spacing, flow, \u2026 }).`);
+    throw new Error(`Unknown brush '${brush}'. ${_chunkIUKPQCYQcjs.closest.call(void 0, brush, PRESETS.map((b) => b.id))}Use one of the dry presets (${presetIds()}), a saved brush from the brush library, or tip settings ({ hardness, spacing, flow, \u2026 }).`);
   }
   if (!brush || typeof brush !== "object" || Array.isArray(brush)) {
     throw new Error("A brush is a preset or saved brush id (see listCanvasBrushes / canvas.listBrushes) or an object of tip settings.");
@@ -126,7 +126,7 @@ function renderShapeBrushstrokeNow(shape, scale, place = {}) {
   const textured = typeof seed === "number" && Number.isFinite(seed);
   const size = _nullishCoalesce(shape.brush.size, () => ( (textured ? void 0 : _nullishCoalesce(shape.strokeWidth, () => ( 3)))));
   const brush = resolveCanvasBrush(shape.brush.brush, size, shape.brush.spec);
-  const points = _chunkWFSYZO5Zcjs.pathDataToPolyline.call(void 0, shape.d);
+  const points = _chunkDFZ4I7EZcjs.pathDataToPolyline.call(void 0, shape.d);
   if (!points.length) return null;
   const { pressure, tiltX, tiltY } = shape.brush;
   const input = {
@@ -164,8 +164,8 @@ function brushedShapeSvgNow(shape, size, scale, place = {}) {
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${f(size.width)}" height="${f(size.height)}" viewBox="0 0 ${f(size.width)} ${f(size.height)}">${content}</svg>`;
 }
 function swatchColour(brush, background, spec) {
-  const facets = typeof brush !== "string" ? null : spec ? readCanvasBrushSpec(spec) : _chunkHRUK5TFWcjs.BRUSH_PRESETS.find((b) => b.id === brush);
-  return background && facets ? _chunkH3EME3S5cjs.brushPreviewColours.call(void 0, facets, { paper: background, profile: _chunkHRUK5TFWcjs.CANVAS_PROFILE, keepPaper: true }).color : "#1f2937";
+  const facets = typeof brush !== "string" ? null : spec ? readCanvasBrushSpec(spec) : _chunkIUKPQCYQcjs.BRUSH_PRESETS.find((b) => b.id === brush);
+  return background && facets ? _chunkMRIAR5DYcjs.brushPreviewColours.call(void 0, facets, { paper: background, profile: _chunkIUKPQCYQcjs.CANVAS_PROFILE, keepPaper: true }).color : "#1f2937";
 }
 function brushSwatchNow(brush, options, spec) {
   const w = options.width && options.width > 8 ? options.width : 96;

package/dist/canvas/edge-animation-tools.d.cts

@@ -0,0 +1,115 @@
+/**
+ * Agent tools for animated edges: `list_edge_animations`, `set_edge_animation` and
+ * `clear_edge_animation`. They read and write `edge.data.animation` through the host's edges, and
+ * each write is one undo step when a history is given.
+ */
+import type { Command } from '../history/types.cjs';
+import type { AgentToolProvider } from '../tools/registry.cjs';
+/** The edge fields the tools read: React Flow and Svelte Flow edges fit as they are. */
+export interface CanvasEdgeAnimationToolEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: unknown;
+    data?: Record<string, any>;
+}
+export interface CanvasEdgeAnimationToolTarget<TEdge extends CanvasEdgeAnimationToolEdge = CanvasEdgeAnimationToolEdge> {
+    /** The edges on the canvas now. */
+    getEdges: () => readonly TEdge[];
+    /**
+     * Replaces the edges with the result of `update(current)`. React's `setEdges` fits as is; in
+     * Svelte, `(update) => (edges = update(edges))`.
+     */
+    setEdges: (update: (current: TEdge[]) => TEdge[]) => void;
+    /** The canvas's undo history: each write is one step there. Without it, writes are not undoable. */
+    history?: {
+        execute(command: Command): void;
+    };
+}
+export interface CanvasEdgeAnimationToolProviderOptions {
+    /** Provider id (unique per registry). Default `canvas-edge-animation`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Edges cannot be changed: the write tools are hidden. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Lets the tool list follow changes. */
+    subscribe?: (notify: () => void) => () => void;
+}
+/** JSON Schema of {@link CanvasEdgeAnimation}, for tools and commands. */
+export declare const CANVAS_EDGE_ANIMATION_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: import("./edgeAnimation.cjs").CanvasEdgeAnimationKind[];
+            readonly description: "What moves: dots (travelling dots), dash (marching dashes), beam (a glowing streak that shoots along), pulse (the edge glows and fades).";
+        };
+        readonly speed: {
+            readonly type: "number";
+            readonly minimum: 1;
+            readonly maximum: 10000;
+            readonly description: "Travel speed in canvas units per second (dots, dash, beam). Defaults: dots 80, dash 40, beam 200.";
+        };
+        readonly duration: {
+            readonly type: "number";
+            readonly minimum: 100;
+            readonly maximum: 600000;
+            readonly description: "One cycle in ms; overrides speed. The pulse timing (default 1600).";
+        };
+        readonly direction: {
+            readonly type: "string";
+            readonly enum: readonly ["forward", "reverse", "alternate"];
+            readonly description: "forward = source to target (default), reverse = target to source, alternate = back and forth.";
+        };
+        readonly color: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "CSS colour, e.g. \"#38bdf8\". Default: the edge stroke colour.";
+        };
+        readonly size: {
+            readonly type: "number";
+            readonly minimum: 0.5;
+            readonly maximum: 100;
+            readonly description: "Dot radius, or stroke width of dashes, beams and the pulse, in canvas units. Defaults: dots 3, dash 2, beam 3, pulse 4.";
+        };
+        readonly count: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 50;
+            readonly description: "How many dots or beams are on the edge at once. Defaults: dots 3, beam 1.";
+        };
+        readonly length: {
+            readonly type: "number";
+            readonly minimum: 1;
+            readonly maximum: 10000;
+            readonly description: "Dash or beam length in canvas units. Defaults: dash 8, beam 40.";
+        };
+        readonly gap: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 10000;
+            readonly description: "Gap between dashes in canvas units (dash). Default 6.";
+        };
+        readonly glow: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 50;
+            readonly description: "Glow (blur) radius in canvas units; 0 is none. Defaults: beam 4, pulse 3, others 0.";
+        };
+        readonly trackOpacity: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: "Opacity of the edge's own line under the animation, 0-1. Defaults: dash 0 (the dashes are the line), beam 0.35, others 1.";
+        };
+        readonly paused: {
+            readonly type: "boolean";
+            readonly description: "Hold the animation still at its first frame. Default false.";
+        };
+    };
+    readonly required: readonly ["kind"];
+    readonly additionalProperties: false;
+};
+/** The edge animation tools for a canvas (see the module comment). */
+export declare function createCanvasEdgeAnimationToolProvider<TEdge extends CanvasEdgeAnimationToolEdge = CanvasEdgeAnimationToolEdge>(target: CanvasEdgeAnimationToolTarget<TEdge>, options?: CanvasEdgeAnimationToolProviderOptions): AgentToolProvider;

package/dist/canvas/edge-animation-tools.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Agent tools for animated edges: `list_edge_animations`, `set_edge_animation` and
+ * `clear_edge_animation`. They read and write `edge.data.animation` through the host's edges, and
+ * each write is one undo step when a history is given.
+ */
+import type { Command } from '../history/types.js';
+import type { AgentToolProvider } from '../tools/registry.js';
+/** The edge fields the tools read: React Flow and Svelte Flow edges fit as they are. */
+export interface CanvasEdgeAnimationToolEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: unknown;
+    data?: Record<string, any>;
+}
+export interface CanvasEdgeAnimationToolTarget<TEdge extends CanvasEdgeAnimationToolEdge = CanvasEdgeAnimationToolEdge> {
+    /** The edges on the canvas now. */
+    getEdges: () => readonly TEdge[];
+    /**
+     * Replaces the edges with the result of `update(current)`. React's `setEdges` fits as is; in
+     * Svelte, `(update) => (edges = update(edges))`.
+     */
+    setEdges: (update: (current: TEdge[]) => TEdge[]) => void;
+    /** The canvas's undo history: each write is one step there. Without it, writes are not undoable. */
+    history?: {
+        execute(command: Command): void;
+    };
+}
+export interface CanvasEdgeAnimationToolProviderOptions {
+    /** Provider id (unique per registry). Default `canvas-edge-animation`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Edges cannot be changed: the write tools are hidden. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Lets the tool list follow changes. */
+    subscribe?: (notify: () => void) => () => void;
+}
+/** JSON Schema of {@link CanvasEdgeAnimation}, for tools and commands. */
+export declare const CANVAS_EDGE_ANIMATION_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: import("./edgeAnimation.js").CanvasEdgeAnimationKind[];
+            readonly description: "What moves: dots (travelling dots), dash (marching dashes), beam (a glowing streak that shoots along), pulse (the edge glows and fades).";
+        };
+        readonly speed: {
+            readonly type: "number";
+            readonly minimum: 1;
+            readonly maximum: 10000;
+            readonly description: "Travel speed in canvas units per second (dots, dash, beam). Defaults: dots 80, dash 40, beam 200.";
+        };
+        readonly duration: {
+            readonly type: "number";
+            readonly minimum: 100;
+            readonly maximum: 600000;
+            readonly description: "One cycle in ms; overrides speed. The pulse timing (default 1600).";
+        };
+        readonly direction: {
+            readonly type: "string";
+            readonly enum: readonly ["forward", "reverse", "alternate"];
+            readonly description: "forward = source to target (default), reverse = target to source, alternate = back and forth.";
+        };
+        readonly color: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "CSS colour, e.g. \"#38bdf8\". Default: the edge stroke colour.";
+        };
+        readonly size: {
+            readonly type: "number";
+            readonly minimum: 0.5;
+            readonly maximum: 100;
+            readonly description: "Dot radius, or stroke width of dashes, beams and the pulse, in canvas units. Defaults: dots 3, dash 2, beam 3, pulse 4.";
+        };
+        readonly count: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 50;
+            readonly description: "How many dots or beams are on the edge at once. Defaults: dots 3, beam 1.";
+        };
+        readonly length: {
+            readonly type: "number";
+            readonly minimum: 1;
+            readonly maximum: 10000;
+            readonly description: "Dash or beam length in canvas units. Defaults: dash 8, beam 40.";
+        };
+        readonly gap: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 10000;
+            readonly description: "Gap between dashes in canvas units (dash). Default 6.";
+        };
+        readonly glow: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 50;
+            readonly description: "Glow (blur) radius in canvas units; 0 is none. Defaults: beam 4, pulse 3, others 0.";
+        };
+        readonly trackOpacity: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: "Opacity of the edge's own line under the animation, 0-1. Defaults: dash 0 (the dashes are the line), beam 0.35, others 1.";
+        };
+        readonly paused: {
+            readonly type: "boolean";
+            readonly description: "Hold the animation still at its first frame. Default false.";
+        };
+    };
+    readonly required: readonly ["kind"];
+    readonly additionalProperties: false;
+};
+/** The edge animation tools for a canvas (see the module comment). */
+export declare function createCanvasEdgeAnimationToolProvider<TEdge extends CanvasEdgeAnimationToolEdge = CanvasEdgeAnimationToolEdge>(target: CanvasEdgeAnimationToolTarget<TEdge>, options?: CanvasEdgeAnimationToolProviderOptions): AgentToolProvider;

package/dist/canvas/edgeAnimation.d.cts

@@ -0,0 +1,164 @@
+/**
+ * Animated canvas edges: dots travelling along an edge, marching dashes, beams of light and a
+ * pulsing glow. An edge's animation is data (`edge.data.animation`, a {@link CanvasEdgeAnimation}),
+ * so it saves, undoes and copies with the edge. {@link getCanvasEdgeAnimationRender} turns it into a
+ * framework-neutral list of SVG elements with SMIL timing, which `<AnimatedEdge>` /
+ * `<EdgeAnimation>` (React and Svelte) render; {@link sampleCanvasEdgeAnimation} gives the same
+ * picture at a moment in time without a browser (thumbnails, exports, tests, reduced motion).
+ */
+import type { CanvasConnectionLineType } from './connectors.cjs';
+import { type MeasuredSvgPath, type SvgPathPoint } from './edgePaths.cjs';
+/** What travels along the edge. */
+export type CanvasEdgeAnimationKind = 'dots' | 'dash' | 'beam' | 'pulse';
+/** Which way the animation runs: source → target, target → source, or back and forth. */
+export type CanvasEdgeAnimationDirection = 'forward' | 'reverse' | 'alternate';
+/** An edge's animation, stored at `edge.data.animation`. Every field but `kind` is optional. */
+export interface CanvasEdgeAnimation {
+    kind: CanvasEdgeAnimationKind;
+    /** Travel speed in canvas units per second (`dots`, `dash`, `beam`). Defaults per kind. */
+    speed?: number;
+    /** Length of one cycle in ms; overrides `speed` (and is the only timing for `pulse`). */
+    duration?: number;
+    /** Default `forward` (source → target). */
+    direction?: CanvasEdgeAnimationDirection;
+    /** CSS colour. Default: the edge's stroke. */
+    color?: string;
+    /** Dot radius, or the stroke width of dashes, beams and the pulse, in canvas units. Defaults per kind. */
+    size?: number;
+    /** Number of dots or beams on the edge at once. Defaults per kind. */
+    count?: number;
+    /** Dash or beam length, in canvas units. Defaults per kind. */
+    length?: number;
+    /** Gap between dashes, in canvas units (`dash`). Default 6. */
+    gap?: number;
+    /** Glow radius (a blur behind the moving part), in canvas units. 0 is none. Defaults per kind. */
+    glow?: number;
+    /** Opacity of the edge's own stroke under the animation, 0–1. Default 1. */
+    trackOpacity?: number;
+    /** Held still at its first frame. Default false. */
+    paused?: boolean;
+}
+export interface CanvasEdgeAnimationKindInfo {
+    kind: CanvasEdgeAnimationKind;
+    title: string;
+    description: string;
+    /** The values used for fields an animation leaves out. */
+    defaults: Required<Omit<CanvasEdgeAnimation, 'kind' | 'color' | 'duration' | 'paused'>> & {
+        duration?: number;
+    };
+}
+/** The animation kinds, with what they look like and their defaults. */
+export declare const CANVAS_EDGE_ANIMATION_KINDS: readonly CanvasEdgeAnimationKindInfo[];
+/**
+ * Checks an animation and returns a clean copy (unknown fields dropped). Throws an error that says
+ * which field is wrong and what it accepts.
+ */
+export declare function normalizeCanvasEdgeAnimation(input: unknown): CanvasEdgeAnimation;
+/** The edge's animation, or null when it has none or it is not valid. */
+export declare function getCanvasEdgeAnimation(edge: {
+    data?: Record<string, any>;
+} | null | undefined): CanvasEdgeAnimation | null;
+/** A copy of the edge with its animation set (checked first), or removed when `animation` is null. */
+export declare function setCanvasEdgeAnimation<TEdge extends {
+    data?: Record<string, any>;
+}>(edge: TEdge, animation: CanvasEdgeAnimation | null): TEdge;
+/** The animation with every default filled in, as it will play. */
+export declare function resolveCanvasEdgeAnimation(animation: CanvasEdgeAnimation): Required<Omit<CanvasEdgeAnimation, 'color' | 'duration'>> & Pick<CanvasEdgeAnimation, 'color' | 'duration'>;
+/** SMIL timing for an element: rendered as `<animate>` / `<animateMotion>` children. */
+export interface CanvasEdgeAnimationTiming {
+    /** Seconds per cycle (SMIL `dur`). */
+    dur: number;
+    /** Start offset in seconds; negative starts part-way through (SMIL `begin`). */
+    begin: number;
+}
+/** One SVG element of an animated edge. Coordinates are canvas units. */
+export type CanvasEdgeAnimationElement = {
+    type: 'dot';
+    key: string;
+    r: number;
+    fill: string;
+    filter?: string;
+    /** Where the dot is at the first frame (used when paused or with reduced motion). */
+    at: SvgPathPoint;
+    /** Travel along the path: `keyPoints` / `keyTimes` for `<animateMotion>`. */
+    motion: CanvasEdgeAnimationTiming & {
+        keyPoints: string;
+        keyTimes: string;
+    };
+} | {
+    type: 'stroke';
+    key: string;
+    stroke: string;
+    strokeWidth: number;
+    strokeLinecap: 'round' | 'butt';
+    strokeDasharray?: string;
+    strokeDashoffset?: number;
+    opacity?: number;
+    filter?: string;
+    /** `<animate>`s to add: attribute, values (`;`-separated, SMIL), timing. */
+    animate: Array<CanvasEdgeAnimationTiming & {
+        attributeName: 'stroke-dashoffset' | 'stroke-opacity' | 'stroke-width';
+        values: string;
+    }>;
+};
+export interface CanvasEdgeAnimationRender {
+    kind: CanvasEdgeAnimationKind;
+    /** Path length in canvas units. */
+    length: number;
+    /** Opacity for the edge's own stroke. */
+    trackOpacity: number;
+    /** Whether the elements should move (false when paused, reduced motion or a zero-length path). */
+    moving: boolean;
+    /**
+     * A blur filter to define in `<defs>` when anything glows. Its region is in user space (canvas
+     * units, `filterUnits="userSpaceOnUse"`): a straight edge has a zero-height box, and a filter
+     * sized to the box would hide it.
+     */
+    glowFilter?: {
+        id: string;
+        stdDeviation: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    elements: CanvasEdgeAnimationElement[];
+}
+export interface CanvasEdgeAnimationRenderOptions {
+    /** SVG path data of the edge (`getCanvasEdgePath(...).path` or the path your edge draws). */
+    path: string;
+    /** A unique id for this edge's defs (the edge id). */
+    id: string;
+    /** Colour used when the animation has none (the edge's stroke). Default `currentColor`. */
+    stroke?: string;
+    /** Draw the first frame without movement (honour `prefers-reduced-motion`). Default false. */
+    reducedMotion?: boolean;
+    /** A measured path to reuse, when you already have one for `path`. */
+    measured?: MeasuredSvgPath;
+}
+/**
+ * How to draw an animated edge: SVG elements and SMIL timing, computed from the path. Dots use
+ * `<animateMotion>` along the path, dashes and beams animate `stroke-dashoffset`, the pulse animates
+ * opacity and width. Nothing here needs a DOM; the React and Svelte `<EdgeAnimation>` render it.
+ */
+export declare function getCanvasEdgeAnimationRender(animation: CanvasEdgeAnimation, options: CanvasEdgeAnimationRenderOptions): CanvasEdgeAnimationRender;
+/** The animated part of an edge at one moment. */
+export interface CanvasEdgeAnimationFrame {
+    kind: CanvasEdgeAnimationKind;
+    length: number;
+    /** Dot positions (`dots`). */
+    dots: SvgPathPoint[];
+    /** Visible stretches of the path as [from, to] distances (`dash`, `beam`), clipped to the path. */
+    segments: Array<[number, number]>;
+    /** Stroke opacity and width (`pulse`). */
+    opacity: number;
+    strokeWidth: number;
+}
+/**
+ * Where everything is `timeMs` into the animation: the same picture the SVG shows at that time,
+ * computed without a browser (for thumbnails, exports, canvas renderers and tests). A paused
+ * animation always returns its first frame.
+ */
+export declare function sampleCanvasEdgeAnimation(animation: CanvasEdgeAnimation, path: string | MeasuredSvgPath, timeMs: number): CanvasEdgeAnimationFrame;
+/** Edge path styles `<AnimatedEdge>` can draw (read from `edge.data.pathType`). */
+export type CanvasAnimatedEdgePathType = CanvasConnectionLineType;