@pixerate/editor 0.57.0 → 0.58.0

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

@@ -1,7 +1,8 @@
 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 { V as VectorDocument, a as VectorNode, b as VectorBounds, c as VectorSvgExportOptions } from '../svg-ymShkNtu.cjs';
+import { a as MotionBehavior } from '../behavior-Ymbld6jL.cjs';
+import { A as AffineMatrix, B as BezierPath } 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';
@@ -84,24 +85,46 @@ interface MotionCommandBase {
     /** 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 MotionEnterStyle = 'fade' | 'pop' | 'grow' | 'slide' | 'draw' | 'zoom' | 'rise' | 'wipe' | 'iris' | 'split';
+type MotionExitStyle = 'fade' | 'shrink' | 'slide' | 'undraw' | 'wipe';
 type MotionDirection = 'up' | 'down' | 'left' | 'right';
-/** Brings hidden targets in. Targets entered in a shot are hidden before it. */
+/** The opening an `iris` reveals through. */
+type MotionIrisShape = 'circle' | 'box';
+/** The line a `split` opens from. */
+type MotionSplitOrientation = 'horizontal' | 'vertical';
+/**
+ * Brings hidden targets in. Targets entered in a shot are hidden before it. Each style is a
+ * Flair motion primitive (`entrance.<style>`) with the same defaults.
+ */
 interface MotionEnterCommand extends MotionCommandBase {
     type: 'enter';
-    /** Default `fade`. `draw` draws the outline on, then fades the fill in. */
+    /**
+     * Default `fade`. `draw` draws the outline on, then fades the fill in. `pop` scales up past
+     * full size and settles; `zoom` settles from larger; `rise` rises a short way with a little
+     * overshoot. `wipe`, `iris` and `split` reveal the target through a clip over its box (see
+     * `MotionFrame.clips`), reaching past it far enough to show its whole stroke.
+     */
     style?: MotionEnterStyle;
-    /** For `slide`: the direction of travel (default `up`). */
+    /**
+     * For `slide`: the direction of travel (default `up`). For `wipe`: the way the edge travels
+     * (default `right`, which reveals from the left).
+     */
     direction?: MotionDirection;
-    /** For `slide`: how far in document units (default 40). */
+    /** For `slide` (default 40) and `rise` (default 20): how far in document units. */
     distance?: number;
+    /** For `pop` (default 0.5) and `zoom` (default 1.6): the starting scale. */
+    scale?: number;
+    /** For `iris`: open through a `circle` (default; an ellipse on a box that is not square) or a `box`. */
+    shape?: MotionIrisShape;
+    /** For `split`: open up and down from a `horizontal` line through the middle (default), or left and right from a `vertical` one. */
+    orientation?: MotionSplitOrientation;
 }
 /** Takes targets out. */
 interface MotionExitCommand extends MotionCommandBase {
     type: 'exit';
-    /** Default `fade`. */
+    /** Default `fade`. `wipe` hides the target behind an edge travelling `direction` (a wipe in, reversed). */
     style?: MotionExitStyle;
+    /** For `slide`: the direction of travel (default `down`). For `wipe`: the way the edge travels (default `right`, which hides from the left). */
     direction?: MotionDirection;
     distance?: number;
 }
@@ -161,7 +184,10 @@ 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). */
+    /**
+     * Turn with the path's direction (default false). Moves, shakes and wiggles made during the
+     * follow then turn with it too: they are offsets from the target's place on the path.
+     */
     rotate?: boolean;
     /** Fractions of the path's length to travel between (default 0 → 1). */
     from?: number;
@@ -174,12 +200,56 @@ interface MotionPulseCommand extends MotionCommandBase {
     amount?: number;
     count?: number;
 }
