@pixerate/editor 0.139.1 → 0.140.1

package/dist/animation-editor/index.js

@@ -48,7 +48,7 @@ import {
   createEffectToolProvider,
   isEffectError,
   resolveEffectValues
-} from "../chunk-KHMVB3SJ.js";
+} from "../chunk-7KWJEYIK.js";
 import "../chunk-V2ZCJRDM.js";
 import "../chunk-AGZ47XY2.js";
 import "../chunk-ODBT55Q7.js";
@@ -206,6 +206,7 @@ var COMMAND_KEYS = {
   effect: [...BASE_KEYS, "effect", "param", "to"],
   wait: ["type", "duration", "with", "note"]
 };
+var MOTION_COMMAND_FIELDS = COMMAND_KEYS;
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isNum = (v) => typeof v === "number" && Number.isFinite(v);
 var isPoint = (v) => isObject(v) && isNum(v.x) && isNum(v.y);
@@ -4041,106 +4042,194 @@ var DRAW_ORDER = {
   origin: object({ x: { type: "number", description: "Document units." }, y: { type: "number", description: "Document units." } }, ["x", "y"], "With sortBy distance: where strokes are drawn out from (default the target's centre).")
 };
 var command2 = (type, description, extra = {}, required = []) => object({ type: { const: type, description }, ...BASE, ...extra }, ["type", "targets", ...required], description);
