@pixerate/editor 0.57.0 → 0.58.0

package/dist/animation-editor/index.js

@@ -17,7 +17,7 @@ import {
   vectorDocumentToSvg,
   vectorNodeBounds,
   vectorPathWorldBezier
-} from "../chunk-NONDTTH7.js";
+} from "../chunk-PYMV7HLI.js";
 import {
   bezierPathLength,
   bezierPathPointAtLength,
@@ -27,6 +27,10 @@ import {
 import {
   HistoryManager
 } from "../chunk-QVZZGT4X.js";
+import {
+  behaviorProgress,
+  motionSeedFromId
+} from "../chunk-3NYXDBBW.js";
 import {
   AnimationPlayer
 } from "../chunk-SHOVAHUB.js";
@@ -59,11 +63,17 @@ var MOTION_COMMAND_TYPES = [
   "follow",
   "pulse",
   "shake",
+  "teeter",
+  "wave",
+  "wiggle",
+  "color-pulse",
   "effect",
   "wait"
 ];
-var MOTION_ENTER_STYLES = ["fade", "pop", "grow", "slide", "draw"];
-var MOTION_EXIT_STYLES = ["fade", "shrink", "slide", "undraw"];
+var MOTION_ENTER_STYLES = ["fade", "pop", "grow", "slide", "draw", "zoom", "rise", "wipe", "iris", "split"];
+var MOTION_EXIT_STYLES = ["fade", "shrink", "slide", "undraw", "wipe"];
+var MOTION_IRIS_SHAPES = ["circle", "box"];
+var MOTION_SPLIT_ORIENTATIONS = ["horizontal", "vertical"];
 var MOTION_DIRECTIONS = ["up", "down", "left", "right"];
 var MOTION_DEFAULT_DURATIONS = {
   enter: 600,
@@ -77,12 +87,37 @@ var MOTION_DEFAULT_DURATIONS = {
   follow: 1400,
   pulse: 600,
   shake: 500,
+  teeter: 600,
+  wave: 1e3,
+  wiggle: 1500,
+  "color-pulse": 600,
   effect: 900
 };
 var MOTION_DEFAULT_HOLD = 600;
 var MOTION_CAMERA_MS = 1e3;
 var MOTION_DRAW_MS_PER_UNIT = 1.5;
 var MOTION_DRAW_RANGE = [500, 2500];
+function motionFlairPrimitive(command2) {
+  switch (command2.type) {
+    case "enter":
+      return `entrance.${command2.style ?? "fade"}`;
+    case "exit":
+      return `exit.${command2.style ?? "fade"}`;
+    case "pulse":
+    case "shake":
+    case "teeter":
+    case "wave":
+    case "wiggle":
+    case "color-pulse":
+      return `emphasis.${command2.type}`;
+    case "rotate":
+      return command2.by !== void 0 ? "emphasis.spin" : void 0;
+    case "follow":
+      return "path.follow";
+    default:
+      return void 0;
+  }
+}
 
 // src/animation-editor/issues.ts
 var MOTION_ISSUE_CODES = {
@@ -91,13 +126,14 @@ var MOTION_ISSUE_CODES = {
   "unknown-target": { severity: "error", wording: "A command names a node the artwork does not have." },
   "unknown-path": { severity: "error", wording: "A follow command names a path the artwork does not have." },
   "not-a-path": { severity: "error", wording: "A follow path must be a path node, not a group." },
+  "reveal-no-box": { severity: "warning", wording: "A wipe, iris or split cannot clip a node with no width or height (a lone straight line), so it fades instead." },
   "unknown-shape": { severity: "error", wording: "A morph names a shape the artwork does not have." },
   "unknown-effect": { severity: "error", wording: "An effect command names an effect the node does not have." },
   "unknown-effect-param": { severity: "error", wording: "An effect command names a parameter that is not a number of that effect." },
   "unknown-frame": { severity: "error", wording: "A camera frames a node the artwork does not have." },
   "invalid-camera": { severity: "error", wording: "A camera rectangle has no area." },
   "invalid-color": { severity: "error", wording: "A colour cannot be read." },
-  "paint-not-color": { severity: "warning", wording: "A style command recolours a gradient or empty paint, which only switches at the end." },
+  "paint-not-color": { severity: "warning", 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." },
   "overlap": { severity: "warning", wording: "Two commands change the same property of a node at the same time; the later one wins." },
   "enter-visible": { severity: "warning", wording: "A node enters while it is already showing, so it blinks out first." },
   "exit-hidden": { severity: "warning", wording: "A node exits or animates while it is hidden." },
@@ -165,7 +201,7 @@ var SHOT_KEYS = ["id", "label", "camera", "run", "hold"];
 var CAMERA_KEYS = ["x", "y", "width", "height", "frame", "padding", "ease", "ms"];
 var BASE_KEYS = ["type", "targets", "duration", "delay", "stagger", "with", "ease", "note"];
 var COMMAND_KEYS = {
-  enter: [...BASE_KEYS, "style", "direction", "distance"],
+  enter: [...BASE_KEYS, "style", "direction", "distance", "scale", "shape", "orientation"],
   exit: [...BASE_KEYS, "style", "direction", "distance"],
   draw: [...BASE_KEYS, "from", "to"],
   move: [...BASE_KEYS, "by", "to"],
@@ -176,7 +212,11 @@ var COMMAND_KEYS = {
   morph: [...BASE_KEYS, "into"],
   follow: [...BASE_KEYS, "path", "rotate", "from", "to"],
   pulse: [...BASE_KEYS, "amount", "count"],
-  shake: [...BASE_KEYS, "amount", "count"],
+  shake: [...BASE_KEYS, "amount", "count", "axis"],
+  teeter: [...BASE_KEYS, "angle", "count"],
+  wave: [...BASE_KEYS, "amount", "count"],
+  wiggle: [...BASE_KEYS, "amount", "frequency", "octaves", "rotate", "seed"],
+  "color-pulse": [...BASE_KEYS, "color", "paint", "count"],
   effect: [...BASE_KEYS, "effect", "param", "to"],
   wait: ["type", "duration", "with", "note"]
 };
@@ -223,6 +263,9 @@ function commandShapeProblems(command2, where) {
         p(`"style" must be one of ${styles.join(", ")}${typeof command2.style === "string" ? ` (got ${namedWithSuggestion(command2.style, styles)})` : ""}.`);
       if (command2.direction !== void 0 && !MOTION_DIRECTIONS.includes(command2.direction)) p(`"direction" must be one of ${MOTION_DIRECTIONS.join(", ")}.`);
       optionalNumber("distance");
+      if (command2.scale !== void 0 && !(isNum(command2.scale) && command2.scale >= 0)) p(`"scale" must be a number \u2265 0 (the starting scale for pop and zoom).`);
+      if (command2.shape !== void 0 && !MOTION_IRIS_SHAPES.includes(command2.shape)) p(`"shape" must be one of ${MOTION_IRIS_SHAPES.join(", ")} (the opening of an iris).`);
+      if (command2.orientation !== void 0 && !MOTION_SPLIT_ORIENTATIONS.includes(command2.orientation)) p(`"orientation" must be one of ${MOTION_SPLIT_ORIENTATIONS.join(", ")} (the line a split opens from).`);
       break;
     }
     case "draw":
@@ -264,8 +307,22 @@ function commandShapeProblems(command2, where) {
       break;
     case "pulse":
     case "shake":
+    case "teeter":
+    case "wave":
+    case "color-pulse":
       optionalNumber("amount");
+      optionalNumber("angle");
       if (command2.count !== void 0 && !(Number.isInteger(command2.count) && command2.count >= 1)) p(`"count" must be a whole number \u2265 1.`);
+      if (command2.axis !== void 0 && command2.axis !== "horizontal" && command2.axis !== "vertical") p(`"axis" must be "horizontal" or "vertical".`);
+      if (command2.color !== void 0 && typeof command2.color !== "string") p(`"color" must be a CSS colour.`);
+      if (command2.paint !== void 0 && command2.paint !== "fill" && command2.paint !== "stroke") p(`"paint" must be "fill" or "stroke".`);
+      break;
+    case "wiggle":
+      optionalNumber("amount");
+      optionalNumber("rotate");
+      if (command2.frequency !== void 0 && !(isNum(command2.frequency) && command2.frequency > 0)) p(`"frequency" must be a number of Hz > 0.`);
+      if (command2.octaves !== void 0 && !(Number.isInteger(command2.octaves) && command2.octaves >= 1 && command2.octaves <= 8)) p(`"octaves" must be a whole number from 1 to 8.`);
+      if (command2.seed !== void 0 && !(Number.isInteger(command2.seed) && command2.seed >= 0)) p(`"seed" must be a whole number \u2265 0.`);
       break;
     case "effect":
       if (typeof command2.effect !== "string" || !command2.effect) p(`"effect" must be the id of one of the node's effects.`);
@@ -358,7 +415,7 @@ function indexMotionNodes(nodes) {
       const local = vectorNodeBounds(node);
       const bounds = vectorNodeBounds(node, parentWorld);
       const center = local ? { x: local.x + local.width / 2, y: local.y + local.height / 2 } : { x: 0, y: 0 };
-      if (!out.has(node.id)) out.set(node.id, { node, ancestors, parentWorld, center, bounds });
+      if (!out.has(node.id)) out.set(node.id, { node, ancestors, parentWorld, center, bounds, box: local });
       if (node.type === "group") walk(node.children, multiplyMatrices(nodeMatrix(node), parentWorld), [...ancestors, node.id]);
     }
   };
@@ -375,6 +432,56 @@ function firstPaint(node, key) {
   }
   return void 0;
 }
+function strokeReach(node) {
+  let reach = 0;
+  for (const p of node.type === "path" ? [node] : collectPathNodes(node)) {
+    if (p.stroke == null || p.stroke === "none") continue;
+    const width = p.strokeWidth ?? 1;
+    reach = Math.max(reach, p.strokeAlign === "outside" ? width : p.strokeAlign === "inside" ? 0 : width / 2);
+  }
+  return reach;
+}
+function motionRevealPadding(entry) {
+  const box = entry.box;
+  if (!box || !(box.width > 0) || !(box.height > 0)) return null;
+  const s = strokeReach(entry.node);
+  return [Math.min(1, s / box.width + 0.02), Math.min(1, s / box.height + 0.02)];
+}
+var clipRound = (n) => Math.round(n * 1e4) / 1e4 || 0;
+function revealFull(property, [px, py]) {
+  return (property === "clipRect" ? [-px, -py, 1 + 2 * px, 1 + 2 * py] : [0.5, 0.5, Math.hypot(0.5 + px, 0.5 + py)]).map(clipRound);
+}
+var OPPOSITE = { up: "down", down: "up", left: "right", right: "left" };
+function motionRevealClip(entry, reveal) {
+  const pad = motionRevealPadding(entry);
+  if (!pad) return null;
+  const [px, py] = pad;
+  const [w, h] = [1 + 2 * px, 1 + 2 * py];
+  const rect = (from, to) => ({ property: "clipRect", from: from.map(clipRound), to: to.map(clipRound) });
+  if (reveal.style === "iris") {
+    if (reveal.shape === "box") return rect([0.5, 0.5, 0, 0], [-px, -py, w, h]);
+    return { property: "clipCircle", from: [0.5, 0.5, 0], to: revealFull("clipCircle", pad) };
+  }
+  if (reveal.style === "split") {
+    if (reveal.orientation === "vertical") return rect([0.5, -py, 0, h], [-px, -py, w, h]);
+    return rect([-px, 0.5, w, 0], [-px, -py, w, h]);
+  }
+  const direction = reveal.direction ?? "right";
+  if (reveal.hide) {
+    const shown = motionRevealClip(entry, { style: "wipe", direction: OPPOSITE[direction] });
+    return { ...shown, from: shown.to, to: shown.from };
+  }
+  switch (direction) {
+    case "right":
+      return rect([-px, -py, 0, h], [-px, -py, w, h]);
+    case "left":
+      return rect([1 + px, -py, 0, h], [-px, -py, w, h]);
+    case "down":
+      return rect([-px, -py, w, 0], [-px, -py, w, h]);
+    case "up":
+      return rect([-px, 1 + py, w, 0], [-px, -py, w, h]);
+  }
+}
 function motionRestValue(entry, property, artwork) {
   const node = entry?.node;
   switch (property) {
@@ -402,6 +509,11 @@ function motionRestValue(entry, property, artwork) {
     }
     case "shape":
       return node?.id ?? "";
+    case "clipRect":
+    case "clipCircle": {
+      const pad = entry && motionRevealPadding(entry);
+      return pad ? revealFull(property, pad) : [];
+    }
     case "camera":
       return [0, 0, artwork.width, artwork.height];
   }
@@ -424,15 +536,13 @@ function interpolateMotionValue(from, to, u) {
 function segmentProgress(segment, time) {
   const span = segment.end - segment.start;
   const u = span <= 0 ? 1 : Math.min(1, Math.max(0, (time - segment.start) / span));
-  return { u, eased: segment.wave ? u : evaluateEasing(segment.ease, u, span) };
+  return { u, eased: evaluateEasing(segment.ease, u, span) };
 }
-function segmentValue(segment, time) {
-  const { u, eased } = segmentProgress(segment, time);
-  const v = interpolateMotionValue(segment.from, segment.to, eased);
-  if (!segment.wave || typeof v !== "number") return v;
-  const { kind, amount, count } = segment.wave;
-  if (kind === "pulse") return v * (1 + amount * Math.sin(Math.PI * u * count) ** 2);
-  return v + amount * Math.sin(2 * Math.PI * u * count) * (1 - u);
+function segmentValue(segment, time, raw = false) {
+  const { eased } = segmentProgress(segment, time);
+  if (!segment.behavior || raw) return interpolateMotionValue(segment.from, segment.to, eased);
+  const p = behaviorProgress(segment.behavior, eased, segment.index ?? 0, segment.end - segment.start);
+  return typeof segment.from === "string" ? interpolateMotionValue(segment.from, segment.to, Math.min(1, Math.max(0, p))) : interpolateMotionValue(segment.from, segment.to, p);
 }
 function activeSegment(track, time) {
   if (!track?.length) return void 0;
@@ -440,10 +550,10 @@ function activeSegment(track, time) {
   for (const s of track) if (s.start <= time && (!found || s.start >= found.start)) found = s;
   return found;
 }
-function trackValue(track, time) {
+function trackValue(track, time, raw = false) {
   if (!track?.length) return void 0;
   const s = activeSegment(track, time);
-  if (s) return segmentValue(s, time);
+  if (s) return segmentValue(s, time, raw);
   let first = track[0];
   for (const t of track) if (t.start < first.start) first = t;
   return first.from;
@@ -582,15 +692,27 @@ function compileMotionScene(scene) {
       case "enter": {
         const style = command2.style ?? "fade";
         const opacity = rest("opacity");
+        const reveal = style === "wipe" ? motionRevealClip(entry, { style, direction: command2.direction }) : style === "iris" ? motionRevealClip(entry, { style, shape: command2.shape }) : style === "split" ? motionRevealClip(entry, { style, orientation: command2.orientation }) : null;
+        for (const p of ["clipRect", "clipCircle"]) if (p !== reveal?.property && tracks.has(motionTrackKey(node, p))) seg(p, rest(p), "linear", start, start);
+        if (reveal) {
+          seg("opacity", opacity, "linear", start, start);
+          seg(reveal.property, reveal.to, ease ?? MOTION_EASE_OUT, start, end, { from: reveal.from });
+          break;
+        }
         if (style === "draw") {
           seg("drawEnd", 1, ease ?? MOTION_EASE_IN_OUT, start, start + duration2 * 0.75, { from: 0 });
           seg("fillOpacity", 1, MOTION_EASE_OUT, start + duration2 * 0.6, end, { from: 0 });
           break;
         }
-        if (style === "pop") {
-          seg("opacity", opacity, MOTION_EASE_OUT, start, start + duration2 * 0.4, { from: 0 });
-          seg("scaleX", 1, ease ?? "ease-out-back", start, end, { from: 0.5 });
-          seg("scaleY", 1, ease ?? "ease-out-back", start, end, { from: 0.5 });
+        if (style === "pop" || style === "zoom") {
+          const from = command2.scale ?? (style === "pop" ? 0.5 : 1.6);
+          seg("opacity", opacity, MOTION_EASE_OUT, start, start + duration2 * (style === "pop" ? 0.4 : 0.5), { from: 0 });
+          seg("scaleX", 1, ease ?? (style === "pop" ? "ease-out-back" : MOTION_EASE_OUT), start, end, { from });
+          seg("scaleY", 1, ease ?? (style === "pop" ? "ease-out-back" : MOTION_EASE_OUT), start, end, { from });
+        } else if (style === "rise") {
+          const y = num("y");
+          seg("opacity", opacity, MOTION_EASE_OUT, start, start + duration2 * 0.5, { from: 0 });
+          seg("y", y, ease ?? "ease-out-back", start, end, { from: y + (command2.distance ?? 20) });
         } else if (style === "grow") {
           seg("opacity", opacity, MOTION_EASE_OUT, start, start + duration2 * 0.3, { from: 0 });
           seg("scaleX", 1, ease ?? MOTION_EASE_OUT, start, end, { from: 0 });
@@ -608,7 +730,9 @@ function compileMotionScene(scene) {
       }
       case "exit": {
         const style = command2.style ?? "fade";
-        if (style === "undraw") {
+        const wipe = style === "wipe" ? motionRevealClip(entry, { style, direction: command2.direction, hide: true }) : null;
+        if (wipe) seg(wipe.property, wipe.to, ease ?? "ease-in", start, end, { from: wipe.from });
+        else if (style === "undraw") {
           seg("fillOpacity", 0, "ease-in", start, start + duration2 * 0.4);
           seg("drawEnd", 0, ease ?? MOTION_EASE_IN_OUT);
         } else if (style === "shrink") {
@@ -624,13 +748,11 @@ function compileMotionScene(scene) {
         } else seg("opacity", 0, ease ?? "ease-in");
         break;
       }
-      case "draw":
-        {
-          const drawn = tracks.has(motionTrackKey(node, "drawEnd"));
-          seg("drawEnd", command2.to ?? 1, ease ?? MOTION_EASE_IN_OUT, start, end, command2.from !== void 0 ? { from: command2.from } : drawn ? {} : { from: 0 });
-          break;
-        }
+      case "draw": {
+        const drawn = tracks.has(motionTrackKey(node, "drawEnd"));
+        seg("drawEnd", command2.to ?? 1, ease ?? MOTION_EASE_IN_OUT, start, end, command2.from !== void 0 ? { from: command2.from } : drawn ? {} : { from: 0 });
         break;
+      }
       case "move": {
         const e = ease ?? MOTION_EASE_IN_OUT;
         let dx = command2.by?.x ?? 0;
@@ -668,14 +790,35 @@ function compileMotionScene(scene) {
       case "follow":
         seg("follow", command2.to ?? 1, ease ?? MOTION_EASE_IN_OUT, start, end, { from: command2.from ?? 0, path: command2.path, rotate: command2.rotate ?? false });
         break;
+      // Emphasis: a change toward a peak that a behaviour swings round (as Flair's primitives do).
       case "pulse": {
-        const wave = { kind: "pulse", amount: command2.amount ?? 0.15, count: command2.count ?? 1 };
-        seg("scaleX", num("scaleX"), "linear", start, end, { wave });
-        seg("scaleY", num("scaleY"), "linear", start, end, { wave });
+        const behavior = { type: "pulse", count: command2.count ?? 1 };
+        const k = 1 + (command2.amount ?? 0.15);
+        seg("scaleX", num("scaleX") * k, ease ?? "linear", start, end, { behavior });
+        seg("scaleY", num("scaleY") * k, ease ?? "linear", start, end, { behavior });
         break;
       }
-      case "shake":
-        seg("x", num("x"), "linear", start, end, { wave: { kind: "shake", amount: command2.amount ?? 8, count: command2.count ?? 3 } });
+      case "shake": {
+        const p = command2.axis === "vertical" ? "y" : "x";
+        seg(p, num(p) + (command2.amount ?? 8), ease ?? "linear", start, end, { behavior: { type: "oscillate", count: command2.count ?? 3, decay: 1 } });
+        break;
+      }
+      case "teeter":
+        seg("rotation", num("rotation") + (command2.angle ?? 8), ease ?? "linear", start, end, { behavior: { type: "oscillate", count: command2.count ?? 3, decay: 1 } });
+        break;
+      case "wave":
+        seg("y", num("y") - (command2.amount ?? 6), ease ?? "linear", start, end, { behavior: { type: "oscillate", count: command2.count ?? 2 } });
+        break;
+      case "wiggle": {
+        const behavior = { type: "wriggle", frequency: command2.frequency ?? 3, octaves: command2.octaves ?? 2, seed: command2.seed || motionSeedFromId(node) };
+        const amount = command2.amount ?? 6;
+        seg("x", num("x") + amount, ease ?? "linear", start, end, { behavior, index: 0 });
+        seg("y", num("y") + amount, ease ?? "linear", start, end, { behavior, index: 1 });
+        if (command2.rotate) seg("rotation", num("rotation") + command2.rotate, ease ?? "linear", start, end, { behavior, index: 2 });
+        break;
+      }
+      case "color-pulse":
+        seg(command2.paint ?? "fill", command2.color ?? "#f59e0b", ease ?? "linear", start, end, { behavior: { type: "pulse", count: command2.count ?? 1 } });
         break;
       case "effect":
         seg(`effect:${command2.effect}:${command2.param}`, command2.to, ease ?? MOTION_EASE_IN_OUT);
@@ -757,44 +900,53 @@ function shapeAt(entry, timeline, nodes, time) {
   if (u >= 1) return b === entry ? null : shapeIn(entry, b);
   return morphBetween(shapeIn(entry, a), shapeIn(entry, b)).at(u);
 }
+function motionFollowRoute(entry, path) {
+  if (!path || path.node.type !== "path") return null;
+  try {
+    return transformBezierPath(vectorPathWorldBezier(path.node, path.parentWorld, { effects: false }), invertMatrix(entry.parentWorld));
+  } catch {
+    return null;
+  }
+}
 function followAt(entry, timeline, nodes, time) {
   const track = timeline.tracks.get(motionTrackKey(entry.node.id, "follow"));
   const s = activeSegment(track, time) ?? track?.[0];
   if (!s?.path) return null;
-  const path = nodes.get(s.path);
-  if (!path || path.node.type !== "path") return null;
+  const route = motionFollowRoute(entry, nodes.get(s.path));
   const progress = Number(trackValue(track, time));
-  if (!(progress >= 0)) return null;
+  if (!route || !(progress >= 0)) return null;
   try {
-    const bezier = vectorPathWorldBezier(path.node, path.parentWorld, { effects: false });
-    const at = bezierPathPointAtLength(bezier, Math.min(1, Math.max(0, progress)) * bezierPathLength(bezier));
+    const at = bezierPathPointAtLength(route, Math.min(1, Math.max(0, progress)) * bezierPathLength(route));
     if (!at) return null;
-    const p = applyMatrix(invertMatrix(entry.parentWorld), { x: at.point[0], y: at.point[1] });
-    return { x: p.x, y: p.y, angle: s.rotate ? at.angle * 180 / Math.PI : 0 };
+    return { x: at.point[0], y: at.point[1], angle: s.rotate ? at.angle * 180 / Math.PI : 0 };
   } catch {
     return null;
   }
 }
-function motionNodeOffset(entry, timeline, time, nodes = indexMotionNodes([entry.node])) {
+function motionNodeOffset(entry, timeline, time, nodes = indexMotionNodes([entry.node]), raw = false, follow = true) {
   const read = (p, rest) => {
-    const v = trackValue(timeline.tracks.get(motionTrackKey(entry.node.id, p)), time);
+    const v = trackValue(timeline.tracks.get(motionTrackKey(entry.node.id, p)), time, raw);
     return typeof v === "number" ? v : rest;
   };
-  if (!TRANSFORM_PROPS.some((p) => timeline.tracks.has(motionTrackKey(entry.node.id, p)))) return null;
-  let dx = read("x", 0);
-  let dy = read("y", 0);
-  let rotation = read("rotation", 0);
+  if (!TRANSFORM_PROPS.some((p) => (follow || p !== "follow") && timeline.tracks.has(motionTrackKey(entry.node.id, p)))) return null;
+  const dx = read("x", 0);
+  const dy = read("y", 0);
+  const rotation = read("rotation", 0);
   const scaleX = read("scaleX", 1);
   const scaleY = read("scaleY", 1);
-  const follow = followAt(entry, timeline, nodes, time);
-  if (follow) {
-    dx += follow.x - entry.center.x;
-    dy += follow.y - entry.center.y;
-    rotation += follow.angle;
-  }
   const c = entry.center;
-  const matrix = multiplyMatrices(multiplyMatrices(scaleMatrix(scaleX, scaleY, c), rotateMatrix(rotation, c)), translateMatrix(dx, dy));
-  return { matrix, dx, dy, rotation, scaleX, scaleY };
+  let matrix = multiplyMatrices(multiplyMatrices(scaleMatrix(scaleX, scaleY, c), rotateMatrix(rotation, c)), translateMatrix(dx, dy));
+  const along = follow ? followAt(entry, timeline, nodes, time) : null;
+  if (along) matrix = multiplyMatrices(matrix, multiplyMatrices(multiplyMatrices(translateMatrix(-c.x, -c.y), rotateMatrix(along.angle)), translateMatrix(along.x, along.y)));
+  return { matrix, dx, dy, rotation, scaleX, scaleY, follow: along };
+}
+function motionNodeClips(id, timeline, time) {
+  const out = [];
+  const rect = trackValue(timeline.tracks.get(motionTrackKey(id, "clipRect")), time);
+  if (Array.isArray(rect) && rect.length === 4) out.push({ shape: "rect", x: tidy(rect[0]), y: tidy(rect[1]), width: Math.max(0, tidy(rect[2])), height: Math.max(0, tidy(rect[3])) });
+  const circle = trackValue(timeline.tracks.get(motionTrackKey(id, "clipCircle")), time);
+  if (Array.isArray(circle) && circle.length === 3) out.push({ shape: "circle", cx: tidy(circle[0]), cy: tidy(circle[1]), r: Math.max(0, tidy(circle[2])) });
+  return out;
 }
 function motionFrameAt(scene, time, options = {}) {
   const s = applyMotionControlValues(scene, options.values);
@@ -803,12 +955,15 @@ function motionFrameAt(scene, time, options = {}) {
   const drawOn = options.draw !== false;
   const value = (id, p) => trackValue(timeline.tracks.get(motionTrackKey(id, p)), time);
   const animated = new Set(timeline.segments.map((seg) => seg.node));
+  const clips = {};
   const visit = (node) => {
     let out = node.type === "group" ? { ...node, children: node.children.map(visit) } : node;
     if (!animated.has(node.id)) return out;
     const entry = nodes.get(node.id);
     if (!entry) return out;
     const id = node.id;
+    const clip = motionNodeClips(id, timeline, time);
+    if (clip.length) clips[id] = clip;
     const shape = shapeAt(entry, timeline, nodes, time);
     if (shape) {
       const { name, visible, opacity: opacity2, locked } = node;
@@ -872,11 +1027,19 @@ function motionFrameAt(scene, time, options = {}) {
   const document = { ...s.artwork, nodes: s.artwork.nodes.map(visit) };
   const cam = trackValue(timeline.tracks.get(motionTrackKey("", "camera")), time);
   const box = Array.isArray(cam) ? cam : [0, 0, s.artwork.width, s.artwork.height];
-  return { time, document, camera: { x: tidy(box[0]), y: tidy(box[1]), width: tidy(box[2]), height: tidy(box[3]) } };
+  return { time, document, camera: { x: tidy(box[0]), y: tidy(box[1]), width: tidy(box[2]), height: tidy(box[3]) }, clips };
+}
+function motionClipAttrs(clip) {
+  const { shape: _shape, ...attrs } = clip;
+  return attrs;
 }
 function motionFrameToSvg(scene, time, options = {}) {
   const frame = motionFrameAt(scene, time, options);
-  return withViewBox(vectorDocumentToSvg(frame.document, options), frame.camera);
+  const prefix = options.idPrefix ?? "vg-";
+  const wrap = { ...options.wrap };
+  for (const [id, clips] of Object.entries(frame.clips))
+    wrap[id] = [...wrap[id] ?? [], ...clips.map((clip, i) => ({ clip: { id: `${prefix}reveal-${id}-${i}`, shape: clip.shape, attrs: motionClipAttrs(clip) } }))];
+  return withViewBox(vectorDocumentToSvg(frame.document, { ...options, wrap }), frame.camera);
 }
 function withViewBox(svg, box) {
   const f = (n) => String(Math.round(n * 1e3) / 1e3);
@@ -911,6 +1074,11 @@ function visibleAt(timeline, id, time, node) {
   if (node.visible === false) return false;
   if (num("opacity", node.opacity ?? 1) <= 0.01) return false;
   if (Math.abs(num("scaleX", 1) * num("scaleY", 1)) <= 1e-4) return false;
+  const clip = (p) => trackValue(timeline.tracks.get(motionTrackKey(id, p)), time);
+  const rect = clip("clipRect");
+  if (Array.isArray(rect) && (rect[2] <= 1e-4 || rect[3] <= 1e-4)) return false;
+  const circle = clip("clipCircle");
+  if (Array.isArray(circle) && circle[2] <= 1e-4) return false;
   const hasFill = node.type === "path" ? !!node.fill && node.fill !== "none" : collectPathNodes(node).some((p) => p.fill && p.fill !== "none");
   return num("drawEnd", 1) > 0.01 || hasFill && num("fillOpacity", 1) > 0.01;
 }
@@ -950,6 +1118,12 @@ function checkMotionScene(scene) {
       if (command2.type === "follow" && known(command2.path, "unknown-path", "path", where) && nodes.get(command2.path).node.type !== "path")
         issues.push(motionIssue("not-a-path", `"${command2.path}" is a group; follow a single path node.`, { ...where, ids: [command2.path] }));
       if (command2.type === "morph") known(command2.into, "unknown-shape", "shape", where);
+      const style = command2.type === "enter" || command2.type === "exit" ? command2.style : void 0;
+      if (style === "wipe" || style === "iris" || style === "split") {
+        for (const id of targets)
+          if (!motionRevealPadding(nodes.get(id)))
+            issues.push(motionIssue("reveal-no-box", `"${id}" has no width or height (a straight line), so a ${style} cannot clip it and it fades instead; use style "${command2.type === "enter" ? "draw" : "undraw"}" for a line.`, { ...where, ids: [id] }));
+      }
       if (command2.type === "style") {
         for (const key of ["fill", "stroke"]) {
           const color = command2[key];
@@ -966,6 +1140,18 @@ function checkMotionScene(scene) {
           }
         }
       }
+      if (command2.type === "color-pulse") {
+        const key = command2.paint ?? "fill";
+        const color = command2.color ?? "#f59e0b";
+        if (normalizeTokenColor(color) === null) issues.push(motionIssue("invalid-color", `color "${color}" is not a colour this editor reads; use hex ("#0ea5e9"), rgb() or rgba().`, where));
+        else
+          for (const id of targets) {
+            const node = nodes.get(id).node;
+            const paths = node.type === "path" ? [node] : collectPathNodes(node);
+            if (paths.some((p) => typeof p[key] !== "string"))
+              issues.push(motionIssue("paint-not-color", `"${id}" has a gradient or no ${key}, so a colour pulse cannot tint it; give it a solid ${key} or pulse the ${key === "fill" ? "stroke" : "fill"}.`, { ...where, ids: [id] }));
+          }
+      }
       if (command2.type === "effect") {
         for (const id of targets) {
           const node = nodes.get(id).node;
@@ -1250,6 +1436,8 @@ function toFlairSvgMotion(scene, options = {}) {
   const fps = options.fps ?? scene.fps ?? 30;
   const precision = options.precision ?? 3;
   const curves = options.curves ?? true;
+  const behaviors = options.behaviors ?? true;
+  const plays = (s) => !s.behavior || behaviors;
   const round2 = (n) => Math.round(n * 10 ** precision) / 10 ** precision;
   const f = (n) => String(round2(n));
   const timeline = compileMotionScene(scene);
@@ -1264,26 +1452,72 @@ function toFlairSvgMotion(scene, options = {}) {
   };
   const animatedNodes = new Set(timeline.segments.map((s) => s.node).filter(Boolean));
   const pathsSeen = /* @__PURE__ */ new Set();
+  const wrap = {};
+  const routes = [];
+  const follows = [];
+  const usedIds = new Set(nodes.keys());
+  const freshId = (base) => {
+    let id = base;
+    for (let n = 2; usedIds.has(id); n++) id = `${base}-${n}`;
+    usedIds.add(id);
+    return id;
+  };
   for (const id of animatedNodes) {
     const entry = nodes.get(id);
     const node = entry.node;
+    const drawn = [...entry.ancestors.map((a) => nodes.get(a).node), node].every((n) => n.visible !== false);
+    for (const [p, name] of [["clipRect", "reveal"], ["clipCircle", "iris"]]) {
+      if (!drawn || !timeline.tracks.has(motionTrackKey(id, p))) continue;
+      const wrapper = freshId(`${id}--${name}`);
+      const clipId = freshId(`${wrapper}-clip`);
+      const shapeId = freshId(`${wrapper}-clip-shape`);
+      const clipAt = (t) => motionNodeClips(id, timeline, t).find((c) => c.shape === (p === "clipRect" ? "rect" : "circle"));
+      const rest = clipAt(0);
+      (wrap[id] ??= []).push({ id: wrapper, clip: { id: clipId, shapeId, shape: rest.shape, attrs: motionClipAttrs(rest) } });
+      channels.push({ id: shapeId, kind: "attrs", attrs: Object.keys(motionClipAttrs(rest)), segments: [...track(id, p)], exact: () => true, value: (t) => Object.values(motionClipAttrs(clipAt(t))).map((v) => Math.round(v * 1e4) / 1e4) });
+    }
+    const followSegments = track(id, "follow");
+    if (drawn && followSegments.length) {
+      const ids = /* @__PURE__ */ new Map();
+      for (const seg of followSegments) {
+        if (!seg.path || ids.has(seg.path)) continue;
+        const route = motionFollowRoute(entry, nodes.get(seg.path));
+        if (!route) continue;
+        const routeId = freshId(`${id}--follow-route`);
+        ids.set(seg.path, routeId);
+        routes.push(`<path id="${routeId}" d="${bezierPathToSvg(route, { precision })}" fill="none"/>`);
+      }
+      if (ids.size) {
+        const wrapper = freshId(`${id}--follow`);
+        const centre = freshId(`${id}--follow-centre`);
+        const c = entry.center;
+        const at = motionNodeOffset(entry, timeline, 0, nodes)?.follow;
+        const placed = at ? `translate(${f(at.x)} ${f(at.y)})${at.angle ? ` rotate(${f(at.angle)})` : ""}` : void 0;
+        (wrap[id] ??= []).push({ id: wrapper, ...placed ? { transform: placed } : {} }, { id: centre, transform: `translate(${f(-c.x)} ${f(-c.y)})` });
+        follows.push({ id, wrapper, routes: ids, segments: followSegments.filter((seg) => seg.path && ids.has(seg.path)) });
+      }
+    }
     if (timeline.tracks.has(motionTrackKey(id, "opacity")))
-      channels.push({ id, kind: "attr", attr: "opacity", segments: [...track(id, "opacity")], exact: (s) => !s.wave, value: (t) => round2(Math.min(1, Math.max(0, Number(trackValue(track(id, "opacity"), t))))) });
-    const transformSegments = TRANSFORM_PROPS2.flatMap((p) => track(id, p));
+      channels.push({ id, kind: "attr", attr: "opacity", segments: [...track(id, "opacity")], exact: plays, value: (t) => round2(Math.min(1, Math.max(0, Number(trackValue(track(id, "opacity"), t))))) });
+    const followed = follows.some((x) => x.id === id);
+    const transformSegments = TRANSFORM_PROPS2.flatMap((p) => followed && p === "follow" ? [] : track(id, p));
     if (transformSegments.length) {
       const base = node.transform ? ` matrix(${node.transform.map(f).join(" ")})` : "";
       const c = entry.center;
+      const transformAt = (t, raw) => {
+        const o = motionNodeOffset(entry, timeline, t, nodes, raw, !followed);
+        return `translate(${f(o.dx)} ${f(o.dy)}) rotate(${f(o.rotation)} ${f(c.x)} ${f(c.y)}) translate(${f(c.x)} ${f(c.y)}) scale(${f(o.scaleX)} ${f(o.scaleY)}) translate(${f(-c.x)} ${f(-c.y)})${base}`;
+      };
       channels.push({
         id,
         kind: "attr",
         attr: "transform",
         segments: transformSegments,
-        exact: (s) => LINEAR_TRANSFORM.has(s.property) && !s.wave,
+        exact: (s) => LINEAR_TRANSFORM.has(s.property) && plays(s),
         overshoot: true,
-        value: (t) => {
-          const o = motionNodeOffset(entry, timeline, t, nodes);
-          return `translate(${f(o.dx)} ${f(o.dy)}) rotate(${f(o.rotation)} ${f(c.x)} ${f(c.y)}) translate(${f(c.x)} ${f(c.y)}) scale(${f(o.scaleX)} ${f(o.scaleY)}) translate(${f(-c.x)} ${f(-c.y)})${base}`;
-        }
+        // x, y and the angle are the transform's numbers 0, 1 and 2 (`MotionSegment.index`).
+        value: (t) => transformAt(t, false),
+        raw: (t) => transformAt(t, true)
       });
     }
     const paths = node.type === "path" ? [node] : collectPathNodes(node);
@@ -1292,7 +1526,7 @@ function toFlairSvgMotion(scene, options = {}) {
       pathsSeen.add(path.id);
       const paint = (p, attr) => {
         const from = owner(path, p);
-        if (from) channels.push({ id: path.id, kind: "attr", attr, segments: [...track(from, p)], exact: () => true, value: (t) => hex6(trackValue(track(from, p), t)) });
+        if (from) channels.push({ id: path.id, kind: "attr", attr, segments: [...track(from, p)], exact: plays, value: (t) => hex6(trackValue(track(from, p), t)), raw: (t) => hex6(trackValue(track(from, p), t, true)) });
       };
       paint("fill", "fill");
       paint("stroke", "stroke");
@@ -1331,15 +1565,22 @@ function toFlairSvgMotion(scene, options = {}) {
   const animate = [];
   let sampled = 0;
   const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-  const emit = (channel, delay, ms, from, to, ease) => {
-    const base = { ...channel.id ? { id: channel.id } : {}, ...delay > 0 ? { delay: round2(delay) } : {}, ms: round2(ms), ease: typeof ease === "string" ? ease : ease.map(round2) };
+  const emit = (channel, delay, ms, from, to, ease, behavior) => {
+    const base = { ...channel.id ? { id: channel.id } : {}, ...delay > 0 ? { delay: round2(delay) } : {}, ms: round2(ms), ease: typeof ease === "string" ? ease : ease.map(round2), ...behavior ? { behavior } : {} };
     if (channel.kind === "view") animate.push({ ...base, view: to });
     else if (channel.kind === "draw") animate.push({ ...base, draw: [from, to] });
-    else animate.push({ ...base, attrs: { [channel.attr]: [from, to] } });
+    else if (channel.kind === "attrs") {
+      const [a, b] = [from, to];
+      const attrs = Object.fromEntries(channel.attrs.flatMap((name, k) => a[k] !== b[k] ? [[name, [a[k], b[k]]]] : []));
+      animate.push({ ...base, attrs });
+    } else animate.push({ ...base, attrs: { [channel.attr]: [from, to] } });
   };
   for (const channel of channels) {
     const cuts = channel.segments.filter((s) => s.end <= s.start);
-    for (const cut of cuts) emit(channel, cut.start, 0, channel.value(Math.max(0, cut.start - 1e-3)), channel.value(cut.start), "linear");
+    for (const cut of cuts) {
+      const [from, to] = [channel.value(Math.max(0, cut.start - 1e-3)), channel.value(cut.start)];
+      if (cut.start <= 0 || !same(from, to) || channel.kind === "view") emit(channel, cut.start, 0, from, to, "linear");
+    }
     const times = [...new Set(channel.segments.flatMap((s) => [s.start, s.end]))].sort((a, b) => a - b);
     for (let i = 0; i + 1 < times.length; i++) {
       const a = times[i];
@@ -1347,13 +1588,15 @@ function toFlairSvgMotion(scene, options = {}) {
       const active = channel.segments.filter((s) => s.start < b && s.end > a);
       if (!active.length) continue;
       const first = active[0];
-      const together = active.every((x) => x.start === a && x.end === b && channel.exact(x) && JSON.stringify(x.ease) === JSON.stringify(first.ease));
+      const together = active.every(
+        (x) => x.start === a && x.end === b && channel.exact(x) && JSON.stringify(x.ease) === JSON.stringify(first.ease) && JSON.stringify(x.behavior) === JSON.stringify(first.behavior)
+      );
       const curve = together ? flairCurveFor(first.ease, curves) : void 0;
       const ease = curve && (!overshoots(curve) || channel.overshoot) ? curve : void 0;
       if (ease) {
         const from = channel.value(a);
-        const to = channel.value(b);
-        if (!same(from, to) || channel.kind === "view") emit(channel, a, b - a, from, to, ease);
+        const to = first.behavior ? (channel.raw ?? channel.value)(b) : channel.value(b);
+        if (!same(from, to) || channel.kind === "view") emit(channel, a, b - a, from, to, ease, first.behavior);
         continue;
       }
       const n = Math.max(1, Math.ceil((b - a) * fps / 1e3));
@@ -1370,8 +1613,29 @@ function toFlairSvgMotion(scene, options = {}) {
       }
     }
   }
+  for (const follow of follows) {
+    const starts = follow.segments.map((seg) => seg.start);
+    for (const seg of follow.segments) {
+      const along = { id: follow.wrapper, along: follow.routes.get(seg.path), ...seg.rotate ? { orient: true } : {} };
+      const progress = (t) => round2(Math.min(1, Math.max(0, Number(segmentValue(seg, t)))));
+      const curve = seg.end > seg.start ? flairCurveFor(seg.ease, curves) : "linear";
+      if (curve && !(overshoots(curve) && seg.rotate)) {
+        animate.push({ ...along, ...seg.start > 0 ? { delay: round2(seg.start) } : {}, ms: round2(seg.end - seg.start), ease: typeof curve === "string" ? curve : curve.map(round2), at: [round2(Number(seg.from)), round2(Number(seg.to))] });
+        continue;
+      }
+      const until = Math.min(seg.end, ...starts.filter((t) => t > seg.start));
+      const n = Math.max(1, Math.ceil((until - seg.start) * fps / 1e3));
+      for (let k = 1; k <= n; k++) {
+        const t0 = seg.start + (until - seg.start) * (k - 1) / n;
+        const t1 = seg.start + (until - seg.start) * k / n;
+        animate.push({ ...along, ...t0 > 0 ? { delay: round2(t0) } : {}, ms: round2(t1 - t0), ease: "linear", at: [progress(t0), progress(t1)] });
+        sampled++;
+      }
+    }
+  }
   animate.sort((x, y) => (x.delay ?? 0) - (y.delay ?? 0));
-  let svg = vectorDocumentToSvg({ ...scene.artwork, nodes: expandVectorAppearances(scene.artwork.nodes) }, { pretty: false, precision });
+  let svg = vectorDocumentToSvg({ ...scene.artwork, nodes: expandVectorAppearances(scene.artwork.nodes) }, { pretty: false, precision, wrap });
+  if (routes.length) svg = svg.replace(/^(<svg[^>]*>)/, `$1<defs>${routes.join("")}</defs>`);
   const lastChange = animate.reduce((m, a) => Math.max(m, (a.delay ?? 0) + (a.ms ?? 0)), 0);
   let motion = { svg, animate };
   if (scene.controls?.length) {
@@ -1680,13 +1944,20 @@ 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: [
     command("enter", "Brings hidden targets in; they are hidden before this shot.", {
-      style: { type: "string", enum: [...MOTION_ENTER_STYLES], description: "fade (default), pop, grow, slide, or draw (outline drawn on, then the fill fades in)." },
-      direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "For slide: direction of travel (default up)." },
-      distance: { type: "number", description: "For slide: document units (default 40)." }
+      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." }
     }),
     command("exit", "Takes targets out.", {
-      style: { type: "string", enum: [...MOTION_EXIT_STYLES], description: "fade (default), shrink, slide or undraw." },
-      direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "For slide: direction of travel (default down)." },
+      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)." }
     }),
     command("draw", "Draws strokes on (or off) to a fraction of their length.", { to: FRACTION("Fraction drawn at the end (default 1)."), from: FRACTION("Fraction drawn at the start (default: what is drawn now).") }),
@@ -1702,12 +1973,30 @@ var MOTION_COMMAND_SCHEMA = {
     command("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"]),
     command("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)." },
+      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"]),
     command("pulse", "Scales up and back to draw the eye.", { amount: { type: "number", description: "Extra scale at the peak (default 0.15)." }, count: { type: "integer", minimum: 1, description: "Pulses (default 1)." } }),
-    command("shake", "Shakes side to side, settling.", { amount: { type: "number", description: "Document units (default 8)." }, count: { type: "integer", minimum: 1, description: "Shakes (default 3)." } }),
+    command("shake", "Shakes side to side (or up and down), settling.", {
+      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." }
+    }),
+    command("teeter", "Rocks about the centre either way, settling.", { angle: { type: "number", description: "Degrees either way (default 8)." }, count: { type: "integer", minimum: 1, description: "Rocks (default 3)." } }),
+    command("wave", "Bobs up and down without settling, like something floating (default 1000 ms).", { amount: { type: "number", description: "Height in document units (default 6)." }, count: { type: "integer", minimum: 1, description: "Bobs (default 2)." } }),
+    command("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.", {
+      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." }
+    }),
+    command("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)." }
+    }),
     command("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)." },
@@ -1804,7 +2093,8 @@ function describeMotionShots(scene) {
       ...shot.hold !== void 0 ? { hold: shot.hold } : {},
       commands: shot.run.map((c, index) => {
         const ct = timeline.commands.find((x) => x.shotIndex === i && x.command === index);
-        return { index, ...c, start: ct.start, end: ct.end };
+        const primitive = motionFlairPrimitive(c);
+        return { index, ...c, start: ct.start, end: ct.end, ...primitive ? { flairPrimitive: primitive } : {} };
       })
     };
   });
@@ -1840,7 +2130,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
   const getAnimation = {
     name: "get_animation",
     title: "Read the animation",
-    description: "Returns the vector animation: its name, artwork size, length (ms), loop mode, the artwork's elements (id, type, name, parent, bounds, solid paints, live effects with their numeric parameters), every shot with its commands and their start/end times, Flair controls, and a summary of issues. Use the ids it returns with the write tools.",
+    description: `Returns the vector animation: its name, artwork size, length (ms), loop mode, the artwork's elements (id, type, name, parent, bounds, solid paints, live effects with their numeric parameters), every shot with its commands and their start/end times (and, where Flair has one, the Flair motion primitive a command plays as "flairPrimitive", e.g. "entrance.pop"), Flair controls, and a summary of issues. Use the ids it returns with the write tools.`,
     inputSchema: object({ includeElements: { type: "boolean", description: "Include the artwork's elements (default true)." } }),
     annotations: { title: "Read the animation", ...READ },
     handler: ({ includeElements = true }) => {
@@ -1927,16 +2217,18 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     }
   };
   const CURVES_DESCRIPTION = "Write cubic-bezier easings (ease, ease-in, ease-out, ease-in-out, back eases, custom curves) as one change with ease: [x1, y1, x2, y2] (default true). Needs Flair 0.36 or later; false samples them into linear steps for older Flair.";
+  const BEHAVIORS_DESCRIPTION = "Write pulses, shakes, teeters, waves, wiggles and colour pulses as one change with a Flair behavior, so they play exactly (default true; needs Flair 0.38 or later). False samples them into linear steps for older Flair.";
   const exportFlairMotion = {
     name: "export_flair_motion",
     title: "Export as Flair vector motion",
     description: "Returns the animation as a Flair SvgMotion ({ svg, animate }) that Flair's SvgPlayer plays, plus its hold, how many changes were sampled into linear steps, and notes on anything not carried over.",
     inputSchema: object({
       fps: { type: "number", minimum: 1, maximum: 120, description: "Sampling rate for changes Flair cannot express exactly (default: the scene's fps, else 30)." },
-      curves: { type: "boolean", description: CURVES_DESCRIPTION }
+      curves: { type: "boolean", description: CURVES_DESCRIPTION },
+      behaviors: { type: "boolean", description: BEHAVIORS_DESCRIPTION }
     }),
     annotations: { title: "Export as Flair vector motion", ...READ },
-    handler: ({ fps, curves }) => controller.toFlairMotion({ ...fps ? { fps } : {}, ...curves === void 0 ? {} : { curves } })
+    handler: ({ fps, curves, behaviors }) => controller.toFlairMotion({ ...fps ? { fps } : {}, ...curves === void 0 ? {} : { curves }, ...behaviors === void 0 ? {} : { behaviors } })
   };
   const exportFlairEffect = {
     name: "export_flair_effect",
@@ -1948,7 +2240,8 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       description: { type: "string", description: "One sentence (default: the scene's description)." },
       category: { type: "string", minLength: 1, description: "Flair catalog category, e.g. icon, loader, ui, data, text, morph (default icon)." },
       tags: { type: "array", items: { type: "string" }, description: "Search tags (default none)." },
-      curves: { type: "boolean", description: CURVES_DESCRIPTION }
+      curves: { type: "boolean", description: CURVES_DESCRIPTION },
+      behaviors: { type: "boolean", description: BEHAVIORS_DESCRIPTION }
     }),
     annotations: { title: "Export as a Flair effect", ...READ },
     handler: (args) => controller.toFlairEffect(args)
@@ -2160,8 +2453,12 @@ How it plays
 
 Commands
 - enter (fade, pop, grow, slide, draw) and exit (fade, shrink, slide, undraw) bring things in and out.
+- 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.
 - 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.
-- 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.
+- enter also has zoom (settles from larger) and rise (rises a short way, overshooting a touch); pop and zoom take a starting "scale".
+- 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).
+- 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).
+- 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.
 - effect tweens a numeric parameter of a live path effect already on the node (twist angle, wiggle time, zig zag size).
 
 Working method
@@ -2189,8 +2486,10 @@ export {
   MOTION_EDIT_OPS,
   MOTION_ENTER_STYLES,
   MOTION_EXIT_STYLES,
+  MOTION_IRIS_SHAPES,
   MOTION_ISSUE_CODES,
   MOTION_MIN_CHANGE_MS,
+  MOTION_SPLIT_ORIENTATIONS,
   MotionSceneFormatError,
   activeSegment,
   applyMotionControlValues,
@@ -2210,15 +2509,21 @@ export {
   interpolateMotionValue,
   isMotionCommand,
   isMotionShot,
+  motionClipAttrs,
   motionCommandDuration,
+  motionFlairPrimitive,
+  motionFollowRoute,
   motionFrameAt,
   motionFrameToSvg,
   motionIssue,
   motionIssueKey,
   motionIssueLine,
+  motionNodeClips,
   motionNodeOffset,
   motionPathLength,
   motionRestValue,
+  motionRevealClip,
+  motionRevealPadding,
   motionSceneShapeProblems,
   motionSceneToJson,
   motionShotAt,