-/** Shakes side to side, settling. */
+/** Shakes side to side (or up and down), settling. */
 interface MotionShakeCommand extends MotionCommandBase {
     type: 'shake';
     /** Distance in document units (default 8). */
     amount?: number;
     count?: number;
+    /** Default `horizontal`. */
+    axis?: 'horizontal' | 'vertical';
+}
+/** Rocks about the centre by `angle` either way, settling (Flair's `emphasis.teeter`). */
+interface MotionTeeterCommand extends MotionCommandBase {
+    type: 'teeter';
+    /** Degrees either way (default 8). */
+    angle?: number;
+    /** Rocks (default 3). */
+    count?: number;
+}
+/** Bobs up and down without settling, like something floating (Flair's `emphasis.wave`). */
+interface MotionWaveCommand extends MotionCommandBase {
+    type: 'wave';
+    /** Height in document units (default 6). */
+    amount?: number;
+    /** Bobs (default 2). */
+    count?: number;
+}
+/**
+ * Wanders about its place as smooth seeded noise, easing out of and back to rest (Flair's
+ * `emphasis.wiggle`). The same seed always wanders the same way.
+ */
+interface MotionWiggleCommand extends MotionCommandBase {
+    type: 'wiggle';
+    /** Up to about this far, in document units (default 6). */
+    amount?: number;
+    /** Wanders per second, in Hz (default 3). */
+    frequency?: number;
+    /** Layers of finer detail (default 2). */
+    octaves?: number;
+    /** Also turns about the centre by up to about this many degrees (default 0). */
+    rotate?: number;
+    /** A whole number; default: one picked from the target's id, so each target wanders its own way. */
+    seed?: number;
+}
+/** Tints solid paint toward a colour and back, `count` times (Flair's `emphasis.color-pulse`). */
+interface MotionColorPulseCommand extends MotionCommandBase {
+    type: 'color-pulse';
+    /** The tint (default `#f59e0b`). Mixes in OKLab. */
+    color?: string;
+    /** Which paint (default `fill`). On a group it tints every path in it. */
+    paint?: 'fill' | 'stroke';
+    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 {
@@ -197,11 +267,13 @@ interface MotionWaitCommand {
     with?: 'after' | 'previous';
     note?: string;
 }
-type MotionCommand = MotionEnterCommand | MotionExitCommand | MotionDrawCommand | MotionMoveCommand | MotionRotateCommand | MotionScaleCommand | MotionFadeCommand | MotionStyleCommand | MotionMorphCommand | MotionFollowCommand | MotionPulseCommand | MotionShakeCommand | MotionEffectCommand | MotionWaitCommand;
+type MotionCommand = MotionEnterCommand | MotionExitCommand | MotionDrawCommand | MotionMoveCommand | MotionRotateCommand | MotionScaleCommand | MotionFadeCommand | MotionStyleCommand | MotionMorphCommand | MotionFollowCommand | MotionPulseCommand | MotionShakeCommand | MotionTeeterCommand | MotionWaveCommand | MotionWiggleCommand | MotionColorPulseCommand | 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_IRIS_SHAPES: readonly MotionIrisShape[];
+declare const MOTION_SPLIT_ORIENTATIONS: readonly MotionSplitOrientation[];
 declare const MOTION_DIRECTIONS: readonly MotionDirection[];
 /**
  * A colour parameter of the effect made from the scene: it stands for every use of its
@@ -228,6 +300,12 @@ 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];
+/**
+ * The Flair motion primitive (`@pixerate/flair/motion`) a command plays, or undefined when
+ * Flair has none (`move`, `scale`, `fade`, `style`, `morph`, `effect`, `wait` are the editor's
+ * own). Commands and primitives of the same name take the same parameters and defaults.
+ */
+declare function motionFlairPrimitive(command: MotionCommand): string | undefined;
 
 /**
  * Problems with a scene, as data: every issue has a stable `code`, a severity, the shot and
@@ -258,6 +336,10 @@ declare const MOTION_ISSUE_CODES: {
         readonly severity: "error";
         readonly wording: "A follow path must be a path node, not a group.";
     };
+    readonly 'reveal-no-box': {
+        readonly severity: "warning";
+        readonly wording: "A wipe, iris or split cannot clip a node with no width or height (a lone straight line), so it fades instead.";
+    };
     readonly 'unknown-shape': {
         readonly severity: "error";
         readonly wording: "A morph names a shape the artwork does not have.";
@@ -284,7 +366,7 @@ declare const MOTION_ISSUE_CODES: {
     };
     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 wording: "A style command recolours a gradient or empty paint, which only switches at the end, or a colour pulse has no solid paint to tint.";
     };
     readonly overlap: {
         readonly severity: "warning";
@@ -386,16 +468,12 @@ declare const isMotionCommand: (command: unknown) => command is MotionCommand;
  * 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]`.
+ * the view box `[x, y, width, height]`. `clipRect` (`[x, y, width, height]`) and `clipCircle`
+ * (`[cx, cy, r]`) are the reveal clips of `wipe`, `iris` and `split`, in the units of the
+ * node's own box (0–1 across it, SVG's `objectBoundingBox`), as Flair's clip reveals are.
  */
-type MotionProperty = 'opacity' | 'x' | 'y' | 'rotation' | 'scaleX' | 'scaleY' | 'fill' | 'stroke' | 'strokeWidth' | 'fillOpacity' | 'drawStart' | 'drawEnd' | 'shape' | 'follow' | 'camera' | `effect:${string}:${string}`;
+type MotionProperty = 'opacity' | 'x' | 'y' | 'rotation' | 'scaleX' | 'scaleY' | 'fill' | 'stroke' | 'strokeWidth' | 'fillOpacity' | 'drawStart' | 'drawEnd' | 'shape' | 'follow' | 'clipRect' | 'clipCircle' | '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;
@@ -408,7 +486,16 @@ interface MotionSegment {
     /** The shot and command (index in `run`) it comes from. */
     shot: string;
     command: number;
-    wave?: MotionWave;
+    /**
+     * How the change gets from `from` to `to` when not straight along its ease (a pulse there and
+     * back, a settling oscillation, a wriggle): Flair's `behavior`, exported as is.
+     */
+    behavior?: MotionBehavior;
+    /**
+     * Which number of the node's exported value this is (x 0, y 1, rotation 2, matching the
+     * transform Flair is given), so a wriggle wanders each on the channel Flair uses. Default 0.
+     */
+    index?: number;
     /** For `follow`: the path node id, and whether to turn with it. */
     path?: string;
     rotate?: boolean;
@@ -457,9 +544,39 @@ interface MotionNodeEntry {
     };
     /** Bounds at rest in document space. */
     bounds: VectorBounds | null;
+    /** Bounds at rest in its parent's space (what a reveal clip's box is). */
+    box: VectorBounds | null;
 }
 /** Every node of the artwork by id (cached per node list). */
 declare function indexMotionNodes(nodes: readonly VectorNode[]): Map<string, MotionNodeEntry>;
+/**
+ * How far past its box (as a share of its width and height) a reveal clip reaches, so it shows
+ * the whole stroke: the stroke's reach over the box plus 0.02, at most 1 (Flair's padding). Null
+ * when the box has no width or height (a lone straight line), which a clip cannot reveal.
+ */
+declare function motionRevealPadding(entry: MotionNodeEntry): readonly [number, number] | null;
+/** What a reveal clip animates: a wipe (in, or out with `hide`), an iris or a split. */
+type MotionReveal = {
+    style: 'wipe';
+    direction?: MotionDirection;
+    hide?: boolean;
+} | {
+    style: 'iris';
+    shape?: MotionIrisShape;
+} | {
+    style: 'split';
+    orientation?: MotionSplitOrientation;
+};
+/**
+ * The reveal clip a `wipe`, `iris` or `split` animates, from and to (Flair's `entrance.wipe`,
+ * `entrance.iris`, `entrance.split` and `exit.wipe`), or null when the node's box has no width
+ * or height. An exit wipe is the enter wipe the other way, reversed in time.
+ */
+declare function motionRevealClip(entry: MotionNodeEntry, reveal: MotionReveal): {
+    property: 'clipRect' | 'clipCircle';
+    from: number[];
+    to: number[];
+} | null;
 /** A property's value with no animation. */
 declare function motionRestValue(entry: MotionNodeEntry | undefined, property: MotionProperty, artwork: {
     width: number;
@@ -472,12 +589,15 @@ 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;
+/**
+ * A segment's value at `time`: along its ease, through its behaviour when it has one. `raw`
+ * ignores the behaviour (the value it swings towards), as Flair is given it.
+ */
+declare function segmentValue(segment: MotionSegment, time: number, raw?: boolean): 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;
+/** A track's value at `time`, or `undefined` when nothing animates it. `raw` ignores behaviours (see `segmentValue`). */
+declare function trackValue(track: readonly MotionSegment[] | undefined, time: number, raw?: boolean): 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;
@@ -500,11 +620,32 @@ 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;
 
+/**
+ * A reveal clip (`wipe`, `iris`, `split`) in the units of the node's own box: 0–1 across it,
+ * as SVG's `clipPathUnits="objectBoundingBox"` and Flair's clip reveals are.
+ */
+type MotionClipShape = {
+    shape: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | {
+    shape: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+};
 /** The artwork as it stands at one time, and where the camera looks. */
 interface MotionFrame {
     time: number;
     document: VectorDocument;
     camera: MotionRect;
+    /**
+     * Reveal clips by node id, outermost first: draw each of those nodes inside a group clipped
+     * to each shape (`motionFrameToSvg` does). The vector model has no clips, so they ride here.
+     */
+    clips: Record<string, MotionClipShape[]>;
 }
 interface MotionFrameOptions {
     /** Control values (`{ accent: "#0ea5e9" }`): each recolours its control's default colour. */
@@ -518,15 +659,33 @@ interface MotionFrameOptions {
 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>): {
+/**
+ * The path a node follows, in the node's parent's space (live effects left off), or null when
+ * `path` is not a path or cannot be measured. Lengths and turns along it are measured there.
+ */
+declare function motionFollowRoute(entry: MotionNodeEntry, path: MotionNodeEntry | undefined): BezierPath | null;
+/**
+ * The transform a node's offsets, turn, scale and follow add (parent space), or null when none:
+ * scaled and turned about its centre, offset by `dx`, `dy`, then (following a path) its centre
+ * carried to the point on the path and turned with it, as Flair's `along` carries a wrapper.
+ * `raw` ignores behaviours (the pose a pulse or shake swings towards, as Flair is given it);
+ * `follow: false` leaves the follow out (`dx` … `scaleY` never include it).
+ */
+declare function motionNodeOffset(entry: MotionNodeEntry, timeline: MotionTimeline, time: number, nodes?: Map<string, MotionNodeEntry>, raw?: boolean, follow?: boolean): {
     matrix: AffineMatrix;
     dx: number;
     dy: number;
     rotation: number;
     scaleX: number;
     scaleY: number;
+    follow: {
+        x: number;
+        y: number;
+        angle: number;
+    } | null;
 } | null;
+/** A node's reveal clips at `time`, outermost first (rect, then circle), with sizes kept ≥ 0. */
+declare function motionNodeClips(id: string, timeline: MotionTimeline, time: number): MotionClipShape[];
 /**
  * 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).
@@ -534,7 +693,9 @@ declare function motionNodeOffset(entry: MotionNodeEntry, timeline: MotionTimeli
 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`). */
+/** A clip shape's SVG attributes. */
+declare function motionClipAttrs(clip: MotionClipShape): Record<string, number>;
+/** The scene at `time` as a standalone SVG (the camera becomes the `viewBox`, reveal clips wrap their nodes). */
 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;
@@ -631,8 +792,16 @@ declare function createMotionScene(artwork: VectorDocument, init?: Partial<Omit<
  * 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, and so (Flair 0.36 and later) is
  * one with any cubic-bezier curve, written as `[x1, y1, x2, y2]`. Anything else (springs,
- * elastic, `hold`, 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.
+ * elastic, `hold`, morphs and live-effect tweens) is sampled at the
+ * scene's `fps` into short linear changes, which Flair plays the same way. Pulses, shakes,
+ * teeters, waves, wiggles and colour pulses are one change with a `behavior` (Flair 0.38).
+ *
+ * Reveals (`wipe`, `iris`, `split`) wrap their node in a group clipped through a rect or circle
+ * in the group's own box units (`clipPathUnits="objectBoundingBox"`), as Flair's
+ * `entrance.wipe` does, and animate the shape's attributes. A follow wraps its node in a group
+ * that Flair's `along` carries along a copy of the path in the node's parent's units (written
+ * in `<defs>`, so the path may be hidden or anywhere), turning with it for `orient`, as
+ * Flair's `path.follow` does.
  */
 /** Flair's easing names. */
 type FlairEaseName = 'linear' | 'in-out' | 'out';
@@ -649,6 +818,13 @@ interface FlairSvgAnimation {
     ease?: FlairEase;
     attrs?: Record<string, readonly [string | number, string | number]>;
     draw?: boolean | readonly [number, number];
+    /** Moves the element along a path (by id), from and to the fractions of its length in `at`. */
+    along?: string;
+    at?: readonly [number, number];
+    /** With `along`: turns the element with the path's direction. */
+    orient?: boolean;
+    /** Flair 0.38 and later: how the change swings from → to (see `MotionBehavior`). */
+    behavior?: MotionBehavior;
     view?: readonly [number, number, number, number] | string;
 }
 /** Mirrors `SvgMotion` in `@pixerate/flair/vector`. */
@@ -714,6 +890,12 @@ interface FlairExportOptions {
      * Flair, and they are sampled into linear steps.
      */
     curves?: boolean;
+    /**
+     * Write pulses, shakes, teeters, waves, wiggles and colour pulses as one change with a Flair
+     * `behavior` (default true), so they play exactly. Needs Flair 0.38 or later; set false for
+     * older Flair, and they are sampled into linear steps.
+     */
+    behaviors?: boolean;
 }
 /** The Flair easing that matches `ease` (within 1% everywhere), if any. */
 declare function flairEaseFor(ease: AnimationEasing): FlairEaseName | undefined;
@@ -906,12 +1088,16 @@ declare function describeMotionElements(scene: MotionScene): {
 /** A scene's shots with their timing, as agents see them. */
 declare function describeMotionShots(scene: MotionScene): {
     commands: ({
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "enter";
         style?: MotionEnterStyle;
         direction?: MotionDirection;
         distance?: number;
+        scale?: number;
+        shape?: MotionIrisShape;
+        orientation?: MotionSplitOrientation;
         targets: string[];
         duration?: number;
         delay?: number;
@@ -921,6 +1107,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "exit";
@@ -936,6 +1123,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "draw";
@@ -950,6 +1138,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "move";
@@ -970,6 +1159,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "rotate";
@@ -984,6 +1174,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "scale";
@@ -1000,6 +1191,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "fade";
@@ -1013,6 +1205,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "style";
@@ -1028,6 +1221,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "morph";
@@ -1041,6 +1235,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "follow";
@@ -1057,6 +1252,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "pulse";
@@ -1071,11 +1267,77 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "shake";
         amount?: number;
         count?: number;
+        axis?: "horizontal" | "vertical";
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        flairPrimitive?: string | undefined;
+        start: number;
+        end: number;
+        type: "teeter";
+        angle?: number;
+        count?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        flairPrimitive?: string | undefined;
+        start: number;
+        end: number;
+        type: "wave";
+        amount?: number;
+        count?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        flairPrimitive?: string | undefined;
+        start: number;
+        end: number;
+        type: "wiggle";
+        amount?: number;
+        frequency?: number;
+        octaves?: number;
+        rotate?: number;
+        seed?: number;
+        targets: string[];
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        with?: "after" | "previous";
+        ease?: AnimationEasing;
+        note?: string;
+        index: number;
+    } | {
+        flairPrimitive?: string | undefined;
+        start: number;
+        end: number;
+        type: "color-pulse";
+        color?: string;
+        paint?: "fill" | "stroke";
+        count?: number;
         targets: string[];
         duration?: number;
         delay?: number;
@@ -1085,6 +1347,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "effect";
@@ -1100,6 +1363,7 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     } | {
+        flairPrimitive?: string | undefined;
         start: number;
         end: number;
         type: "wait";
@@ -1128,6 +1392,6 @@ declare function createAnimationEditorToolProvider(controller: AnimationEditorCo
  * 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.";
+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- enter also reveals through a clip over the target's box: wipe (behind an edge travelling \"direction\", default right), iris (from the centre; \"shape\": circle or box) and split (from a line through the middle; \"orientation\": horizontal or vertical). exit wipe hides the same way. Reveals need a width and a height: use draw / undraw for a straight line.\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- enter also has zoom (settles from larger) and rise (rises a short way, overshooting a touch); pop and zoom take a starting \"scale\".\n- morph turns a shape into another node's shape (keep the target hidden); follow moves along a path node (with \"rotate\", moves made meanwhile turn with the path).\n- Emphasis draws the eye and returns to rest: pulse (swell), shake (side to side, or \"axis\": \"vertical\"), teeter (rock), wave (bob, no settling), wiggle (seeded wander; the same seed wanders the same way) and color-pulse (tint and back).\n- Commands share their names and defaults with Flair's motion primitives (get_animation shows each one's \"flairPrimitive\"), and emphasis, reveals and follows export to Flair exactly.\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 FlairEase, 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, flairCurveFor, 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 };
+export { ANIMATION_EDITOR_AGENT_INSTRUCTIONS, AnimationEditorController, type AnimationEditorOptions, type AnimationEditorSelection, type AnimationEditorState, type AnimationEditorToolProviderOptions, FLAIR_EASES, type FlairEase, 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_IRIS_SHAPES, MOTION_ISSUE_CODES, MOTION_MIN_CHANGE_MS, MOTION_SPLIT_ORIENTATIONS, type MotionCamera, type MotionClipShape, type MotionColorPulseCommand, 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 MotionIrisShape, type MotionIssue, type MotionIssueCode, type MotionIssueSeverity, type MotionMorphCommand, type MotionMoveCommand, type MotionNodeEntry, type MotionPreset, type MotionProperty, type MotionPulseCommand, type MotionRect, type MotionReveal, type MotionRotateCommand, type MotionScaleCommand, type MotionScene, MotionSceneFormatError, type MotionSegment, type MotionShakeCommand, type MotionShot, type MotionShotTiming, type MotionSplitOrientation, type MotionStyleCommand, type MotionSvgOptions, type MotionTeeterCommand, type MotionTimeline, type MotionValue, type MotionWaitCommand, type MotionWaveCommand, type MotionWiggleCommand, activeSegment, applyMotionControlValues, applyMotionEdits, checkMotionScene, commandShapeProblems, compileMotionScene, createAnimationEditorToolProvider, createMotionScene, describeMotionElements, describeMotionShots, fitMotionRect, flairCurveFor, flairEaseFor, freshShotId, indexMotionNodes, interpolateMotionValue, isMotionCommand, isMotionShot, motionClipAttrs, motionCommandDuration, motionFlairPrimitive, motionFollowRoute, motionFrameAt, motionFrameToSvg, motionIssue, motionIssueKey, motionIssueLine, motionNodeClips, motionNodeOffset, motionPathLength, motionRestValue, motionRevealClip, motionRevealPadding, motionSceneShapeProblems, motionSceneToJson, motionShotAt, motionTrackKey, namedWithSuggestion, parseMotionScene, resolveMotionCamera, segmentProgress, segmentValue, shotShapeProblems, suggestName, toFlairEffectDocument, toFlairSvgMotion, toFlairVectorEffect, trackValue, withViewBox };