+var MOTION_COMMAND_TYPE_SCHEMAS = {
+  enter: command2("enter", "Brings hidden targets in; they are hidden before this shot.", {
+    ...DRAW_ORDER,
+    style: {
+      type: "string",
+      enum: [...MOTION_ENTER_STYLES],
+      description: "fade (default), pop (scales up past full size and settles), grow (from nothing), slide, draw (outline drawn on, then the fill fades in), zoom (settles from larger), rise (rises a short way, overshooting a touch), or a reveal through a clip over the target's box: wipe (behind a travelling edge), iris (from the centre outwards) or split (from a line through the middle). Reveals need a box with a width and a height (not a lone straight line)."
+    },
+    direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "For slide: direction of travel (default up). For wipe: the way the edge travels (default right, revealing from the left)." },
+    distance: { type: "number", description: "For slide (default 40) and rise (default 20): document units." },
+    scale: { type: "number", minimum: 0, description: "For pop (default 0.5) and zoom (default 1.6): the starting scale (1 = rest size)." },
+    shape: { type: "string", enum: [...MOTION_IRIS_SHAPES], description: "For iris: open through a circle (default; an ellipse on a box that is not square) or a box." },
+    orientation: { type: "string", enum: [...MOTION_SPLIT_ORIENTATIONS], description: "For split: horizontal (default) opens up and down from a horizontal line through the middle; vertical opens left and right." }
+  }),
+  exit: command2("exit", "Takes targets out.", {
+    ...DRAW_ORDER,
+    style: { type: "string", enum: [...MOTION_EXIT_STYLES], description: "fade (default), shrink, slide, undraw, or wipe (hides behind a travelling edge through a clip over the target's box: a wipe in, reversed)." },
+    direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "For slide: direction of travel (default down). For wipe: the way the edge travels (default right, hiding from the left)." },
+    distance: { type: "number", description: "For slide: document units (default 40)." }
+  }),
+  draw: command2("draw", "Draws strokes on (or off) to a fraction of their length.", { ...DRAW_ORDER, comet: FRACTION("A travelling stroke this fraction of the length long: it runs along the path and off the end (leave out from and to)."), to: FRACTION("Fraction drawn at the end (default 1)."), from: FRACTION("Fraction drawn at the start (default: what is drawn now).") }),
+  move: command2("move", "Moves targets by an offset or so their centre lands on a point.", { via: { type: "array", items: POINT("A point the centre passes through."), minItems: 1, maxItems: 64, description: 'Waypoints (document units) the centre passes through on the way to "to" or "by", smoothly (velocity carries through each) and without overshooting any. Default length 700 ms + 400 per waypoint.' }, pacing: { type: "string", enum: ["even", "equal"], description: "With via: even (default) keeps the speed steady along the path; equal gives each stretch the same time." }, blend: BLEND("replace"), by: POINT("Offset in document units."), to: POINT("Point (document coordinates) for the centre.") }),
+  rotate: command2("rotate", "Turns targets about their centre (degrees, clockwise).", { blend: BLEND("replace"), by: { type: "number", description: "Degrees to turn by." }, to: { type: "number", description: "Angle to turn to, in degrees from rest." } }),
+  scale: command2("scale", "Scales targets about their centre (1 = rest size).", { blend: BLEND("replace"), to: { description: "A factor, or { x, y } factors.", anyOf: [{ type: "number" }, POINT("Factors per axis.")] }, geometric: { type: "boolean", description: "Grow by a steady factor, which reads as an even zoom (default false)." } }, ["to"]),
+  fade: command2("fade", "Changes opacity.", { to: FRACTION("Opacity at the end (0\u20131).") }, ["to"]),
+  style: command2("style", "Blends solid fill / stroke colours (in OKLab) and stroke width. On a group it changes every path in it.", {
+    fill: { type: "string", description: "CSS colour (hex, rgb(), rgba())." },
+    stroke: { type: "string", description: "CSS colour (hex, rgb(), rgba())." },
+    strokeWidth: { type: "number", minimum: 0, description: "Document units." }
+  }),
+  play: object(
+    {
+      type: { const: "play", description: 'Plays a clip (set_animation_clip) on the targets: its commands, with "$" standing for each target, timed as in a shot.' },
+      targets: NODE_IDS,
+      clip: { type: "string", minLength: 1, description: "The clip's name (get_animation lists them)." },
+      speed: { type: "number", minimum: 0.05, maximum: 20, description: "Play it this many times as fast (default 1)." },
+      delay: BASE.delay,
+      stagger: BASE.stagger,
+      with: BASE.with,
+      note: BASE.note
+    },
+    ["type", "targets", "clip"],
+    "Plays a clip on the targets."
+  ),
+  match: command2("match", `Smart Animate: tweens a group into another group (usually hidden), part by part. Parts pair by name, then by id with the group ids taken out (card-a-title \u2194 card-b-title), then by kind in order; each takes its partner's shape, paint and place. Unpaired parts fade out; parts of "into" with no partner do not appear (check_animation lists them).`, { into: { type: "string", minLength: 1, description: "Id of the group to become." } }, ["into"]),
+  morph: command2("morph", "Morphs each target into the shape (and paint) of another node, which usually stays hidden.", { into: { type: "string", minLength: 1, description: "Id of the node whose shape to take." } }, ["into"]),
+  follow: command2("follow", "Moves targets along a path node, centre on the path.", {
+    path: { type: "string", minLength: 1, description: "Id of a path node (it can be hidden)." },
+    rotate: { type: "boolean", description: "Turn with the path (default false); moves and shakes made meanwhile turn with it too." },
+    from: FRACTION("Where to start along the path (default 0)."),
+    to: FRACTION("Where to end along the path (default 1).")
+  }, ["path"]),
+  pulse: command2("pulse", "Scales up and back to draw the eye.", { blend: BLEND("add"), amount: { type: "number", description: "Extra scale at the peak (default 0.15)." }, count: { type: "integer", minimum: 1, description: "Pulses (default 1)." } }),
+  shake: command2("shake", "Shakes side to side (or up and down), settling.", {
+    blend: BLEND("add"),
+    amount: { type: "number", description: "Document units (default 8)." },
+    count: { type: "integer", minimum: 1, description: "Shakes (default 3)." },
+    axis: { type: "string", enum: ["horizontal", "vertical"], description: "Default horizontal." }
+  }),
+  teeter: command2("teeter", "Rocks about the centre either way, settling.", { blend: BLEND("add"), angle: { type: "number", description: "Degrees either way (default 8)." }, count: { type: "integer", minimum: 1, description: "Rocks (default 3)." } }),
+  wave: command2("wave", "Bobs up and down without settling, like something floating (default 1000 ms).", { blend: BLEND("add"), amount: { type: "number", description: "Height in document units (default 6)." }, count: { type: "integer", minimum: 1, description: "Bobs (default 2)." } }),
+  wiggle: command2("wiggle", "Wanders about its place as smooth seeded noise, easing out of and back to rest (default 1500 ms). The same seed always wanders the same way.", {
+    blend: BLEND("add"),
+    amount: { type: "number", description: "Up to about this far, in document units (default 6)." },
+    frequency: { type: "number", exclusiveMinimum: 0, description: "Wanders per second, in Hz (default 3)." },
+    octaves: { type: "integer", minimum: 1, maximum: 8, description: "Layers of finer detail (default 2)." },
+    rotate: { type: "number", description: "Also turns about the centre by up to about this many degrees (default 0)." },
+    seed: { type: "integer", minimum: 0, description: "Default: one picked from the target id, so each target wanders its own way." }
+  }),
+  "color-pulse": command2("color-pulse", "Tints solid paint toward a colour and back (mixed in OKLab). On a group it tints every path in it.", {
+    color: { type: "string", description: 'The tint, a CSS colour (default "#f59e0b").' },
+    paint: { type: "string", enum: ["fill", "stroke"], description: "Which paint (default fill)." },
+    count: { type: "integer", minimum: 1, description: "Pulses (default 1)." }
+  }),
+  effect: command2("effect", "Tweens a numeric parameter of a live path effect on the targets (twist angle, wiggle time, zig zag size, trim offset\u2026).", {
+    effect: { type: "string", minLength: 1, description: `Effect id from get_animation's element "effects".` },
+    param: { type: "string", minLength: 1, description: "A numeric parameter of that effect (listed with it)." },
+    to: { type: "number", description: "Value at the end." }
+  }, ["effect", "param", "to"]),
+  wait: object(
+    { type: { const: "wait", description: "Waits." }, duration: MS("How long"), with: BASE.with, note: BASE.note },
+    ["type", "duration"],
+    "Waits before the next command."
+  )
+};
 var MOTION_COMMAND_SCHEMA = {
   description: `A command (one of ${MOTION_COMMAND_TYPES.join(", ")}). Commands in a shot play one after another unless "with": "previous".`,
-  oneOf: [
-    command2("enter", "Brings hidden targets in; they are hidden before this shot.", {
-      ...DRAW_ORDER,
-      style: {
-        type: "string",
-        enum: [...MOTION_ENTER_STYLES],
-        description: "fade (default), pop (scales up past full size and settles), grow (from nothing), slide, draw (outline drawn on, then the fill fades in), zoom (settles from larger), rise (rises a short way, overshooting a touch), or a reveal through a clip over the target's box: wipe (behind a travelling edge), iris (from the centre outwards) or split (from a line through the middle). Reveals need a box with a width and a height (not a lone straight line)."
-      },
-      direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "For slide: direction of travel (default up). For wipe: the way the edge travels (default right, revealing from the left)." },
-      distance: { type: "number", description: "For slide (default 40) and rise (default 20): document units." },
-      scale: { type: "number", minimum: 0, description: "For pop (default 0.5) and zoom (default 1.6): the starting scale (1 = rest size)." },
-      shape: { type: "string", enum: [...MOTION_IRIS_SHAPES], description: "For iris: open through a circle (default; an ellipse on a box that is not square) or a box." },
-      orientation: { type: "string", enum: [...MOTION_SPLIT_ORIENTATIONS], description: "For split: horizontal (default) opens up and down from a horizontal line through the middle; vertical opens left and right." }
-    }),
-    command2("exit", "Takes targets out.", {
-      ...DRAW_ORDER,
-      style: { type: "string", enum: [...MOTION_EXIT_STYLES], description: "fade (default), shrink, slide, undraw, or wipe (hides behind a travelling edge through a clip over the target's box: a wipe in, reversed)." },
-      direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "For slide: direction of travel (default down). For wipe: the way the edge travels (default right, hiding from the left)." },
-      distance: { type: "number", description: "For slide: document units (default 40)." }
-    }),
-    command2("draw", "Draws strokes on (or off) to a fraction of their length.", { ...DRAW_ORDER, comet: FRACTION("A travelling stroke this fraction of the length long: it runs along the path and off the end (leave out from and to)."), to: FRACTION("Fraction drawn at the end (default 1)."), from: FRACTION("Fraction drawn at the start (default: what is drawn now).") }),
-    command2("move", "Moves targets by an offset or so their centre lands on a point.", { via: { type: "array", items: POINT("A point the centre passes through."), minItems: 1, maxItems: 64, description: 'Waypoints (document units) the centre passes through on the way to "to" or "by", smoothly (velocity carries through each) and without overshooting any. Default length 700 ms + 400 per waypoint.' }, pacing: { type: "string", enum: ["even", "equal"], description: "With via: even (default) keeps the speed steady along the path; equal gives each stretch the same time." }, blend: BLEND("replace"), by: POINT("Offset in document units."), to: POINT("Point (document coordinates) for the centre.") }),
-    command2("rotate", "Turns targets about their centre (degrees, clockwise).", { blend: BLEND("replace"), by: { type: "number", description: "Degrees to turn by." }, to: { type: "number", description: "Angle to turn to, in degrees from rest." } }),
-    command2("scale", "Scales targets about their centre (1 = rest size).", { blend: BLEND("replace"), to: { description: "A factor, or { x, y } factors.", anyOf: [{ type: "number" }, POINT("Factors per axis.")] }, geometric: { type: "boolean", description: "Grow by a steady factor, which reads as an even zoom (default false)." } }, ["to"]),
-    command2("fade", "Changes opacity.", { to: FRACTION("Opacity at the end (0\u20131).") }, ["to"]),
-    command2("style", "Blends solid fill / stroke colours (in OKLab) and stroke width. On a group it changes every path in it.", {
-      fill: { type: "string", description: "CSS colour (hex, rgb(), rgba())." },
-      stroke: { type: "string", description: "CSS colour (hex, rgb(), rgba())." },
-      strokeWidth: { type: "number", minimum: 0, description: "Document units." }
-    }),
+  oneOf: MOTION_COMMAND_TYPES.map((type) => MOTION_COMMAND_TYPE_SCHEMAS[type])
+};
+var REF2 = (name, description) => ({ $ref: `#/$defs/${name}`, ...description ? { description } : {} });
+var firstSentence = (text) => /^.*?[.;](?=\s|$)/.exec(text)?.[0] ?? text;
+var COMMAND_TYPE_LINES = MOTION_COMMAND_TYPES.map((type) => `${type}: ${firstSentence(MOTION_COMMAND_TYPE_SCHEMAS[type].description ?? "")}`);
+var EASE_COMPACT = {
+  description: `Easing: a preset, or a curve { "type": "cubic-bezier", x1, y1, x2, y2 }, { "type": "spring", stiffness, damping, mass, velocity } (spring presets are Figma's; with no "duration" it lasts until it settles) or { "type": "elastic", amplitude, period, mode }. Default: ease-out for entrances, ease-in-out for moves.`,
+  anyOf: [
+    { type: "string", enum: [...ANIMATION_EASING_PRESETS] },
     object(
       {
-        type: { const: "play", description: 'Plays a clip (set_animation_clip) on the targets: its commands, with "$" standing for each target, timed as in a shot.' },
-        targets: NODE_IDS,
-        clip: { type: "string", minLength: 1, description: "The clip's name (get_animation lists them)." },
-        speed: { type: "number", minimum: 0.05, maximum: 20, description: "Play it this many times as fast (default 1)." },
-        delay: BASE.delay,
-        stagger: BASE.stagger,
-        with: BASE.with,
-        note: BASE.note
+        type: { type: "string", enum: ["cubic-bezier", "spring", "elastic"], description: "Curve kind." },
+        x1: { type: "number", description: "cubic-bezier: out handle x (0\u20131)." },
+        y1: { type: "number", description: "cubic-bezier: out handle y." },
+        x2: { type: "number", description: "cubic-bezier: in handle x (0\u20131)." },
+        y2: { type: "number", description: "cubic-bezier: in handle y." },
+        stiffness: { type: "number", exclusiveMinimum: 0, description: "spring: default 170." },
+        damping: { type: "number", minimum: 0, description: "spring: default 26, lower bounces more." },
+        mass: { type: "number", exclusiveMinimum: 0, description: "spring: default 1." },
+        velocity: { type: "number", description: "spring: starting speed (default 0)." },
+        amplitude: { type: "number", minimum: 0, description: "elastic: overshoot (default 1)." },
+        period: { type: "number", exclusiveMinimum: 0, description: "elastic: fraction of the length (default 0.3)." },
+        mode: { type: "string", enum: ["out", "in", "in-out"], description: "elastic: default out." }
       },
-      ["type", "targets", "clip"],
-      "Plays a clip on the targets."
-    ),
-    command2("match", `Smart Animate: tweens a group into another group (usually hidden), part by part. Parts pair by name, then by id with the group ids taken out (card-a-title \u2194 card-b-title), then by kind in order; each takes its partner's shape, paint and place. Unpaired parts fade out; parts of "into" with no partner do not appear (check_animation lists them).`, { into: { type: "string", minLength: 1, description: "Id of the group to become." } }, ["into"]),
-    command2("morph", "Morphs each target into the shape (and paint) of another node, which usually stays hidden.", { into: { type: "string", minLength: 1, description: "Id of the node whose shape to take." } }, ["into"]),
-    command2("follow", "Moves targets along a path node, centre on the path.", {
-      path: { type: "string", minLength: 1, description: "Id of a path node (it can be hidden)." },
-      rotate: { type: "boolean", description: "Turn with the path (default false); moves and shakes made meanwhile turn with it too." },
-      from: FRACTION("Where to start along the path (default 0)."),
-      to: FRACTION("Where to end along the path (default 1).")
-    }, ["path"]),
-    command2("pulse", "Scales up and back to draw the eye.", { blend: BLEND("add"), amount: { type: "number", description: "Extra scale at the peak (default 0.15)." }, count: { type: "integer", minimum: 1, description: "Pulses (default 1)." } }),
-    command2("shake", "Shakes side to side (or up and down), settling.", {
-      blend: BLEND("add"),
-      amount: { type: "number", description: "Document units (default 8)." },
-      count: { type: "integer", minimum: 1, description: "Shakes (default 3)." },
-      axis: { type: "string", enum: ["horizontal", "vertical"], description: "Default horizontal." }
-    }),
-    command2("teeter", "Rocks about the centre either way, settling.", { blend: BLEND("add"), angle: { type: "number", description: "Degrees either way (default 8)." }, count: { type: "integer", minimum: 1, description: "Rocks (default 3)." } }),
-    command2("wave", "Bobs up and down without settling, like something floating (default 1000 ms).", { blend: BLEND("add"), amount: { type: "number", description: "Height in document units (default 6)." }, count: { type: "integer", minimum: 1, description: "Bobs (default 2)." } }),
-    command2("wiggle", "Wanders about its place as smooth seeded noise, easing out of and back to rest (default 1500 ms). The same seed always wanders the same way.", {
-      blend: BLEND("add"),
-      amount: { type: "number", description: "Up to about this far, in document units (default 6)." },
-      frequency: { type: "number", exclusiveMinimum: 0, description: "Wanders per second, in Hz (default 3)." },
-      octaves: { type: "integer", minimum: 1, maximum: 8, description: "Layers of finer detail (default 2)." },
-      rotate: { type: "number", description: "Also turns about the centre by up to about this many degrees (default 0)." },
-      seed: { type: "integer", minimum: 0, description: "Default: one picked from the target id, so each target wanders its own way." }
-    }),
-    command2("color-pulse", "Tints solid paint toward a colour and back (mixed in OKLab). On a group it tints every path in it.", {
-      color: { type: "string", description: 'The tint, a CSS colour (default "#f59e0b").' },
-      paint: { type: "string", enum: ["fill", "stroke"], description: "Which paint (default fill)." },
-      count: { type: "integer", minimum: 1, description: "Pulses (default 1)." }
-    }),
-    command2("effect", "Tweens a numeric parameter of a live path effect on the targets (twist angle, wiggle time, zig zag size, trim offset\u2026).", {
-      effect: { type: "string", minLength: 1, description: `Effect id from get_animation's element "effects".` },
-      param: { type: "string", minLength: 1, description: "A numeric parameter of that effect (listed with it)." },
-      to: { type: "number", description: "Value at the end." }
-    }, ["effect", "param", "to"]),
-    object(
-      { type: { const: "wait", description: "Waits." }, duration: MS("How long"), with: BASE.with, note: BASE.note },
-      ["type", "duration"],
-      "Waits before the next command."
+      ["type"]
     )
   ]
 };
