@pixerate/editor 0.279.1 → 0.281.0

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;

package/dist/canvas/edgeAnimation.d.ts

@@ -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.js';
+import { type MeasuredSvgPath, type SvgPathPoint } from './edgePaths.js';
+/** 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;

package/dist/canvas/edgePaths.d.cts

@@ -0,0 +1,63 @@
+/**
+ * Edge path geometry for canvas edges, matching xyflow's (`getBezierPath`, `getStraightPath`,
+ * `getSimpleBezierPath`, `getSmoothStepPath`) so the same path is drawn with or without React Flow /
+ * Svelte Flow, plus a small SVG path measurer (`measureSvgPath`) for placing things along a path.
+ * No DOM and no xyflow import.
+ */
+import type { CanvasConnectionLineType } from './connectors.cjs';
+import type { Position } from './types.cjs';
+export interface CanvasEdgePathParams {
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+    /** Side of the source node the edge leaves from. Default `bottom`. */
+    sourcePosition?: Position;
+    /** Side of the target node the edge enters. Default `top`. */
+    targetPosition?: Position;
+    /** Path style, as xyflow's edge `type`. Default `default` (bézier). */
+    type?: CanvasConnectionLineType;
+    /** Bézier curvature (`default`). Default 0.25. */
+    curvature?: number;
+    /** Corner radius for `smoothstep`, in canvas units. Default 5 (`step` is 0). */
+    borderRadius?: number;
+    /** Distance the step paths run straight out of a handle before turning, in canvas units. Default 20. */
+    offset?: number;
+}
+export interface CanvasEdgePath {
+    /** SVG path data. */
+    path: string;
+    /** Where a label sits (xyflow's `labelX` / `labelY`). */
+    labelX: number;
+    labelY: number;
+}
+/**
+ * The SVG path of a canvas edge, the same as xyflow draws for that edge `type` (`default` bézier,
+ * `straight`, `step`, `smoothstep`, `simplebezier`), with the label position.
+ */
+export declare function getCanvasEdgePath(params: CanvasEdgePathParams): CanvasEdgePath;
+/** A point on a path with the direction of travel there (radians, 0 = +x). */
+export interface SvgPathPoint {
+    x: number;
+    y: number;
+    angle: number;
+}
+export interface MeasuredSvgPath {
+    /** Total length in path units. */
+    length: number;
+    /** Bounding box of the flattened path. */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The point `distance` along the path (clamped to [0, length]). */
+    pointAt(distance: number): SvgPathPoint;
+}
+/**
+ * Measures SVG path data (M, L, H, V, C, S, Q, T, Z, absolute or relative; arcs are drawn as
+ * straight lines). Curves are flattened to `segments` pieces each (default 24), which is well under
+ * a canvas unit of error for edge-sized curves.
+ */
+export declare function measureSvgPath(d: string, segments?: number): MeasuredSvgPath;