@pixerate/editor 0.53.0 → 0.55.0

package/dist/animation-editor/index.d.cts

@@ -0,0 +1,1117 @@
+import { b as AnimationEasing } from '../easing-CNGk-W6d.cjs';
+import { b as AnimationLoopMode, c as AnimationPlayer, C as Clock } from '../player-Dg0FT0UI.cjs';
+import { V as VectorDocument, a as VectorNode, b as VectorBounds, c as VectorSvgExportOptions } from '../svg-CLg2zqZA.cjs';
+import { A as AffineMatrix } from '../bezier-BfwIbVTl.cjs';
+import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
+import { A as AgentToolProvider } from '../registry-DIpIaCkH.cjs';
+import { J as JsonSchema } from '../schema-Di0CS6Pe.cjs';
+import '../types-BFkYA4eF.cjs';
+import '../types-DsiXGmjo.cjs';
+
+/**
+ * A vector animation as plain JSON: a piece of vector artwork (the editor's `VectorDocument`,
+ * as the vector editor draws it) and the shots that bring it to life.
+ *
+ * Shots, not timelines: a shot frames the camera, plays its commands and holds. Timing comes
+ * from the content (each command has a sensible default length, and drawing a line takes as
+ * long as the line is long), so there are no keyframes to manage. The same scene plays the
+ * same frames every time: every frame is a pure function of time.
+ */
+interface MotionScene {
+    /** Format version (always 1). */
+    version: 1;
+    /** A short name, e.g. `logo-reveal`. */
+    name: string;
+    description?: string;
+    /** The artwork in its resting state. Commands target its node ids. */
+    artwork: VectorDocument;
+    shots: MotionShot[];
+    /** Playback past the end: stop (`none`, default), `loop` or `ping-pong`. */
+    loop?: AnimationLoopMode;
+    /** Frame rate used to sample motion that a target format cannot express exactly (default 30). */
+    fps?: number;
+    /** Wanted length in seconds `[min, max]`; `check` warns outside it. */
+    target?: [number, number];
+    /** Parameters a Flair effect made from this scene exposes (see `toFlairVectorEffect`). */
+    controls?: MotionControl[];
+    /** Named sets of control values. */
+    presets?: MotionPreset[];
+}
+/** A rectangle of the artwork, in document units. */
+interface MotionRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Where the camera looks: a rectangle, or the id of a node to frame (with `padding` around
+ * its bounds, default 24). The camera eases there over `ms` (default 1000; the first shot cuts).
+ */
+type MotionCamera = (MotionRect | {
+    frame: string;
+    padding?: number;
+}) & {
+    ease?: AnimationEasing;
+    ms?: number;
+};
+/** One beat of the animation. */
+interface MotionShot {
+    /** Stable id (unique in the scene), e.g. `intro`. */
+    id: string;
+    /** What happens in this shot, in a few words (shown on the timeline). */
+    label?: string;
+    /** Omit to keep the current framing. */
+    camera?: MotionCamera;
+    /** Commands, played one after another (unless a command says `with: "previous"`). */
+    run: MotionCommand[];
+    /** Milliseconds to hold after the commands finish (default 600). */
+    hold?: number;
+}
+/** Fields every command takes. */
+interface MotionCommandBase {
+    /** Node ids from the artwork (groups animate as one). */
+    targets: string[];
+    /** Length in ms for each target (each type has a default; `draw` follows the path length). */
+    duration?: number;
+    /** Wait this many ms before starting (default 0). */
+    delay?: number;
+    /** Start each further target this many ms after the one before (default 0). */
+    stagger?: number;
+    /** `after` (default) starts when the commands before it finish; `previous` starts with the command before. */
+    with?: 'after' | 'previous';
+    ease?: AnimationEasing;
+    /** Why this command is here (for people and agents reading the scene). */
+    note?: string;
+}
+type MotionEnterStyle = 'fade' | 'pop' | 'grow' | 'slide' | 'draw';
+type MotionExitStyle = 'fade' | 'shrink' | 'slide' | 'undraw';
+type MotionDirection = 'up' | 'down' | 'left' | 'right';
+/** Brings hidden targets in. Targets entered in a shot are hidden before it. */
+interface MotionEnterCommand extends MotionCommandBase {
+    type: 'enter';
+    /** Default `fade`. `draw` draws the outline on, then fades the fill in. */
+    style?: MotionEnterStyle;
+    /** For `slide`: the direction of travel (default `up`). */
+    direction?: MotionDirection;
+    /** For `slide`: how far in document units (default 40). */
+    distance?: number;
+}
+/** Takes targets out. */
+interface MotionExitCommand extends MotionCommandBase {
+    type: 'exit';
+    /** Default `fade`. */
+    style?: MotionExitStyle;
+    direction?: MotionDirection;
+    distance?: number;
+}
+/** Draws a stroke on (or off) between two fractions of its length. */
+interface MotionDrawCommand extends MotionCommandBase {
+    type: 'draw';
+    /** Fraction drawn at the end (default 1). */
+    to?: number;
+    /** Fraction drawn at the start (default: what is drawn now). */
+    from?: number;
+}
+/** Moves targets by an offset, or to a point (their centre lands there). */
+interface MotionMoveCommand extends MotionCommandBase {
+    type: 'move';
+    by?: {
+        x: number;
+        y: number;
+    };
+    to?: {
+        x: number;
+        y: number;
+    };
+}
+/** Turns targets about their centre, by or to an angle in degrees (clockwise). */
+interface MotionRotateCommand extends MotionCommandBase {
+    type: 'rotate';
+    by?: number;
+    to?: number;
+}
+/** Scales targets about their centre (1 = rest size). */
+interface MotionScaleCommand extends MotionCommandBase {
+    type: 'scale';
+    to: number | {
+        x: number;
+        y: number;
+    };
+}
+/** Changes opacity (0–1). */
+interface MotionFadeCommand extends MotionCommandBase {
+    type: 'fade';
+    to: number;
+}
+/** Changes solid paints and stroke width. Colours mix in OKLab. */
+interface MotionStyleCommand extends MotionCommandBase {
+    type: 'style';
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+}
+/** Morphs each target into the shape of another node (`into`), which usually stays hidden. */
+interface MotionMorphCommand extends MotionCommandBase {
+    type: 'morph';
+    into: string;
+}
+/** Moves targets along a path node, centre on the path. */
+interface MotionFollowCommand extends MotionCommandBase {
+    type: 'follow';
+    /** Id of a path node in the artwork (it can be hidden). */
+    path: string;
+    /** Turn with the path's direction (default false). */
+    rotate?: boolean;
+    /** Fractions of the path's length to travel between (default 0 → 1). */
+    from?: number;
+    to?: number;
+}
+/** Scales up and back, `count` times (draws the eye). */
+interface MotionPulseCommand extends MotionCommandBase {
+    type: 'pulse';
+    /** Extra scale at the peak (default 0.15). */
+    amount?: number;
+    count?: number;
+}
+/** Shakes side to side, settling. */
+interface MotionShakeCommand extends MotionCommandBase {
+    type: 'shake';
+    /** Distance in document units (default 8). */
+    amount?: number;
+    count?: number;
+}
+/** Tweens a numeric parameter of a live path effect on the target (twist angle, wiggle time, zig zag size…). */
+interface MotionEffectCommand extends MotionCommandBase {
+    type: 'effect';
+    /** Id of an effect in the target node's `effects`. */
+    effect: string;
+    /** A numeric parameter of that effect, e.g. `angle`. */
+    param: string;
+    to: number;
+}
+/** Does nothing for `duration` ms. */
+interface MotionWaitCommand {
+    type: 'wait';
+    duration: number;
+    with?: 'after' | 'previous';
+    note?: string;
+}
+type MotionCommand = MotionEnterCommand | MotionExitCommand | MotionDrawCommand | MotionMoveCommand | MotionRotateCommand | MotionScaleCommand | MotionFadeCommand | MotionStyleCommand | MotionMorphCommand | MotionFollowCommand | MotionPulseCommand | MotionShakeCommand | MotionEffectCommand | MotionWaitCommand;
+type MotionCommandType = MotionCommand['type'];
+declare const MOTION_COMMAND_TYPES: readonly MotionCommandType[];
+declare const MOTION_ENTER_STYLES: readonly MotionEnterStyle[];
+declare const MOTION_EXIT_STYLES: readonly MotionExitStyle[];
+declare const MOTION_DIRECTIONS: readonly MotionDirection[];
+/**
+ * A colour parameter of the effect made from the scene: it stands for every use of its
+ * `default` colour in the artwork and the commands, so recolouring it recolours them all.
+ */
+interface MotionControl {
+    /** Identifier, e.g. `accent`. */
+    name: string;
+    type: 'color';
+    /** A `#rrggbb` colour used in the scene. */
+    default: string;
+    label?: string;
+}
+interface MotionPreset {
+    name: string;
+    values: Record<string, string>;
+}
+/** Default lengths (ms) of commands that give none. */
+declare const MOTION_DEFAULT_DURATIONS: Readonly<Record<Exclude<MotionCommandType, 'wait' | 'draw'>, number>>;
+/** Default hold after a shot's commands (ms). */
+declare const MOTION_DEFAULT_HOLD = 600;
+/** Default camera move (ms). */
+declare const MOTION_CAMERA_MS = 1000;
+/** `draw` lasts `length × MOTION_DRAW_MS_PER_UNIT`, clamped to `MOTION_DRAW_RANGE`. */
+declare const MOTION_DRAW_MS_PER_UNIT = 1.5;
+declare const MOTION_DRAW_RANGE: readonly [number, number];
+
+/**
+ * Problems with a scene, as data: every issue has a stable `code`, a severity, the shot and
+ * command it is in and the ids it is about, beside its prose `message`, so an agent (or a UI)
+ * can act on it without parsing sentences.
+ */
+/** `error`: the scene does not play as written. `warning`: it plays, but probably not as meant. `note`: may well be intended. */
+type MotionIssueSeverity = 'error' | 'warning' | 'note';
+/** Every issue code with its severity and what it means. */
+declare const MOTION_ISSUE_CODES: {
+    readonly 'no-shots': {
+        readonly severity: "note";
+        readonly wording: "The scene has no shots yet.";
+    };
+    readonly 'duplicate-shot-id': {
+        readonly severity: "error";
+        readonly wording: "Two shots share an id.";
+    };
+    readonly 'unknown-target': {
+        readonly severity: "error";
+        readonly wording: "A command names a node the artwork does not have.";
+    };
+    readonly 'unknown-path': {
+        readonly severity: "error";
+        readonly wording: "A follow command names a path the artwork does not have.";
+    };
+    readonly 'not-a-path': {
+        readonly severity: "error";
+        readonly wording: "A follow path must be a path node, not a group.";
+    };
+    readonly 'unknown-shape': {
+        readonly severity: "error";
+        readonly wording: "A morph names a shape the artwork does not have.";
+    };
+    readonly 'unknown-effect': {
+        readonly severity: "error";
+        readonly wording: "An effect command names an effect the node does not have.";
+    };
+    readonly 'unknown-effect-param': {
+        readonly severity: "error";
+        readonly wording: "An effect command names a parameter that is not a number of that effect.";
+    };
+    readonly 'unknown-frame': {
+        readonly severity: "error";
+        readonly wording: "A camera frames a node the artwork does not have.";
+    };
+    readonly 'invalid-camera': {
+        readonly severity: "error";
+        readonly wording: "A camera rectangle has no area.";
+    };
+    readonly 'invalid-color': {
+        readonly severity: "error";
+        readonly wording: "A colour cannot be read.";
+    };
+    readonly 'paint-not-color': {
+        readonly severity: "warning";
+        readonly wording: "A style command recolours a gradient or empty paint, which only switches at the end.";
+    };
+    readonly overlap: {
+        readonly severity: "warning";
+        readonly wording: "Two commands change the same property of a node at the same time; the later one wins.";
+    };
+    readonly 'enter-visible': {
+        readonly severity: "warning";
+        readonly wording: "A node enters while it is already showing, so it blinks out first.";
+    };
+    readonly 'exit-hidden': {
+        readonly severity: "warning";
+        readonly wording: "A node exits or animates while it is hidden.";
+    };
+    readonly 'out-of-frame': {
+        readonly severity: "warning";
+        readonly wording: "A node a command animates ends up outside the camera.";
+    };
+    readonly 'too-fast': {
+        readonly severity: "warning";
+        readonly wording: "A change is too quick to follow.";
+    };
+    readonly 'scene-too-long': {
+        readonly severity: "warning";
+        readonly wording: "The scene runs past its target length.";
+    };
+    readonly 'scene-too-short': {
+        readonly severity: "warning";
+        readonly wording: "The scene ends before its target length.";
+    };
+    readonly 'unknown-control-color': {
+        readonly severity: "warning";
+        readonly wording: "A control stands for a colour the scene never uses.";
+    };
+    readonly 'empty-shot': {
+        readonly severity: "note";
+        readonly wording: "A shot neither moves the camera nor runs a command.";
+    };
+    readonly 'camera-aspect': {
+        readonly severity: "note";
+        readonly wording: "A camera rectangle has a different shape from the artwork, so it is letterboxed.";
+    };
+};
+type MotionIssueCode = keyof typeof MOTION_ISSUE_CODES;
+interface MotionIssue {
+    code: MotionIssueCode;
+    severity: MotionIssueSeverity;
+    message: string;
+    /** Id of the shot it is in, when it is in one. */
+    shot?: string;
+    /** Index of the command in that shot's `run`. */
+    command?: number;
+    /** Node ids it is about. */
+    ids?: string[];
+    /** What was measured, what was needed and in what unit (e.g. 80 vs 120 ms). */
+    measured?: number;
+    needed?: number;
+    unit?: 'ms' | 's' | 'units';
+}
+declare function motionIssue(code: MotionIssueCode, message: string, extra?: Omit<MotionIssue, 'code' | 'severity' | 'message'>): MotionIssue;
+/** A stable key for an issue (code and ids, else code and place), to compare two checks. */
+declare function motionIssueKey(issue: MotionIssue): string;
+/** One line: `Shot "intro", command 2: …`. */
+declare function motionIssueLine(issue: MotionIssue): string;
+/** The candidate closest to `word` (case-insensitive), if it is within a third of its length. */
+declare function suggestName(word: string, candidates: Iterable<string>): string | undefined;
+/** `"sunn" (did you mean "sun"?)`, or just `"sunn"`. */
+declare function namedWithSuggestion(word: string, candidates: Iterable<string>): string;
+
+/**
+ * Shape checking: whether a value is a well-formed scene, listing every problem at once.
+ * Meaning (do the ids exist, does the timing work) is `checkMotionScene`'s job.
+ */
+declare class MotionSceneFormatError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** Problems with one command's shape (empty when well formed). `where` prefixes each. */
+declare function commandShapeProblems(command: unknown, where: string): string[];
+/** Problems with one shot's shape. */
+declare function shotShapeProblems(shot: unknown, where: string): string[];
+/** Problems with a scene's shape (empty when well formed). */
+declare function motionSceneShapeProblems(input: unknown): string[];
+/** Reads a scene from JSON (a string or a parsed value). Throws `MotionSceneFormatError` listing every problem. */
+declare function parseMotionScene(input: unknown): MotionScene;
+/** Writes a scene as JSON. */
+declare function motionSceneToJson(scene: MotionScene, space?: number | string): string;
+/** Whether `shot` is a well-formed shot. */
+declare const isMotionShot: (shot: unknown) => shot is MotionShot;
+/** Whether `command` is a well-formed command. */
+declare const isMotionCommand: (command: unknown) => command is MotionCommand;
+
+/**
+ * Compiling a scene: shots and commands become timed segments, one per (node, property)
+ * change. A property's value at a time is that of the latest segment to have started (its
+ * `from` before the first one), so a node that enters later is hidden until then. This is
+ * also how Flair's vector motion combines changes, which keeps the Flair export exact.
+ */
+/**
+ * Properties a segment can change. Offsets (`x`, `y`, `rotation`) are relative to the rest
+ * pose, scales multiply it, and turns and scales are about the node's centre at rest.
+ * `effect:<effectId>:<param>` tweens a live path effect's parameter. `camera` (node `""`) is
+ * the view box `[x, y, width, height]`.
+ */
+type MotionProperty = 'opacity' | 'x' | 'y' | 'rotation' | 'scaleX' | 'scaleY' | 'fill' | 'stroke' | 'strokeWidth' | 'fillOpacity' | 'drawStart' | 'drawEnd' | 'shape' | 'follow' | 'camera' | `effect:${string}:${string}`;
+type MotionValue = number | string | readonly number[];
+/** An oscillation laid over a segment (`pulse`: scale up and back; `shake`: side to side, settling). */
+interface MotionWave {
+    kind: 'pulse' | 'shake';
+    amount: number;
+    count: number;
+}
+interface MotionSegment {
+    /** Node id (`""` for the camera). */
+    node: string;
+    property: MotionProperty;
+    start: number;
+    end: number;
+    from: MotionValue;
+    to: MotionValue;
+    ease: AnimationEasing;
+    /** The shot and command (index in `run`) it comes from. */
+    shot: string;
+    command: number;
+    wave?: MotionWave;
+    /** For `follow`: the path node id, and whether to turn with it. */
+    path?: string;
+    rotate?: boolean;
+}
+interface MotionShotTiming {
+    id: string;
+    index: number;
+    label?: string;
+    start: number;
+    /** When the camera move ends and the commands begin. */
+    commandsStart: number;
+    /** When the last command ends (the hold follows). */
+    commandsEnd: number;
+    end: number;
+}
+interface MotionCommandTiming {
+    shot: string;
+    shotIndex: number;
+    command: number;
+    type: MotionCommand['type'];
+    start: number;
+    end: number;
+    /** Length per target (ms). */
+    duration: number;
+}
+interface MotionTimeline {
+    /** Total length in ms. */
+    duration: number;
+    shots: MotionShotTiming[];
+    commands: MotionCommandTiming[];
+    segments: MotionSegment[];
+    /** Segments per `node\u0000property`, in start order. */
+    tracks: ReadonlyMap<string, readonly MotionSegment[]>;
+}
+/** Where a node sits in the artwork. */
+interface MotionNodeEntry {
+    node: VectorNode;
+    /** Ids from the root down to the node's parent. */
+    ancestors: string[];
+    /** Parent space → document space. */
+    parentWorld: AffineMatrix;
+    /** Centre of the node's bounds at rest, in its parent's space. */
+    center: {
+        x: number;
+        y: number;
+    };
+    /** Bounds at rest in document space. */
+    bounds: VectorBounds | null;
+}
+/** Every node of the artwork by id (cached per node list). */
+declare function indexMotionNodes(nodes: readonly VectorNode[]): Map<string, MotionNodeEntry>;
+/** A property's value with no animation. */
+declare function motionRestValue(entry: MotionNodeEntry | undefined, property: MotionProperty, artwork: {
+    width: number;
+    height: number;
+}): MotionValue;
+/** `from` → `to` at eased progress `u` (numbers extrapolate, colours mix in OKLab, others switch at the end). */
+declare function interpolateMotionValue(from: MotionValue, to: MotionValue, u: number): MotionValue;
+/** Progress (0–1, unclamped by the easing) of a segment at `time`. */
+declare function segmentProgress(segment: MotionSegment, time: number): {
+    u: number;
+    eased: number;
+};
+/** A segment's value at `time`. */
+declare function segmentValue(segment: MotionSegment, time: number): MotionValue;
+/** The segment in effect at `time` (the latest to have started), if any. */
+declare function activeSegment(track: readonly MotionSegment[] | undefined, time: number): MotionSegment | undefined;
+/** A track's value at `time`, or `undefined` when nothing animates it. */
+declare function trackValue(track: readonly MotionSegment[] | undefined, time: number): MotionValue | undefined;
+declare const motionTrackKey: (node: string, property: MotionProperty) => string;
+/** Grows a rectangle to the artwork's aspect ratio (about its centre). */
+declare function fitMotionRect(rect: MotionRect, aspect: number): MotionRect;
+/** The rectangle a camera looks at, or `null` when it frames an unknown node. */
+declare function resolveMotionCamera(camera: MotionCamera, scene: MotionScene): MotionRect | null;
+/** Length of a node's outline (its longest path for a group), in document units. */
+declare function motionPathLength(node: VectorNode, parentWorld?: AffineMatrix): number;
+/** How long one target of a command takes (ms). */
+declare function motionCommandDuration(command: MotionCommand, scene: MotionScene, target?: string): number;
+/** Cubic ease-out, `1 − (1 − t)³` exactly (Flair's `out`): the default for things arriving. */
+declare const MOTION_EASE_OUT: AnimationEasing;
+/** Cubic ease-in-out (close to Flair's `in-out`): the default for moves. */
+declare const MOTION_EASE_IN_OUT: AnimationEasing;
+/**
+ * Times every shot and command and turns them into segments. Pure and cached per scene object
+ * (treat scenes as immutable). Commands naming unknown nodes are timed but change nothing;
+ * `checkMotionScene` reports them.
+ */
+declare function compileMotionScene(scene: MotionScene): MotionTimeline;
+/** The shot playing at `time` (the last one at the end). */
+declare function motionShotAt(timeline: MotionTimeline, time: number): MotionShotTiming | undefined;
+
+/** The artwork as it stands at one time, and where the camera looks. */
+interface MotionFrame {
+    time: number;
+    document: VectorDocument;
+    camera: MotionRect;
+}
+interface MotionFrameOptions {
+    /** Control values (`{ accent: "#0ea5e9" }`): each recolours its control's default colour. */
+    values?: Record<string, string>;
+    /** Draw-on as a Trim Paths effect (default true). Off leaves strokes whole. */
+    draw?: boolean;
+    /** Apply moves, turns, scales and follows (default true). Off leaves nodes where they rest. */
+    offsets?: boolean;
+}
+/** Id of the trim effect that draws strokes on. */
+declare const MOTION_DRAW_EFFECT_ID = "~draw";
+/** A copy of the scene with each control's default colour replaced by its value (exact, case-insensitive matches). */
+declare function applyMotionControlValues(scene: MotionScene, values: Record<string, string> | undefined): MotionScene;
+/** The transform a node's offsets, turn, scale and follow add (parent space), or null when none. */
+declare function motionNodeOffset(entry: MotionNodeEntry, timeline: MotionTimeline, time: number, nodes?: Map<string, MotionNodeEntry>): {
+    matrix: AffineMatrix;
+    dx: number;
+    dy: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+} | null;
+/**
+ * The scene at `time` (ms): the artwork with every change applied, and the camera. A pure
+ * function of time, so frames can be drawn in any order (and the same frames come out every time).
+ */
+declare function motionFrameAt(scene: MotionScene, time: number, options?: MotionFrameOptions): MotionFrame;
+interface MotionSvgOptions extends MotionFrameOptions, VectorSvgExportOptions {
+}
+/** The scene at `time` as a standalone SVG (the camera becomes the `viewBox`). */
+declare function motionFrameToSvg(scene: MotionScene, time: number, options?: MotionSvgOptions): string;
+/** Replaces the root `viewBox` of an SVG string. */
+declare function withViewBox(svg: string, box: MotionRect): string;
+
+/** Changes shorter than this (ms) are too quick to follow. */
+declare const MOTION_MIN_CHANGE_MS = 120;
+/**
+ * What is wrong with a scene's meaning: unknown ids (with a "did you mean"), timing that
+ * fights itself, things animated while hidden or off camera, and lengths outside the target.
+ * The scene must be well formed (see `parseMotionScene`).
+ */
+declare function checkMotionScene(scene: MotionScene): MotionIssue[];
+
+/**
+ * Edits as data: each is a pure function of the scene, all or nothing. An edit that leaves the
+ * scene malformed, or adds an error the scene did not have (an unknown id, say), changes
+ * nothing and says why; existing errors do not block unrelated edits, so a broken scene can be
+ * fixed a step at a time.
+ */
+type MotionEdit = {
+    op: 'set_settings';
+    name?: string;
+    description?: string | null;
+    loop?: MotionScene['loop'];
+    fps?: number;
+    target?: [number, number] | null;
+} | {
+    op: 'insert_shots';
+    shots: MotionShot[];
+    at?: number;
+} | {
+    op: 'update_shot';
+    shot: string;
+    set?: Partial<MotionShot>;
+    remove?: ('label' | 'camera' | 'hold')[];
+} | {
+    op: 'delete_shots';
+    shots: string[];
+} | {
+    op: 'move_shot';
+    shot: string;
+    to: number;
+} | {
+    op: 'add_commands';
+    shot: string;
+    commands: MotionCommand[];
+    at?: number;
+} | {
+    op: 'update_command';
+    shot: string;
+    command: number;
+    set?: Record<string, unknown>;
+    remove?: string[];
+} | {
+    op: 'delete_commands';
+    shot: string;
+    commands: number[];
+} | {
+    op: 'set_artwork';
+    artwork: VectorDocument;
+} | {
+    op: 'set_controls';
+    controls: MotionControl[];
+    presets?: MotionPreset[];
+} | {
+    op: 'replace_scene';
+    scene: MotionScene;
+};
+type MotionEditOp = MotionEdit['op'];
+declare const MOTION_EDIT_OPS: readonly MotionEditOp[];
+type MotionEditResult = {
+    ok: true;
+    scene: MotionScene;
+    /** Every issue the edited scene has. */
+    issues: MotionIssue[];
+    /** Edits that work but may surprise (a later command undoes this one, say). */
+    hints: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** A free shot id: `base`, then `base-2`, `base-3`… */
+declare function freshShotId(scene: MotionScene, base?: string): string;
+/** Applies edits in order, as one change. Fails without changing anything when one fails. */
+declare function applyMotionEdits(scene: MotionScene, edits: MotionEdit | readonly MotionEdit[]): MotionEditResult;
+/** An empty scene over `artwork`. */
+declare function createMotionScene(artwork: VectorDocument, init?: Partial<Omit<MotionScene, 'artwork' | 'version'>>): MotionScene;
+
+/**
+ * Export to Flair (`@pixerate/flair`): a scene becomes an `SvgMotion` (one SVG plus a list of
+ * from → to changes on its elements), a catalog `VectorEffect`, or an `EffectDocument` for
+ * Flair's effect editor. The types are mirrored here so this package does not depend on Flair.
+ *
+ * Changes are exact where Flair can express them: a change with a linear, cubic-out or
+ * cubic-in-out curve (the editor's defaults) is one change. Anything else (other easings,
+ * pulses and shakes, follows, morphs and live-effect tweens) is sampled at the scene's `fps`
+ * into short linear changes, which Flair plays the same way.
+ */
+/** Flair's easing names. */
+type FlairEaseName = 'linear' | 'in-out' | 'out';
+/** Flair's curves, for matching. */
+declare const FLAIR_EASES: Readonly<Record<FlairEaseName, (t: number) => number>>;
+/** One change of a Flair `SvgMotion` (mirrors `SvgAnimation` in `@pixerate/flair/vector`). */
+interface FlairSvgAnimation {
+    id?: string;
+    step?: number;
+    delay?: number;
+    ms?: number;
+    ease?: FlairEaseName;
+    attrs?: Record<string, readonly [string | number, string | number]>;
+    draw?: boolean | readonly [number, number];
+    view?: readonly [number, number, number, number] | string;
+}
+/** Mirrors `SvgMotion` in `@pixerate/flair/vector`. */
+interface FlairSvgMotion {
+    svg: string;
+    animate?: FlairSvgAnimation[];
+}
+/** Mirrors Flair's catalog `VectorEffect` (`@pixerate/flair/catalog`). */
+interface FlairVectorEffect {
+    kind: 'vector';
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    tags: string[];
+    motion: FlairSvgMotion;
+    presets?: {
+        name: string;
+        values: Record<string, string>;
+    }[];
+    /** Ms on the last frame before looping. */
+    hold?: number;
+    trigger?: 'hover' | 'press' | 'click' | 'scroll';
+}
+/** Mirrors Flair's `EffectDocument` (`@pixerate/flair/editor`) for a vector effect. */
+interface FlairEffectDocument {
+    version: 1;
+    name: string;
+    effect: {
+        kind: 'vector';
+        motion: FlairSvgMotion;
+        hold?: number;
+    };
+    values: Record<string, string>;
+    tracks: Record<string, never>;
+    duration: number;
+    loop: boolean;
+    presets: {
+        name: string;
+        values: Record<string, string>;
+    }[];
+}
+interface FlairMotionExport {
+    motion: FlairSvgMotion;
+    /** The scene's length (ms). */
+    duration: number;
+    /** Ms after the last change (Flair's `hold`). */
+    hold: number;
+    /** Changes sampled into linear steps. */
+    sampled: number;
+    /** What could not be carried over, in sentences. */
+    notes: string[];
+}
+interface FlairExportOptions {
+    /** Sampling rate for changes Flair cannot express exactly (default: the scene's `fps`, else 30). */
+    fps?: number;
+    /** Decimal places (default 3). */
+    precision?: number;
+}
+/** The Flair easing that matches `ease` (within 1% everywhere), if any. */
+declare function flairEaseFor(ease: AnimationEasing): FlairEaseName | undefined;
+/** A scene as a Flair `SvgMotion`. */
+declare function toFlairSvgMotion(scene: MotionScene, options?: FlairExportOptions): FlairMotionExport;
+interface FlairEffectOptions extends FlairExportOptions {
+    /** Kebab-case id (default: the scene's name). */
+    id?: string;
+    name?: string;
+    description?: string;
+    /** Flair catalog category (default `icon`). */
+    category?: string;
+    tags?: string[];
+    trigger?: FlairVectorEffect['trigger'];
+}
+/** A scene as a Flair catalog vector effect, with its colour controls and presets. */
+declare function toFlairVectorEffect(scene: MotionScene, options?: FlairEffectOptions): FlairVectorEffect;
+/** A scene as a document for Flair's `EffectEditor` (`replaceDocument`). */
+declare function toFlairEffectDocument(scene: MotionScene, options?: FlairExportOptions): FlairEffectDocument;
+
+interface AnimationEditorOptions {
+    /** The scene to open (default: an empty one over a blank 800 × 450 artwork). */
+    scene?: MotionScene;
+    /** Shared undo history (default: a new one). */
+    history?: HistoryManager;
+    /** Time source for playback (default: requestAnimationFrame). Pass a `ManualClock` to step frames. */
+    clock?: Clock;
+    readOnly?: boolean;
+    /** Called after every change to the scene (not on playback or selection). */
+    onChange?: (scene: MotionScene) => void;
+}
+/** What is selected on the timeline: a shot, and optionally one of its commands. */
+interface AnimationEditorSelection {
+    shot: string;
+    command?: number;
+}
+/** A snapshot of the editor. The same object is returned until something changes. */
+interface AnimationEditorState {
+    scene: MotionScene;
+    /** Total length (ms). */
+    duration: number;
+    /** Each shot's timing. */
+    shots: readonly MotionShotTiming[];
+    /** The scene's problems (see `checkMotionScene`). */
+    issues: readonly MotionIssue[];
+    /** Playhead (ms). */
+    time: number;
+    playing: boolean;
+    loop: AnimationLoopMode;
+    /** Id of the shot under the playhead. */
+    currentShot: string | null;
+    selection: AnimationEditorSelection | null;
+    readOnly: boolean;
+    /** Why the last edit was refused, if it was. */
+    error: string | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string;
+    redoLabel: string;
+    /** Bumped on every change. */
+    revision: number;
+}
+/**
+ * Headless editor for a vector animation (a `MotionScene`): undoable, all-or-nothing edits,
+ * playback on an injectable clock, a timeline selection and frames at any time. UI-agnostic:
+ * React and Svelte bind it with `useAnimationEditor` / `createAnimationEditor`, and agents
+ * drive it through `createAnimationEditorToolProvider`. `getState()` returns the same object
+ * until something changes, so it works with `useSyncExternalStore` and Svelte runes.
+ */
+declare class AnimationEditorController {
+    readonly history: HistoryManager;
+    readonly player: AnimationPlayer;
+    private scene;
+    private issues;
+    private selection;
+    private readOnly;
+    private error;
+    private revision;
+    private applying;
+    private readonly onChange?;
+    private readonly listeners;
+    private readonly unsubscribers;
+    private state;
+    constructor(options?: AnimationEditorOptions);
+    private connect;
+    /**
+     * Pauses and stops listening to the player and history. Subscribing again reconnects, so a
+     * controller survives React StrictMode's unmount / remount.
+     */
+    destroy(): void;
+    getState: () => AnimationEditorState;
+    subscribe: (listener: (state: AnimationEditorState) => void) => (() => void);
+    /** The current scene (immutable; edit through the controller). */
+    getScene(): MotionScene;
+    private computeState;
+    private notify;
+    private setScene;
+    private commit;
+    private refuse;
+    /** Why edits are refused now, or `null` when they are allowed. */
+    readOnlyReason(): string | null;
+    /**
+     * Applies edits as one undo step, all or nothing (see `applyMotionEdits`). With
+     * `dryRun` it reports what would happen and changes nothing.
+     */
+    apply(edits: MotionEdit | readonly MotionEdit[], label?: string, options?: {
+        dryRun?: boolean;
+    }): MotionEditResult;
+    /** Replaces the artwork (e.g. from a vector editor's `onChange`), as one undo step. */
+    setArtwork(artwork: VectorDocument, label?: string): MotionEditResult;
+    /** Opens a scene (JSON or object). `clearHistory` drops the undo stack (opening a file); otherwise it is one undo step. */
+    load(scene: MotionScene | string, options?: {
+        clearHistory?: boolean;
+    }): MotionEditResult;
+    setReadOnly(readOnly: boolean): void;
+    /** Selects a shot (and optionally a command in it); `null` clears. Unknown shots clear. */
+    select(selection: AnimationEditorSelection | null): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Moves the playhead (ms). */
+    seek(time: number): void;
+    /** Moves the playhead to the start or end of a shot. Returns false for an unknown shot. */
+    seekShot(id: string, at?: 'start' | 'end'): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    /** The scene at `time` (default: the playhead). */
+    frame(time?: number, options?: MotionFrameOptions): MotionFrame;
+    /** The scene at `time` (default: the playhead) as SVG. */
+    toSvg(time?: number, options?: MotionSvgOptions): string;
+    /** The scene as a Flair `SvgMotion`. */
+    toFlairMotion(options?: FlairExportOptions): FlairMotionExport;
+    /** The scene as a Flair catalog vector effect. */
+    toFlairEffect(options?: FlairEffectOptions): FlairVectorEffect;
+    /** The scene as a Flair `EffectDocument`. */
+    toFlairDocument(options?: FlairExportOptions): FlairEffectDocument;
+}
+
+interface AnimationEditorToolProviderOptions {
+    /** Provider id (unique per registry). Default `animation`. */
+    id?: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+    /** The animation cannot be edited: write tools are hidden and `get_animation` says why. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Turns SVG into PNG (e.g. `rasterizeSvg`), so `render_animation_frame` can return an image. */
+    rasterize?: (svg: string, size: {
+        width: number;
+        height: number;
+    }) => Promise<{
+        data: string;
+        mimeType: string;
+    }> | {
+        data: string;
+        mimeType: string;
+    };
+}
+/** JSON Schema of one command (each type its own strict branch). */
+declare const MOTION_COMMAND_SCHEMA: JsonSchema;
+/** The elements of a scene's artwork, as agents see them. */
+declare function describeMotionElements(scene: MotionScene): {
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
+    effects?: {
+        id: string;
+        type: "trim" | "roundCorners" | "puckerBloat" | "twist" | "zigzag" | "wiggle" | "offset" | "merge" | "repeater" | "envelope";
+        numericParams: {
+            [k: string]: unknown;
+        };
+    }[] | undefined;
+    children?: string[] | undefined;
+    stroke?: string | undefined;
+    fill?: string | undefined;
+    hidden?: boolean | undefined;
+    parent?: string | undefined;
+    name?: string | undefined;
+    id: string;
+    type: "path" | "group";
+}[];
+/** A scene's shots with their timing, as agents see them. */
+declare function describeMotionShots(scene: MotionScene): {
+    commands: ({
+        start: number;
+        end: number;
+        type: "enter";
+        style?: MotionEnterStyle;
+        direction?: MotionDirection;
+        distance?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "exit";
+        style?: MotionExitStyle;
+        direction?: MotionDirection;
+        distance?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "draw";
+        to?: number;
+        from?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "move";
+        by?: {
+            x: number;
+            y: number;
+        };
+        to?: {
+            x: number;
+            y: number;
+        };
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "rotate";
+        by?: number;
+        to?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "scale";
+        to: number | {
+            x: number;
+            y: number;
+        };
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "fade";
+        to: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "style";
+        fill?: string;
+        stroke?: string;
+        strokeWidth?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "morph";
+        into: string;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "follow";
+        path: string;
+        rotate?: boolean;
+        from?: number;
+        to?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "pulse";
+        amount?: number;
+        count?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "shake";
+        amount?: number;
+        count?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "effect";
+        effect: string;
+        param: string;
+        to: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        start: number;
+        end: number;
+        type: "wait";
+        duration: number;
+        with?: "after" | "previous";
+        note?: string;
+        index: number;
+    })[];
+    hold?: number | undefined;
+    camera?: MotionCamera | undefined;
+    start: number;
+    end: number;
+    label?: string | undefined;
+    id: string;
+}[];
+/**
+ * Agent tools for an `AnimationEditorController`: read the scene (artwork elements, shots with
+ * their timing, issues), render a frame, export to Flair, and change it a step at a time. Every
+ * write is checked first (unknown ids with "did you mean", malformed commands), applies as one
+ * undo step, and returns the resulting timing and any new issues. Write tools are hidden while
+ * the animation is read-only.
+ */
+declare function createAnimationEditorToolProvider(controller: AnimationEditorController, options?: AnimationEditorToolProviderOptions): AgentToolProvider;
+
+/**
+ * A short authoring guide for a model writing vector animations with the animation editor's
+ * tools. Static, so it caches well as part of a system prompt.
+ */
+declare const ANIMATION_EDITOR_AGENT_INSTRUCTIONS = "You animate vector artwork. A scene is artwork (vector paths and groups, each with an id) plus shots.\n\nHow it plays\n- Shots play in order. A shot optionally moves the camera, plays its commands, then holds (default 600 ms).\n- Commands in a shot play one after another; give \"with\": \"previous\" to start one together with the command before, \"delay\" to wait, \"stagger\" to offset several targets.\n- Timing comes from the content: each command has a default length (enter 600 ms, move 700 ms, draw follows the path length). Only set \"duration\" to change the pace.\n- Anything that enters later is hidden until it enters. Things that never enter are visible from the start.\n- Every frame is a pure function of time: the same scene always plays the same frames.\n\nCommands\n- enter (fade, pop, grow, slide, draw) and exit (fade, shrink, slide, undraw) bring things in and out.\n- draw draws strokes on to a fraction; move, rotate, scale and fade change the pose (about the centre); style blends solid colours and stroke width.\n- morph turns a shape into another node's shape (keep the target hidden); follow moves along a path node; pulse and shake draw the eye.\n- effect tweens a numeric parameter of a live path effect already on the node (twist angle, wiggle time, zig zag size).\n\nWorking method\n1. get_animation to learn the element ids (set_animation_artwork_svg first if there is no artwork: give every element you will animate an id).\n2. Plan a few shots, each one idea. Add them with insert_shots, or edit_animation to make several edits as one step (dry_run first when unsure).\n3. check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result.\n4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.\n\nKeep motion purposeful: one thing moving at a time reads best, ease-out for arrivals, ease-in for exits, and hold long enough to see each result.";
+
+export { ANIMATION_EDITOR_AGENT_INSTRUCTIONS, AnimationEditorController, type AnimationEditorOptions, type AnimationEditorSelection, type AnimationEditorState, type AnimationEditorToolProviderOptions, FLAIR_EASES, type FlairEaseName, type FlairEffectDocument, type FlairEffectOptions, type FlairExportOptions, type FlairMotionExport, type FlairSvgAnimation, type FlairSvgMotion, type FlairVectorEffect, MOTION_CAMERA_MS, MOTION_COMMAND_SCHEMA, MOTION_COMMAND_TYPES, MOTION_DEFAULT_DURATIONS, MOTION_DEFAULT_HOLD, MOTION_DIRECTIONS, MOTION_DRAW_EFFECT_ID, MOTION_DRAW_MS_PER_UNIT, MOTION_DRAW_RANGE, MOTION_EASE_IN_OUT, MOTION_EASE_OUT, MOTION_EDIT_OPS, MOTION_ENTER_STYLES, MOTION_EXIT_STYLES, MOTION_ISSUE_CODES, MOTION_MIN_CHANGE_MS, type MotionCamera, type MotionCommand, type MotionCommandBase, type MotionCommandTiming, type MotionCommandType, type MotionControl, type MotionDirection, type MotionDrawCommand, type MotionEdit, type MotionEditOp, type MotionEditResult, type MotionEffectCommand, type MotionEnterCommand, type MotionEnterStyle, type MotionExitCommand, type MotionExitStyle, type MotionFadeCommand, type MotionFollowCommand, type MotionFrame, type MotionFrameOptions, type MotionIssue, type MotionIssueCode, type MotionIssueSeverity, type MotionMorphCommand, type MotionMoveCommand, type MotionNodeEntry, type MotionPreset, type MotionProperty, type MotionPulseCommand, type MotionRect, type MotionRotateCommand, type MotionScaleCommand, type MotionScene, MotionSceneFormatError, type MotionSegment, type MotionShakeCommand, type MotionShot, type MotionShotTiming, type MotionStyleCommand, type MotionSvgOptions, type MotionTimeline, type MotionValue, type MotionWaitCommand, type MotionWave, activeSegment, applyMotionControlValues, applyMotionEdits, checkMotionScene, commandShapeProblems, compileMotionScene, createAnimationEditorToolProvider, createMotionScene, describeMotionElements, describeMotionShots, fitMotionRect, flairEaseFor, freshShotId, indexMotionNodes, interpolateMotionValue, isMotionCommand, isMotionShot, motionCommandDuration, motionFrameAt, motionFrameToSvg, motionIssue, motionIssueKey, motionIssueLine, motionNodeOffset, motionPathLength, motionRestValue, motionSceneShapeProblems, motionSceneToJson, motionShotAt, motionTrackKey, namedWithSuggestion, parseMotionScene, resolveMotionCamera, segmentProgress, segmentValue, shotShapeProblems, suggestName, toFlairEffectDocument, toFlairSvgMotion, toFlairVectorEffect, trackValue, withViewBox };