+var COMMAND = object(
+  {
+    type: {
+      type: "string",
+      enum: [...MOTION_COMMAND_TYPES],
+      description: `${COMMAND_TYPE_LINES.join(" ")} The fields from blend on say which types take them; play takes no duration, ease, split, cascade, repeat or steps, and wait only duration, with and note. describe_animation_command gives a type's full schema.`
+    },
+    targets: { ...NODE_IDS, description: `Node ids from get_animation's "elements" (a group animates as one; "$" in a clip). Required except for wait.` },
+    duration: MS("Length for each target (each type has a default; draw follows the path length)"),
+    delay: MS("Wait before starting (default 0)"),
+    stagger: MS("Start each further target this much later (default 0)"),
+    with: BASE.with,
+    ease: REF2("ease", "Easing (default ease-out for entrances, ease-in-out for moves)."),
+    note: BASE.note,
+    split: { type: "string", enum: ["letter", "word", "line"], description: "Outlined text (a group of letter paths): animate a letter, word or line at a time, staggered. get_text_layout shows the units." },
+    cascade: { type: "string", enum: ["forward", "backward", "center", "edges", "random"], description: "With split: the order units go in (default forward)." },
+    repeat: { type: "integer", minimum: 1, maximum: 1e3, description: 'Play it this many times (default 1); "duration" is one cycle. Not for enter or exit.' },
+    repeatMode: { type: "string", enum: [...MOTION_REPEAT_MODES], description: "With repeat: loop (default), mirror (every other cycle backwards) or offset (carry on from where the last ended)." },
+    steps: { type: "number", exclusiveMinimum: 0, maximum: 120, description: `Stepped time, frames per second to hold on (12 = "on twos"). Default: the scene's steps, else smooth.` },
+    blend: { type: "string", enum: [...MOTION_BLENDS], description: 'move, rotate, scale, emphasis: "replace" is a change the next takes over from (default for move, rotate, scale), "add" a layer over the pose (default for emphasis).' },
+    style: { type: "string", enum: [.../* @__PURE__ */ new Set([...MOTION_ENTER_STYLES, ...MOTION_EXIT_STYLES])], description: `enter: ${MOTION_ENTER_STYLES.join(", ")} (default fade). exit: ${MOTION_EXIT_STYLES.join(", ")} (default fade).` },
+    direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "enter / exit slide or wipe: the way it travels (default up for enter slide, down for exit slide, right for wipe)." },
+    distance: { type: "number", description: "enter / exit slide (default 40), enter rise (default 20): document units." },
+    scale: { type: "number", minimum: 0, description: "enter pop (default 0.5) or zoom (default 1.6): the starting scale." },
+    shape: { type: "string", enum: [...MOTION_IRIS_SHAPES], description: "enter iris: open through a circle (default) or a box." },
+    orientation: { type: "string", enum: [...MOTION_SPLIT_ORIENTATIONS], description: "enter split: the line it opens from (default horizontal)." },
+    order: { type: "string", enum: ["together", "sequence"], description: "draw, enter draw, exit undraw on several strokes: together (default) or sequence (one after another)." },
+    pace: { type: "string", enum: ["time", "speed"], description: "With order together: every stroke takes the whole time (default) or all go at one speed." },
+    align: { type: "string", enum: ["start", "end"], description: "With pace speed: start together (default) or finish together." },
+    sortBy: { type: "string", enum: ["document", "distance"], description: "With order sequence: stacking order (default) or distance from origin." },
+    origin: REF2("point", "With sortBy distance: where strokes are drawn out from (default the target's centre)."),
+    from: FRACTION("draw: fraction drawn at the start (default: what is drawn now). follow: where to start along the path (default 0)."),
+    to: { anyOf: [{ type: "number" }, REF2("point")], description: "move: point for the centre. rotate: angle in degrees. scale: factor or { x, y } factors (required). fade: opacity 0\u20131 (required). draw: fraction drawn (default 1). follow: where to end on the path (default 1). effect: the value (required)." },
+    by: { anyOf: [{ type: "number" }, REF2("point")], description: "move: offset { x, y } in document units. rotate: degrees to turn by." },
+    comet: FRACTION("draw: a travelling stroke this fraction of the length long (leave out from and to)."),
+    via: { type: "array", items: REF2("point"), minItems: 1, maxItems: 64, description: 'move: waypoints the centre passes through smoothly on the way to "to" or "by".' },
+    pacing: { type: "string", enum: ["even", "equal"], description: "move with via: steady speed (even, default) or the same time per stretch (equal)." },
+    geometric: { type: "boolean", description: "scale: grow by a steady factor, an even zoom (default false)." },
+    fill: { type: "string", description: "style: fill colour, CSS (hex, rgb(), rgba())." },
+    stroke: { type: "string", description: "style: stroke colour, CSS." },
+    strokeWidth: { type: "number", minimum: 0, description: "style: stroke width, document units." },
+    clip: { type: "string", minLength: 1, description: "play: the clip's name (required)." },
+    speed: { type: "number", minimum: 0.05, maximum: 20, description: "play: this many times as fast (default 1)." },
+    into: { type: "string", minLength: 1, description: "match: id of the group to become. morph: id of the node whose shape to take (required)." },
+    path: { type: "string", minLength: 1, description: "follow: id of a path node (required; it can be hidden)." },
+    rotate: { type: ["boolean", "number"], description: "follow: turn with the path (boolean, default false). wiggle: also turn by up to this many degrees (default 0)." },
+    amount: { type: "number", description: "pulse: extra scale at the peak (default 0.15). shake (8), wave (6), wiggle (6): document units." },
+    count: { type: "integer", minimum: 1, description: "pulse, shake, teeter, wave, color-pulse: how many times." },
+    axis: { type: "string", enum: ["horizontal", "vertical"], description: "shake: default horizontal." },
+    angle: { type: "number", description: "teeter: degrees either way (default 8)." },
+    frequency: { type: "number", exclusiveMinimum: 0, description: "wiggle: wanders per second, Hz (default 3)." },
+    octaves: { type: "integer", minimum: 1, maximum: 8, description: "wiggle: layers of finer detail (default 2)." },
+    seed: { type: "integer", minimum: 0, description: "wiggle: noise seed (default: from the target id)." },
+    color: { type: "string", description: 'color-pulse: the tint, a CSS colour (default "#f59e0b").' },
+    paint: { type: "string", enum: ["fill", "stroke"], description: "color-pulse: which paint (default fill)." },
+    effect: { type: "string", minLength: 1, description: `effect: effect id from get_animation's element "effects" (required).` },
+    param: { type: "string", minLength: 1, description: "effect: a numeric parameter of that effect (required)." }
+  },
+  ["type"],
+  'A command. Commands in a shot play one after another unless "with": "previous".'
+);
 var GEOMETRIC_CAMERA = { type: "boolean", description: "Zoom at a steady rate, so a big zoom does not rush at the start (default false)." };
 var CAMERA = {
   description: `Where the camera looks: a rectangle { x, y, width, height } in document units, or { frame: "<node id>", padding } to frame a node (fitted to the artwork's shape). It eases there over "ms" (default 1000); the first shot cuts.`,
   anyOf: [
-    object({ x: { type: "number", description: "Left." }, y: { type: "number", description: "Top." }, width: { type: "number", exclusiveMinimum: 0, description: "Width." }, height: { type: "number", exclusiveMinimum: 0, description: "Height." }, ease: EASE, ms: MS("Camera move length"), geometric: GEOMETRIC_CAMERA }, ["x", "y", "width", "height"]),
-    object({ frame: { type: "string", minLength: 1, description: "Node id to frame." }, padding: { type: "number", description: "Margin around it (default 24)." }, ease: EASE, ms: MS("Camera move length"), geometric: GEOMETRIC_CAMERA }, ["frame"])
+    object({ x: { type: "number", description: "Left." }, y: { type: "number", description: "Top." }, width: { type: "number", exclusiveMinimum: 0, description: "Width." }, height: { type: "number", exclusiveMinimum: 0, description: "Height." }, ease: REF2("ease"), ms: MS("Camera move length"), geometric: GEOMETRIC_CAMERA }, ["x", "y", "width", "height"]),
+    object({ frame: { type: "string", minLength: 1, description: "Node id to frame." }, padding: { type: "number", description: "Margin around it (default 24)." }, ease: REF2("ease"), ms: MS("Camera move length"), geometric: GEOMETRIC_CAMERA }, ["frame"])
   ]
 };
 var SHOT_FIELDS = {
   label: { type: "string", description: "What happens, in a few words." },
-  camera: CAMERA,
-  run: { type: "array", items: MOTION_COMMAND_SCHEMA, description: "Commands, in order." },
+  camera: REF2("camera"),
+  run: { type: "array", items: REF2("command"), description: "Commands, in order." },
   hold: MS("Hold after the commands (default 600)"),
   speed: { type: "number", minimum: 0.05, maximum: 20, description: "Play the whole shot this many times as fast (default 1; 0.5 is half speed). fit_animation sets it." },
   at: object(
@@ -4161,6 +4250,26 @@ var CONTROL = object(
   "A colour parameter of the Flair effect made from the scene."
 );
 var PRESET = object({ name: { type: "string", minLength: 1, description: "Preset name." }, values: { type: "object", additionalProperties: { type: "string" }, description: "Control name \u2192 colour." } }, ["name", "values"], "Named control values.");
+var DEFS = {
+  point: POINT("A point (or offset) in document units."),
+  ease: EASE_COMPACT,
+  command: COMMAND,
+  camera: CAMERA,
+  shot: SHOT
+};
+function withDefs(schema) {
+  const used = /* @__PURE__ */ new Set();
+  const visit = (value) => {
+    for (const [, name] of JSON.stringify(value).matchAll(/"#\/\$defs\/(\w+)"/g)) {
+      if (used.has(name)) continue;
+      used.add(name);
+      visit(DEFS[name]);
+    }
+  };
+  visit(schema);
+  if (!used.size) return schema;
+  return { ...schema, $defs: Object.fromEntries(Object.keys(DEFS).filter((n) => used.has(n)).map((n) => [n, DEFS[n]])) };
+}
 var SETTINGS = {
   name: { type: "string", minLength: 1, description: 'Short name, e.g. "logo-reveal".' },
   description: { type: ["string", "null"], description: "What it shows; null clears." },
@@ -4195,11 +4304,11 @@ var EDIT_OP = {
   description: `One edit (${MOTION_EDIT_OPS.filter((o) => o !== "replace_scene" && o !== "set_artwork").join(", ")}), shaped like the tool of the same name with an "op" field.`,
   oneOf: [
     object({ op: { const: "set_settings", description: "Like set_animation_settings." }, ...SETTINGS }, ["op"]),
-    object({ op: { const: "insert_shots", description: "Like insert_shots." }, shots: { type: "array", items: SHOT, minItems: 1, description: "Shots to add." }, at: { type: "integer", minimum: 0, description: "Position (default: the end)." } }, ["op", "shots"]),
+    object({ op: { const: "insert_shots", description: "Like insert_shots." }, shots: { type: "array", items: REF2("shot"), minItems: 1, description: "Shots to add." }, at: { type: "integer", minimum: 0, description: "Position (default: the end)." } }, ["op", "shots"]),
     object({ op: { const: "update_shot", description: "Like update_shot." }, shot: SHOT_ID, set: object({ id: SHOT.properties.id, ...SHOT_FIELDS }, [], "Fields to replace."), remove: { type: "array", items: { type: "string", enum: ["label", "camera", "hold", "speed", "at"] }, description: "Fields to clear." } }, ["op", "shot"]),
     object({ op: { const: "delete_shots", description: "Like delete_shots." }, shots: { type: "array", items: SHOT_ID, minItems: 1, description: "Shot ids." } }, ["op", "shots"]),
     object({ op: { const: "move_shot", description: "Like move_shot." }, shot: SHOT_ID, to: { type: "integer", minimum: 0, description: "New position (0 = first)." } }, ["op", "shot", "to"]),
-    object({ op: { const: "add_commands", description: "Like add_commands." }, shot: SHOT_ID, commands: { type: "array", items: MOTION_COMMAND_SCHEMA, minItems: 1, description: "Commands to add." }, at: { type: "integer", minimum: 0, description: "Index in the shot's run (default: the end)." } }, ["op", "shot", "commands"]),
+    object({ op: { const: "add_commands", description: "Like add_commands." }, shot: SHOT_ID, commands: { type: "array", items: REF2("command"), minItems: 1, description: "Commands to add." }, at: { type: "integer", minimum: 0, description: "Index in the shot's run (default: the end)." } }, ["op", "shot", "commands"]),
     object({ op: { const: "update_command", description: "Like update_command." }, shot: SHOT_ID, command: { anyOf: [{ type: "integer", minimum: 0 }, { type: "string", pattern: "^\\$(\\d+|last)[.\\[]" }], description: `Index in the shot's run, or a reference to an earlier op's outcome such as "$0.indexes[0]".` }, set: { type: "object", description: "Command fields to replace." }, remove: { type: "array", items: { type: "string" }, description: "Command fields to clear." } }, ["op", "shot", "command"]),
     object({ op: { const: "move_command", description: "Like move_command." }, shot: SHOT_ID, command: { anyOf: [{ type: "integer", minimum: 0 }, { type: "string", pattern: "^\\$(\\d+|last)[.\\[]" }], description: `Index in the shot's run, or a reference to an earlier op's outcome such as "$0.indexes[0]".` }, to: { type: "integer", minimum: 0, description: "New index in the run (0 = first)." } }, ["op", "shot", "command", "to"]),
     object({ op: { const: "delete_commands", description: "Like delete_commands." }, shot: SHOT_ID, commands: { type: "array", items: { anyOf: [{ type: "integer", minimum: 0 }, { type: "string", pattern: "^\\$(\\d+|last)[.\\[]" }], description: `An index, or a reference to an earlier op's outcome such as "$0.indexes[0]".` }, minItems: 1, description: "Indexes in the shot's run." } }, ["op", "shot", "commands"]),
@@ -4309,6 +4418,21 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       };
     }
   };
+  const describeCommand = {
+    name: "describe_animation_command",
+    title: "Describe command types",
+    description: "Returns the full JSON Schema of each given command type: every field it takes with its type, range, default and meaning, and which are required. The write tools list every field once in short; call this before writing a type you have not used yet or when a write rejects a field. Returns { commands: [{ type, schema }] }.",
+    inputSchema: object(
+      { types: { type: "array", items: { type: "string", enum: [...MOTION_COMMAND_TYPES] }, minItems: 1, uniqueItems: true, description: `Command types, e.g. ["enter", "move"] (any of ${MOTION_COMMAND_TYPES.join(", ")}).` } },
+      ["types"]
+    ),
+    annotations: { title: "Describe command types", ...READ },
+    handler: ({ types }) => {
+      for (const type of types)
+        if (!MOTION_COMMAND_TYPES.includes(type)) throw new Error(`There is no command type ${namedWithSuggestion(type, MOTION_COMMAND_TYPES)}; use one of ${MOTION_COMMAND_TYPES.join(", ")}.`);
+      return { commands: types.map((type) => ({ type, schema: MOTION_COMMAND_TYPE_SCHEMAS[type] })) };
+    }
+  };
   const getShot = {
     name: "get_shot",
     title: "Read one shot",
@@ -4640,7 +4764,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       {
         name: { type: "string", pattern: "^[A-Za-z_][\\w-]*$", description: 'Clip name, e.g. "pop-settle".' },
         clip: {
-          anyOf: [object({ description: { type: "string", description: "What it does, in a few words." }, run: { type: "array", items: MOTION_COMMAND_SCHEMA, minItems: 1, description: 'Commands, timed as in a shot; target "$" for the node it is played on. Clips cannot play clips.' } }, ["run"]), { type: "null" }],
+          anyOf: [object({ description: { type: "string", description: "What it does, in a few words." }, run: { type: "array", items: REF2("command"), minItems: 1, description: 'Commands, timed as in a shot; target "$" for the node it is played on. Clips cannot play clips.' } }, ["run"]), { type: "null" }],
           description: "The clip, or null to delete it (refused while a play command uses it)."
         }
       },
@@ -4698,7 +4822,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     name: "insert_shots",
     title: "Add shots",
     description: "Adds shots (one undo step) at a position (default: the end). Returns every shot's new timing and any issues.",
-    inputSchema: object({ shots: { type: "array", items: SHOT, minItems: 1, description: "Shots to add." }, at: { type: "integer", minimum: 0, description: "Position, 0 = first (default: the end)." } }, ["shots"]),
+    inputSchema: object({ shots: { type: "array", items: REF2("shot"), minItems: 1, description: "Shots to add." }, at: { type: "integer", minimum: 0, description: "Position, 0 = first (default: the end)." } }, ["shots"]),
     annotations: { title: "Add shots", ...WRITE },
     handler: ({ shots, at }) => apply({ op: "insert_shots", shots, at }, "Add shots", () => ({ added: shots.map((s) => s.id) }))
   };
@@ -4737,7 +4861,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     name: "add_commands",
     title: "Add commands to a shot",
     description: "Adds commands to a shot's run (one undo step), at an index (default: the end). Returns the indexes they got, their timing and any issues.",
-    inputSchema: object({ shot: SHOT_ID, commands: { type: "array", items: MOTION_COMMAND_SCHEMA, minItems: 1, description: "Commands to add." }, at: { type: "integer", minimum: 0, description: "Index in the run (default: the end)." } }, ["shot", "commands"]),
+    inputSchema: object({ shot: SHOT_ID, commands: { type: "array", items: REF2("command"), minItems: 1, description: "Commands to add." }, at: { type: "integer", minimum: 0, description: "Index in the run (default: the end)." } }, ["shot", "commands"]),
     annotations: { title: "Add commands to a shot", ...WRITE },
     handler: ({ shot, commands, at }) => {
       const before = scene().shots.find((s) => s.id === shot)?.run.length ?? 0;
@@ -4757,7 +4881,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       {
         shot: SHOT_ID,
         command: { type: "integer", minimum: 0, description: "Index in the shot's run (from get_animation)." },
-        set: { type: "object", description: "Command fields to replace (see add_commands for each type's fields)." },
+        set: { type: "object", description: "Command fields to replace (describe_animation_command lists each type's fields)." },
         remove: { type: "array", items: { type: "string" }, description: 'Optional fields to clear (e.g. "delay").' }
       },
       ["shot", "command"]
@@ -4821,7 +4945,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     name: "write_animation",
     title: "Replace the animation's shots",
     description: "Replaces every shot (and optionally the settings and controls), keeping the artwork, as one undo step. For small changes prefer the per-operation tools. Returns the timing and issues.",
-    inputSchema: object({ shots: { type: "array", items: SHOT, description: "All shots, in order." }, ...SETTINGS, controls: { type: "array", items: CONTROL, description: "Colour controls." }, presets: { type: "array", items: PRESET, description: "Presets." } }, ["shots"]),
+    inputSchema: object({ shots: { type: "array", items: REF2("shot"), description: "All shots, in order." }, ...SETTINGS, controls: { type: "array", items: CONTROL, description: "Colour controls." }, presets: { type: "array", items: PRESET, description: "Presets." } }, ["shots"]),
     annotations: { title: "Replace the animation's shots", ...DESTRUCTIVE },
     handler: ({ shots, controls, presets, ...settings }) => {
       const current = scene();
@@ -4871,11 +4995,15 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getAnimation, getShot, findElements, getTextLayout, getMotionPath, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation];
-  const writes = [setArtworkSvg, importPptx, setDrivers, setClip, copyAnimation, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, moveCommand, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
+  const finish = (tools) => tools.map((tool) => ({ ...tool, inputSchema: withDefs(tool.inputSchema) }));
+  const reads = finish([getAnimation, getShot, describeCommand, findElements, getTextLayout, getMotionPath, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation]);
+  const writes = finish([setArtworkSvg, importPptx, setDrivers, setClip, copyAnimation, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, moveCommand, setSettings, setControls, editAnimation, writeAnimation, undo, redo]);
   return {
     id: options.id ?? "animation",
     namespace: options.namespace,
+    title: "Animation editor",
+    description: "Vector animation: artwork, shots, animation commands and their timing, Flair and Lottie import and export, PowerPoint import.",
+    skill: "pixerate-animation-editor",
     tools: () => readOnlyReason() ? reads : [...reads, ...writes],
     subscribe: (notify) => {
       let last = readOnlyReason();
@@ -4924,6 +5052,7 @@ Commands
 Working method
 1. 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; or import_flair_effect / import_pptx_animation to start from a Flair effect or a PowerPoint slide).
 2. Plan a few shots, each one idea. Add them with insert_shots (add_commands, update_command, move_command and delete_commands refine a shot), or edit_animation to make several edits as one step (dry_run first when unsure).
+- The write tools list each command field once, saying which types take it; describe_animation_command gives a type's exact fields before you write one you have not used.
 - In edit_animation, a later op can use what an earlier one made: "$0.indexes[0]" (the first command op 1 added), "$last.shot".
 3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + "end") to look at the result, or with "times" for a contact sheet of several moments; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.
 - For something the viewer plays (a button, a toggle, a step-by-step explainer), set "trigger" with set_animation_settings: click plays the next shot on each click and then starts over (make the last shot put things back for a toggle), hover or press plays and rewinds, scroll scrubs.
@@ -5245,6 +5374,9 @@ function createAnimationEffectsToolProvider(controller, options = {}) {
   return createEffectToolProvider({
     id: options.id ?? "animation-effects",
     namespace: options.namespace,
+    title: "Animation effects",
+    description: "Provider motion effects on nodes of the animation artwork.",
+    skill: "pixerate-animation-editor",
     target: { noun: "node", id: "A node id of the artwork from get_animation (a group animates as one)." },
     applyUses: ["motion"],
     applyDetails: "The provider animates the node and its changes become ordinary commands (enter, fade, move, pulse\u2026), in a new shot after the last one, tagged with the effect so it can be changed or removed as a whole. They preview, play and export to Flair like any command. Vector effects with their own picture go through add_vector_effect. index, enabled and opacity do not apply here.",
@@ -5318,8 +5450,10 @@ export {
   MOTION_CAMERA_MS,
   MOTION_CASCADES,
   MOTION_CLIP_TARGET,
+  MOTION_COMMAND_FIELDS,
   MOTION_COMMAND_SCHEMA,
   MOTION_COMMAND_TYPES,
+  MOTION_COMMAND_TYPE_SCHEMAS,
   MOTION_DEFAULT_DURATIONS,
   MOTION_DEFAULT_HOLD,
   MOTION_DIRECTIONS,

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

@@ -2,4 +2,4 @@
  * 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.
  */
-export 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- Text: convert it to outlines (a group with a path per letter) and give a command \"split\": \"letter\", \"word\" or \"line\" (and \"cascade\") to animate it a unit at a time; get_text_layout shows the units.\n- Drawing a group of strokes: \"order\": \"sequence\" draws them one after another (a signature, a diagram), \"sortBy\": \"distance\" from \"origin\" reveals outward, \"pace\": \"speed\" keeps one speed; draw with \"comet\": 0.2 sends a short stroke along a path and off the end.\n- Fast motion reads better with blur: set_animation_settings { \"motionBlur\": { \"shutter\": 180 } } (stage and rendered frames only).\n- Tie properties together with set_animation_drivers: parallax layers, a wheel that turns as it rolls, a shadow that fades as something rises. Drivers add to the target's own commands.\n- Reuse motion: set_animation_clip defines a clip (commands targeting \"$\"), and { \"type\": \"play\", \"clip\": name, \"targets\": [...] } plays it on any nodes (with stagger and speed). copy_animation gives other nodes one node's motion.\n- move takes \"via\" waypoints for a curved, smooth path that passes exactly through each point (steady speed by default); use it instead of chaining moves, which stop at each point.\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); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); 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- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- To time shots to music or a voiceover: set a \"beat\" grid or \"narration\" word timings with set_animation_settings, read them with get_timing_grid, and give a shot \"at\": { \"beat\": n } or { \"word\": i }. The shot before holds until the cue; check_animation warns when a cue is missed.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\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; or import_flair_effect / import_pptx_animation to start from a Flair effect or a PowerPoint slide).\n2. Plan a few shots, each one idea. Add them with insert_shots (add_commands, update_command, move_command and delete_commands refine a shot), or edit_animation to make several edits as one step (dry_run first when unsure).\n- In edit_animation, a later op can use what an earlier one made: \"$0.indexes[0]\" (the first command op 1 added), \"$last.shot\".\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result, or with \"times\" for a contact sheet of several moments; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.\n- For something the viewer plays (a button, a toggle, a step-by-step explainer), set \"trigger\" with set_animation_settings: click plays the next shot on each click and then starts over (make the last shot put things back for a toggle), hover or press plays and rewinds, scroll scrubs.\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 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- Text: convert it to outlines (a group with a path per letter) and give a command \"split\": \"letter\", \"word\" or \"line\" (and \"cascade\") to animate it a unit at a time; get_text_layout shows the units.\n- Drawing a group of strokes: \"order\": \"sequence\" draws them one after another (a signature, a diagram), \"sortBy\": \"distance\" from \"origin\" reveals outward, \"pace\": \"speed\" keeps one speed; draw with \"comet\": 0.2 sends a short stroke along a path and off the end.\n- Fast motion reads better with blur: set_animation_settings { \"motionBlur\": { \"shutter\": 180 } } (stage and rendered frames only).\n- Tie properties together with set_animation_drivers: parallax layers, a wheel that turns as it rolls, a shadow that fades as something rises. Drivers add to the target's own commands.\n- Reuse motion: set_animation_clip defines a clip (commands targeting \"$\"), and { \"type\": \"play\", \"clip\": name, \"targets\": [...] } plays it on any nodes (with stagger and speed). copy_animation gives other nodes one node's motion.\n- move takes \"via\" waypoints for a curved, smooth path that passes exactly through each point (steady speed by default); use it instead of chaining moves, which stop at each point.\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); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); 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- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- To time shots to music or a voiceover: set a \"beat\" grid or \"narration\" word timings with set_animation_settings, read them with get_timing_grid, and give a shot \"at\": { \"beat\": n } or { \"word\": i }. The shot before holds until the cue; check_animation warns when a cue is missed.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\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; or import_flair_effect / import_pptx_animation to start from a Flair effect or a PowerPoint slide).\n2. Plan a few shots, each one idea. Add them with insert_shots (add_commands, update_command, move_command and delete_commands refine a shot), or edit_animation to make several edits as one step (dry_run first when unsure).\n- The write tools list each command field once, saying which types take it; describe_animation_command gives a type's exact fields before you write one you have not used.\n- In edit_animation, a later op can use what an earlier one made: \"$0.indexes[0]\" (the first command op 1 added), \"$last.shot\".\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result, or with \"times\" for a contact sheet of several moments; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.\n- For something the viewer plays (a button, a toggle, a step-by-step explainer), set \"trigger\" with set_animation_settings: click plays the next shot on each click and then starts over (make the last shot put things back for a toggle), hover or press plays and rewinds, scroll scrubs.\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.";

package/dist/animation-editor/instructions.d.ts

@@ -2,4 +2,4 @@
  * 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.
  */
-export 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- Text: convert it to outlines (a group with a path per letter) and give a command \"split\": \"letter\", \"word\" or \"line\" (and \"cascade\") to animate it a unit at a time; get_text_layout shows the units.\n- Drawing a group of strokes: \"order\": \"sequence\" draws them one after another (a signature, a diagram), \"sortBy\": \"distance\" from \"origin\" reveals outward, \"pace\": \"speed\" keeps one speed; draw with \"comet\": 0.2 sends a short stroke along a path and off the end.\n- Fast motion reads better with blur: set_animation_settings { \"motionBlur\": { \"shutter\": 180 } } (stage and rendered frames only).\n- Tie properties together with set_animation_drivers: parallax layers, a wheel that turns as it rolls, a shadow that fades as something rises. Drivers add to the target's own commands.\n- Reuse motion: set_animation_clip defines a clip (commands targeting \"$\"), and { \"type\": \"play\", \"clip\": name, \"targets\": [...] } plays it on any nodes (with stagger and speed). copy_animation gives other nodes one node's motion.\n- move takes \"via\" waypoints for a curved, smooth path that passes exactly through each point (steady speed by default); use it instead of chaining moves, which stop at each point.\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); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); 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- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- To time shots to music or a voiceover: set a \"beat\" grid or \"narration\" word timings with set_animation_settings, read them with get_timing_grid, and give a shot \"at\": { \"beat\": n } or { \"word\": i }. The shot before holds until the cue; check_animation warns when a cue is missed.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\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; or import_flair_effect / import_pptx_animation to start from a Flair effect or a PowerPoint slide).\n2. Plan a few shots, each one idea. Add them with insert_shots (add_commands, update_command, move_command and delete_commands refine a shot), or edit_animation to make several edits as one step (dry_run first when unsure).\n- In edit_animation, a later op can use what an earlier one made: \"$0.indexes[0]\" (the first command op 1 added), \"$last.shot\".\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result, or with \"times\" for a contact sheet of several moments; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.\n- For something the viewer plays (a button, a toggle, a step-by-step explainer), set \"trigger\" with set_animation_settings: click plays the next shot on each click and then starts over (make the last shot put things back for a toggle), hover or press plays and rewinds, scroll scrubs.\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 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- Text: convert it to outlines (a group with a path per letter) and give a command \"split\": \"letter\", \"word\" or \"line\" (and \"cascade\") to animate it a unit at a time; get_text_layout shows the units.\n- Drawing a group of strokes: \"order\": \"sequence\" draws them one after another (a signature, a diagram), \"sortBy\": \"distance\" from \"origin\" reveals outward, \"pace\": \"speed\" keeps one speed; draw with \"comet\": 0.2 sends a short stroke along a path and off the end.\n- Fast motion reads better with blur: set_animation_settings { \"motionBlur\": { \"shutter\": 180 } } (stage and rendered frames only).\n- Tie properties together with set_animation_drivers: parallax layers, a wheel that turns as it rolls, a shadow that fades as something rises. Drivers add to the target's own commands.\n- Reuse motion: set_animation_clip defines a clip (commands targeting \"$\"), and { \"type\": \"play\", \"clip\": name, \"targets\": [...] } plays it on any nodes (with stagger and speed). copy_animation gives other nodes one node's motion.\n- move takes \"via\" waypoints for a curved, smooth path that passes exactly through each point (steady speed by default); use it instead of chaining moves, which stop at each point.\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); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); 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- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- To time shots to music or a voiceover: set a \"beat\" grid or \"narration\" word timings with set_animation_settings, read them with get_timing_grid, and give a shot \"at\": { \"beat\": n } or { \"word\": i }. The shot before holds until the cue; check_animation warns when a cue is missed.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\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; or import_flair_effect / import_pptx_animation to start from a Flair effect or a PowerPoint slide).\n2. Plan a few shots, each one idea. Add them with insert_shots (add_commands, update_command, move_command and delete_commands refine a shot), or edit_animation to make several edits as one step (dry_run first when unsure).\n- The write tools list each command field once, saying which types take it; describe_animation_command gives a type's exact fields before you write one you have not used.\n- In edit_animation, a later op can use what an earlier one made: \"$0.indexes[0]\" (the first command op 1 added), \"$last.shot\".\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result, or with \"times\" for a contact sheet of several moments; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.\n- For something the viewer plays (a button, a toggle, a step-by-step explainer), set \"trigger\" with set_animation_settings: click plays the next shot on each click and then starts over (make the last shot put things back for a toggle), hover or press plays and rewinds, scroll scrubs.\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.";

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

@@ -1,4 +1,4 @@
-import { type MotionCommand, type MotionScene, type MotionShot } from './types.cjs';
+import { type MotionCommand, type MotionCommandType, type MotionScene, type MotionShot } from './types.cjs';
 /**
  * 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.
@@ -7,6 +7,8 @@ export declare class MotionSceneFormatError extends Error {
     readonly problems: string[];
     constructor(problems: string[]);
 }
+/** The fields each command type takes (`source` is set by applied effects, not written by hand). */
+export declare const MOTION_COMMAND_FIELDS: Readonly<Record<MotionCommandType, readonly string[]>>;
 /** Problems with one command's shape (empty when well formed). `where` prefixes each. */
 export declare function commandShapeProblems(command: unknown, where: string): string[];
 /** Problems with a scene's `clips`: names, and each clip's commands (which may target `"$"` but not play clips). */

package/dist/animation-editor/parse.d.ts

@@ -1,4 +1,4 @@
-import { type MotionCommand, type MotionScene, type MotionShot } from './types.js';
+import { type MotionCommand, type MotionCommandType, type MotionScene, type MotionShot } from './types.js';
 /**
  * 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.
@@ -7,6 +7,8 @@ export declare class MotionSceneFormatError extends Error {
     readonly problems: string[];
     constructor(problems: string[]);
 }
+/** The fields each command type takes (`source` is set by applied effects, not written by hand). */
+export declare const MOTION_COMMAND_FIELDS: Readonly<Record<MotionCommandType, readonly string[]>>;
 /** Problems with one command's shape (empty when well formed). `where` prefixes each. */
 export declare function commandShapeProblems(command: unknown, where: string): string[];
 /** Problems with a scene's `clips`: names, and each clip's commands (which may target `"$"` but not play clips). */