@pixerate/editor 0.58.0 → 0.59.0

package/dist/animation-editor/index.js

@@ -10,6 +10,7 @@ import {
   isIdentityMatrix,
   multiplyMatrices,
   nodeMatrix,
+  parseSvgTransform,
   parseVectorSvg,
   rotateMatrix,
   scaleMatrix,
@@ -17,7 +18,7 @@ import {
   vectorDocumentToSvg,
   vectorNodeBounds,
   vectorPathWorldBezier
-} from "../chunk-PYMV7HLI.js";
+} from "../chunk-3TLL5OID.js";
 import {
   bezierPathLength,
   bezierPathPointAtLength,
@@ -33,7 +34,7 @@ import {
 } from "../chunk-3NYXDBBW.js";
 import {
   AnimationPlayer
-} from "../chunk-SHOVAHUB.js";
+} from "../chunk-JK6M6V7G.js";
 import {
   mixColorsOklab
 } from "../chunk-ZRJMJIQU.js";
@@ -46,8 +47,10 @@ import {
   ANIMATION_EASING_PRESETS,
   evaluateEasing,
   isAnimationEasing,
-  resolveEasing
-} from "../chunk-UB2OY7FD.js";
+  resolveEasing,
+  reverseCubicBezier,
+  springSettleMs
+} from "../chunk-AGR4P4UZ.js";
 
 // src/animation-editor/types.ts
 var MOTION_COMMAND_TYPES = [
@@ -71,6 +74,7 @@ var MOTION_COMMAND_TYPES = [
   "wait"
 ];
 var MOTION_ENTER_STYLES = ["fade", "pop", "grow", "slide", "draw", "zoom", "rise", "wipe", "iris", "split"];
+var MOTION_REPEAT_MODES = ["loop", "mirror", "offset"];
 var MOTION_EXIT_STYLES = ["fade", "shrink", "slide", "undraw", "wipe"];
 var MOTION_IRIS_SHAPES = ["circle", "box"];
 var MOTION_SPLIT_ORIENTATIONS = ["horizontal", "vertical"];
@@ -139,6 +143,7 @@ var MOTION_ISSUE_CODES = {
   "exit-hidden": { severity: "warning", wording: "A node exits or animates while it is hidden." },
   "out-of-frame": { severity: "warning", wording: "A node a command animates ends up outside the camera." },
   "too-fast": { severity: "warning", wording: "A change is too quick to follow." },
+  "spring-cut-short": { severity: "warning", wording: "A spring is given a duration shorter than it takes to settle, so it jumps to its end." },
   "scene-too-long": { severity: "warning", wording: "The scene runs past its target length." },
   "scene-too-short": { severity: "warning", wording: "The scene ends before its target length." },
   "unknown-control-color": { severity: "warning", wording: "A control stands for a colour the scene never uses." },
@@ -196,17 +201,17 @@ ${problems.map((p) => `- ${p}`).join("\n")}`);
     this.problems = problems;
   }
 };
-var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "loop", "fps", "target", "controls", "presets"];
+var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "loop", "fps", "steps", "target", "controls", "presets"];
 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 CAMERA_KEYS = ["x", "y", "width", "height", "frame", "padding", "ease", "ms", "geometric"];
+var BASE_KEYS = ["type", "targets", "duration", "delay", "stagger", "with", "ease", "note", "repeat", "repeatMode", "steps"];
 var COMMAND_KEYS = {
   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"],
   rotate: [...BASE_KEYS, "by", "to"],
-  scale: [...BASE_KEYS, "to"],
+  scale: [...BASE_KEYS, "to", "geometric"],
   fade: [...BASE_KEYS, "to"],
   style: [...BASE_KEYS, "fill", "stroke", "strokeWidth"],
   morph: [...BASE_KEYS, "into"],
@@ -254,7 +259,13 @@ function commandShapeProblems(command2, where) {
   nonNegative("duration");
   nonNegative("delay");
   nonNegative("stagger");
-  if (command2.ease !== void 0 && !isAnimationEasing(command2.ease)) p(`"ease" is not an easing; use a preset such as "ease-in-out" or { "type": "cubic-bezier", \u2026 }.`);
+  if (command2.ease !== void 0 && !isAnimationEasing(command2.ease)) p(`"ease" is not an easing; use a preset such as "ease-in-out" or "spring-bouncy", or { "type": "cubic-bezier", \u2026 } or { "type": "spring", \u2026 }.`);
+  if (command2.repeat !== void 0) {
+    if (type === "enter" || type === "exit") p(`"repeat" is not for ${type} (it brings things in or out once); repeat an emphasis or a move instead.`);
+    else if (!(Number.isInteger(command2.repeat) && command2.repeat >= 1 && command2.repeat <= 1e3)) p(`"repeat" must be a whole number from 1 to 1000.`);
+  }
+  if (command2.repeatMode !== void 0 && !MOTION_REPEAT_MODES.includes(command2.repeatMode)) p(`"repeatMode" must be one of ${MOTION_REPEAT_MODES.join(", ")}.`);
+  if (command2.steps !== void 0 && !(isNum(command2.steps) && command2.steps > 0 && command2.steps <= 120)) p(`"steps" must be frames per second from above 0 to 120 (12 holds each pose for two frames at 24 fps).`);
   switch (type) {
     case "enter":
     case "exit": {
@@ -286,6 +297,7 @@ function commandShapeProblems(command2, where) {
       break;
     case "scale":
       if (!(isNum(command2.to) || isPoint(command2.to))) p(`"to" must be a number or { "x": number, "y": number }.`);
+      if (command2.geometric !== void 0 && typeof command2.geometric !== "boolean") p(`"geometric" must be true or false.`);
       break;
     case "fade":
       if (!(isNum(command2.to) && command2.to >= 0 && command2.to <= 1)) p(`"to" must be an opacity from 0 to 1.`);
@@ -351,6 +363,7 @@ function shotShapeProblems(shot, where) {
       } else if (!isRect) problems.push(`${name} camera: give { x, y, width, height } or { frame: "<node id>" }.`);
       if (c.ease !== void 0 && !isAnimationEasing(c.ease)) problems.push(`${name} camera: "ease" is not an easing.`);
       if (c.ms !== void 0 && !(isNum(c.ms) && c.ms >= 0)) problems.push(`${name} camera: "ms" must be a number \u2265 0.`);
+      if (c.geometric !== void 0 && typeof c.geometric !== "boolean") problems.push(`${name} camera: "geometric" must be true or false.`);
     }
   }
   if (!Array.isArray(shot.run)) problems.push(`${name}: "run" must be a list of commands (it may be empty).`);
@@ -369,6 +382,7 @@ function motionSceneShapeProblems(input) {
     problems.push('Scene: "artwork" must be a vector document { width, height, nodes }.');
   if (input.loop !== void 0 && !["none", "loop", "ping-pong"].includes(input.loop)) problems.push('Scene: "loop" must be "none", "loop" or "ping-pong".');
   if (input.fps !== void 0 && !(isNum(input.fps) && input.fps > 0 && input.fps <= 120)) problems.push('Scene: "fps" must be a number from 1 to 120.');
+  if (input.steps !== void 0 && !(isNum(input.steps) && input.steps > 0 && input.steps <= 120)) problems.push('Scene: "steps" must be frames per second from above 0 to 120.');
   if (input.target !== void 0 && !(Array.isArray(input.target) && input.target.length === 2 && input.target.every(isNum) && input.target[0] <= input.target[1]))
     problems.push('Scene: "target" must be [min, max] seconds.');
   if (input.controls !== void 0) {
@@ -535,11 +549,33 @@ 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: evaluateEasing(segment.ease, u, span) };
+  let elapsed = time - segment.start;
+  if (segment.steps && segment.steps > 0 && elapsed < span) elapsed = Math.floor(elapsed * segment.steps / 1e3 + 1e-9) / segment.steps * 1e3;
+  const u = span <= 0 ? 1 : Math.min(1, Math.max(0, elapsed / span));
+  return { u, eased: evaluateEasing(segment.ease, segment.reverse ? 1 - u : u, span) };
+}
+function geometricValue(from, to, e) {
+  const grow = (a, b) => a > 0 && b > 0 ? a * (b / a) ** e : void 0;
+  if (typeof from === "number" && typeof to === "number") return grow(from, to);
+  if (Array.isArray(from) && Array.isArray(to) && from.length === 4 && to.length === 4) {
+    const [x0, y0, w0, h0] = from;
+    const [x1, y1, w1, h1] = to;
+    const w = grow(w0, w1);
+    const h = grow(h0, h1);
+    if (w === void 0 || h === void 0) return void 0;
+    const f = Math.abs(w1 - w0) > 1e-9 ? (w - w0) / (w1 - w0) : e;
+    const cx = x0 + w0 / 2 + (x1 + w1 / 2 - x0 - w0 / 2) * f;
+    const cy = y0 + h0 / 2 + (y1 + h1 / 2 - y0 - h0 / 2) * f;
+    return [cx - w / 2, cy - h / 2, w, h];
+  }
+  return void 0;
 }
 function segmentValue(segment, time, raw = false) {
   const { eased } = segmentProgress(segment, time);
+  if (segment.geometric && !segment.behavior) {
+    const g = geometricValue(segment.from, segment.to, eased);
+    if (g !== void 0) return g;
+  }
   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);
@@ -590,9 +626,21 @@ function motionPathLength(node, parentWorld = IDENTITY_MATRIX) {
   }
   return longest;
 }
+function motionCommandRepeat(command2) {
+  if (command2.type === "wait" || command2.type === "enter" || command2.type === "exit") return 1;
+  const n = command2.repeat ?? 1;
+  return Number.isInteger(n) && n >= 1 ? n : 1;
+}
 function motionCommandDuration(command2, scene, target) {
+  return motionCycleDuration(command2, scene, target) * motionCommandRepeat(command2);
+}
+function motionCycleDuration(command2, scene, target) {
   if (command2.type === "wait") return command2.duration;
   if (command2.duration !== void 0) return command2.duration;
+  if (command2.ease !== void 0) {
+    const ease = resolveEasing(command2.ease);
+    if (ease !== "hold" && ease.type === "spring") return springSettleMs(ease);
+  }
   if (command2.type === "draw" || command2.type === "enter" && command2.style === "draw" || command2.type === "exit" && command2.style === "undraw") {
     const entry = target ? indexMotionNodes(scene.artwork.nodes).get(target) : void 0;
     const length = entry ? motionPathLength(entry.node) : 0;
@@ -621,7 +669,7 @@ function compileMotionScene(scene) {
       const rect = resolveMotionCamera(shot.camera, scene);
       if (rect && rect.width > 0 && rect.height > 0) {
         const ms = index === 0 ? 0 : shot.camera.ms ?? MOTION_CAMERA_MS;
-        cameraMoves.push({ shot: shot.id, start, end: start + ms, to: rect, ease: shot.camera.ease ?? MOTION_EASE_IN_OUT });
+        cameraMoves.push({ shot: shot.id, start, end: start + ms, to: rect, ease: shot.camera.ease ?? MOTION_EASE_IN_OUT, geometric: shot.camera.geometric === true });
         cursor = start + ms;
       }
     }
@@ -662,7 +710,7 @@ function compileMotionScene(scene) {
     jobs.push({
       start: move.start,
       order: order++,
-      run: () => push({ node: "", property: "camera", start: move.start, end: move.end, from: valueAt("", "camera", move.start), to: [move.to.x, move.to.y, move.to.width, move.to.height], ease: move.ease, shot: move.shot, command: -1 })
+      run: () => push({ node: "", property: "camera", start: move.start, end: move.end, from: valueAt("", "camera", move.start), to: [move.to.x, move.to.y, move.to.width, move.to.height], ease: move.ease, shot: move.shot, command: -1, ...move.geometric ? { geometric: true } : {} })
     });
   }
   for (const timing of commands) {
@@ -673,11 +721,37 @@ function compileMotionScene(scene) {
       const entry = nodes.get(target);
       if (!entry) return;
       const start = timing.start + k * (command2.stagger ?? 0);
-      const duration2 = motionCommandDuration(command2, scene, target);
-      jobs.push({ start, order: order++, run: () => compileCommand(command2, target, entry, start, duration2, timing) });
+      const cycle = motionCycleDuration(command2, scene, target);
+      jobs.push({ start, order: order++, run: () => compileRepeated(command2, target, entry, start, cycle, timing) });
     });
   }
   jobs.sort((a, b) => a.start - b.start || a.order - b.order).forEach((job) => job.run());
+  function compileRepeated(command2, node, entry, start, cycle, timing) {
+    const first = segments.length;
+    compileCommand(command2, node, entry, start, cycle, timing);
+    const made = segments.slice(first);
+    const steps = command2.steps ?? scene.steps;
+    if (steps && steps > 0) for (const s of made) s.steps = steps;
+    const n = motionCommandRepeat(command2);
+    const mode = command2.repeatMode ?? "loop";
+    const shift = (v, by, k) => {
+      if (typeof v === "number" && typeof by === "number") return v + by * k;
+      if (Array.isArray(v) && Array.isArray(by) && v.length === by.length) return v.map((x, i) => x + by[i] * k);
+      return v;
+    };
+    for (let k = 1; k < n; k++) {
+      const at = start + k * cycle;
+      for (const s of made) {
+        if (mode === "mirror" && k % 2 === 1) {
+          push({ ...s, start: at + (start + cycle - s.end), end: at + (start + cycle - s.start), reverse: !s.reverse });
+          continue;
+        }
+        const delta = typeof s.from === "number" && typeof s.to === "number" ? s.to - s.from : Array.isArray(s.from) && Array.isArray(s.to) && s.from.length === s.to.length ? s.to.map((x, i) => x - s.from[i]) : 0;
+        const by = mode === "offset" ? delta : 0;
+        push({ ...s, start: at + (s.start - start), end: at + (s.end - start), from: shift(s.from, by, k), to: shift(s.to, by, k) });
+      }
+    }
+  }
   function compileCommand(command2, node, entry, start, duration2, timing) {
     const end = start + duration2;
     const where = { shot: timing.shot, command: timing.command };
@@ -772,8 +846,9 @@ function compileMotionScene(scene) {
         break;
       case "scale": {
         const to = typeof command2.to === "number" ? { x: command2.to, y: command2.to } : command2.to;
-        seg("scaleX", to.x, ease ?? MOTION_EASE_IN_OUT);
-        seg("scaleY", to.y, ease ?? MOTION_EASE_IN_OUT);
+        const geometric = command2.geometric ? { geometric: true } : {};
+        seg("scaleX", to.x, ease ?? MOTION_EASE_IN_OUT, start, end, geometric);
+        seg("scaleY", to.y, ease ?? MOTION_EASE_IN_OUT, start, end, geometric);
         break;
       }
       case "fade":
@@ -1115,6 +1190,14 @@ function checkMotionScene(scene) {
       const timing = timeline.commands.find((c) => c.shot === shot.id && c.command === i);
       if (timing && timing.duration > 0 && timing.duration < MOTION_MIN_CHANGE_MS)
         issues.push(motionIssue("too-fast", `This ${command2.type} lasts ${timing.duration} ms, too quick to follow; make it at least ${MOTION_MIN_CHANGE_MS} ms.`, { ...where, measured: timing.duration, needed: MOTION_MIN_CHANGE_MS, unit: "ms", ids: targets }));
+      if (command2.duration !== void 0 && command2.ease !== void 0) {
+        const ease = resolveEasing(command2.ease);
+        if (ease !== "hold" && ease.type === "spring") {
+          const settle = springSettleMs(ease);
+          if (command2.duration < settle * 0.9)
+            issues.push(motionIssue("spring-cut-short", `This ${command2.type}'s spring takes ${settle} ms to settle but lasts ${command2.duration} ms, so it jumps to its end; leave "duration" out (the spring sets it) or make it at least ${settle} ms.`, { ...where, measured: command2.duration, needed: settle, unit: "ms", ids: targets }));
+        }
+      }
       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);
@@ -1272,6 +1355,11 @@ function applyOne(scene, edit) {
       else if (edit.description !== void 0) next.description = edit.description;
       if (edit.loop !== void 0) next.loop = edit.loop;
       if (edit.fps !== void 0) next.fps = edit.fps;
+      if (edit.steps === null) delete next.steps;
+      else if (edit.steps !== void 0) {
+        if (!(typeof edit.steps === "number" && edit.steps > 0 && edit.steps <= 120)) fail('"steps" must be frames per second from above 0 to 120 (12 is "on twos" at 24 fps), or null for smooth.');
+        next.steps = edit.steps;
+      }
       if (edit.target === null) delete next.target;
       else if (edit.target !== void 0) next.target = edit.target;
       return next;
@@ -1407,6 +1495,13 @@ var FLAIR_EASES = {
   "in-out": (t) => t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2,
   out: (t) => 1 - (1 - t) ** 3
 };
+var FLAIR_EXPORT_VERSION = "0.39";
+function flairAtLeast(version, min) {
+  const a = version.split(".").map((n) => parseInt(n, 10) || 0);
+  const b = min.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  return true;
+}
 function flairEaseFor(ease) {
   for (const name of ["linear", "out", "in-out"]) {
     let worst = 0;
@@ -1425,7 +1520,7 @@ function flairCurveFor(ease, curves = true) {
   if (resolved === "hold" || resolved.type !== "cubic-bezier") return void 0;
   return [resolved.x1, resolved.y1, resolved.x2, resolved.y2];
 }
-var overshoots = (ease) => typeof ease !== "string" && (ease[1] < 0 || ease[1] > 1 || ease[3] < 0 || ease[3] > 1);
+var overshoots = (ease) => typeof ease !== "string" && ("spring" in ease || ease[1] < 0 || ease[1] > 1 || ease[3] < 0 || ease[3] > 1);
 var TRANSFORM_PROPS2 = ["x", "y", "rotation", "scaleX", "scaleY", "follow"];
 var LINEAR_TRANSFORM = /* @__PURE__ */ new Set(["x", "y", "rotation", "scaleX", "scaleY"]);
 function hex6(color) {
@@ -1435,9 +1530,24 @@ function hex6(color) {
 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 flair = options.flair ?? FLAIR_EXPORT_VERSION;
+  const curves = options.curves ?? flairAtLeast(flair, "0.36");
+  const behaviors = options.behaviors ?? flairAtLeast(flair, "0.38");
+  const springs = flairAtLeast(flair, "0.39");
+  const strobes = flairAtLeast(flair, "0.39");
+  const writeEase = (ease) => typeof ease === "string" || "spring" in ease ? ease : ease.map(round2);
+  const easeOf = (segment) => {
+    const resolved = resolveEasing(segment.ease);
+    if (resolved !== "hold" && resolved.type === "spring") {
+      if (!springs || segment.reverse) return void 0;
+      const { mass, stiffness, damping, velocity } = resolved;
+      return { spring: { mass, stiffness, damping, velocity } };
+    }
+    if (!segment.reverse) return flairCurveFor(segment.ease, curves);
+    const back = reverseCubicBezier(segment.ease);
+    return back && curves ? flairCurveFor(back, curves) : void 0;
+  };
+  const plays = (s) => (!s.behavior || behaviors) && (!s.steps || strobes) && !s.geometric;
   const round2 = (n) => Math.round(n * 10 ** precision) / 10 ** precision;
   const f = (n) => String(round2(n));
   const timeline = compileMotionScene(scene);
@@ -1565,8 +1675,16 @@ 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, 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 } : {} };
+  const emit = (channel, delay, ms, from, to, ease, segment) => {
+    const written = writeEase(ease);
+    const base = {
+      ...channel.id ? { id: channel.id } : {},
+      ...delay > 0 ? { delay: round2(delay) } : {},
+      ms: round2(ms),
+      ease: written,
+      ...segment?.behavior ? { behavior: segment.behavior } : {},
+      ...segment?.steps ? { strobe: segment.steps } : {}
+    };
     if (channel.kind === "view") animate.push({ ...base, view: to });
     else if (channel.kind === "draw") animate.push({ ...base, draw: [from, to] });
     else if (channel.kind === "attrs") {
@@ -1588,15 +1706,14 @@ 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) && JSON.stringify(x.behavior) === JSON.stringify(first.behavior)
-      );
-      const curve = together ? flairCurveFor(first.ease, curves) : void 0;
+      const key = (x) => JSON.stringify([x.ease, x.behavior, x.reverse ?? false, x.steps ?? 0]);
+      const together = active.every((x) => x.start === a && x.end === b && channel.exact(x) && key(x) === key(first));
+      const curve = together ? easeOf(first) : void 0;
       const ease = curve && (!overshoots(curve) || channel.overshoot) ? curve : void 0;
       if (ease) {
         const from = channel.value(a);
         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);
+        if (!same(from, to) || channel.kind === "view") emit(channel, a, b - a, from, to, ease, first);
         continue;
       }
       const n = Math.max(1, Math.ceil((b - a) * fps / 1e3));
@@ -1618,9 +1735,10 @@ function toFlairSvgMotion(scene, options = {}) {
     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";
+      const curve = seg.end > seg.start ? plays(seg) ? easeOf(seg) : void 0 : "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))] });
+        const ends = seg.reverse ? [Number(seg.to), Number(seg.from)] : [Number(seg.from), Number(seg.to)];
+        animate.push({ ...along, ...seg.start > 0 ? { delay: round2(seg.start) } : {}, ms: round2(seg.end - seg.start), ease: writeEase(curve), ...seg.steps ? { strobe: seg.steps } : {}, at: [round2(ends[0]), round2(ends[1])] });
         continue;
       }
       const until = Math.min(seg.end, ...starts.filter((t) => t > seg.start));
@@ -1678,6 +1796,196 @@ function toFlairEffectDocument(scene, options = {}) {
   };
 }
 
+// src/animation-editor/flair-import.ts
+var PLACEHOLDER = /\{\{\s*([A-Za-z_]\w*)\s*(?::\s*([A-Za-z0-9]*)([^}]*))?\}\}/g;
+function attributeOf(attrs, name) {
+  const m = new RegExp(`(?:^|\\s)${name}=(?:'([^']*)'|(\\S+))`).exec(attrs);
+  return m ? m[1] ?? m[2] : void 0;
+}
+function resolvePlaceholders(motion, notes) {
+  const text = JSON.stringify(motion);
+  const declared = /* @__PURE__ */ new Map();
+  for (const m of text.matchAll(PLACEHOLDER)) {
+    if (!m[2] || declared.has(m[1])) continue;
+    const attrs = m[3] ?? "";
+    const value = attributeOf(attrs, "default");
+    const fallback = m[2] === "color" ? "#000000" : "0";
+    declared.set(m[1], { type: m[2], value: m[2] === "color" ? (value ?? fallback).toLowerCase() : value ?? fallback, ...attributeOf(attrs, "label") ? { label: attributeOf(attrs, "label") } : {} });
+  }
+  const controls = [];
+  for (const [name, d] of declared) {
+    if (d.type === "color" && /^#[0-9a-fA-F]{6}$/.test(d.value)) controls.push({ name, type: "color", default: d.value.toLowerCase(), ...d.label ? { label: d.label } : {} });
+    else notes.push(`Control "${name}" (${d.type}) is fixed at its default ${d.value}: scenes take colour controls only.`);
+  }
+  const unknown = /* @__PURE__ */ new Set();
+  const filled = text.replace(PLACEHOLDER, (_, name) => {
+    const d = declared.get(name);
+    if (!d) unknown.add(name);
+    return (d?.value ?? "").replace(/"/g, '\\"');
+  });
+  for (const name of unknown) notes.push(`Placeholder "{{${name}}}" has no declaration, so it was left empty.`);
+  return { motion: JSON.parse(filled), controls };
+}
+function easingOf(ease, fallback) {
+  if (ease === void 0) return fallback;
+  if (ease === "linear") return "linear";
+  if (ease === "out") return MOTION_EASE_OUT;
+  if (ease === "in-out") return MOTION_EASE_IN_OUT;
+  if (Array.isArray(ease)) return { type: "cubic-bezier", x1: ease[0], y1: ease[1], x2: ease[2], y2: ease[3] };
+  if (typeof ease === "object" && "spring" in ease) return { type: "spring", ...ease.spring };
+  return fallback;
+}
+function poseOf(value, entry) {
+  const t = parseSvgTransform(String(value));
+  const o = multiplyMatrices(invertMatrix(nodeMatrix(entry.node)) ?? [1, 0, 0, 1, 0, 0], t);
+  const sx = Math.hypot(o[0], o[1]);
+  if (!(sx > 1e-9)) return null;
+  const sy = (o[0] * o[3] - o[1] * o[2]) / sx;
+  if (Math.abs(o[2] + o[1] / sx * sy) > 1e-6 || Math.abs(o[3] - o[0] / sx * sy) > 1e-6) return null;
+  const c = entry.center;
+  const moved = applyMatrix(o, c);
+  return { dx: moved.x - c.x, dy: moved.y - c.y, rotation: Math.atan2(o[1], o[0]) * 180 / Math.PI, sx, sy };
+}
+var near = (a, b, eps = 1e-6) => Math.abs(a - b) < eps;
+var r3 = (n) => Math.round(n * 1e3) / 1e3;
+function commandsFor(anim, nodes, entered, notes) {
+  const id = anim.id;
+  const entry = nodes.get(id);
+  const where = `"${id}"`;
+  if (!entry) {
+    notes.push(`A change to ${where} was skipped: the artwork has no element with that id.`);
+    return [];
+  }
+  const targets = [id];
+  const duration = anim.ms ?? 800;
+  const timing = {
+    duration,
+    ...anim.strobe ? { steps: anim.strobe } : {},
+    ...anim.repeat && anim.repeat > 1 ? { repeat: anim.repeat, ...anim.alternate ? { repeatMode: "mirror" } : {} } : {}
+  };
+  const ease = (fallback) => ({ ease: easingOf(anim.ease, fallback) });
+  const out = [];
+  const behavior = anim.behavior;
+  const unsupported = ["count", "write", "scramble", "solo"].filter((k) => anim[k] !== void 0);
+  if (unsupported.length) notes.push(`${where}: ${unsupported.join(", ")} ${unsupported.length > 1 ? "are" : "is"} not part of scenes and was skipped.`);
+  if (anim.draw !== void 0 && anim.draw !== false) {
+    const [from, to] = anim.draw === true ? [0, 1] : anim.draw;
+    out.push({ type: "draw", targets, from, to, ...timing, ...ease(MOTION_EASE_IN_OUT) });
+  }
+  if (anim.along) {
+    const path = nodes.get(anim.along);
+    if (!path || path.node.type !== "path") notes.push(`${where} follows "${anim.along}", which is not a path in the artwork; the follow was skipped.`);
+    else out.push({ type: "follow", targets, path: anim.along, from: anim.at?.[0] ?? 0, to: anim.at?.[1] ?? 1, ...anim.orient ? { rotate: true } : {}, ...timing, ...ease(MOTION_EASE_IN_OUT) });
+  }
+  for (const [attr, [a, b]] of Object.entries(anim.attrs ?? {})) {
+    if (attr === "opacity") {
+      const [from, to] = [Number(a), Number(b)];
+      if (behavior) notes.push(`${where}: an opacity ${behavior.type} became a plain fade.`);
+      if (from === 0 && to > 0 && !entered.has(id)) {
+        entered.add(id);
+        out.push({ type: "enter", targets, style: "fade", ...timing, ...ease(MOTION_EASE_OUT) });
+      } else out.push({ type: "fade", targets, to: Math.min(1, Math.max(0, to)), ...timing, ...ease(MOTION_EASE_IN_OUT) });
+    } else if (attr === "fill" || attr === "stroke") {
+      if (behavior?.type === "pulse") out.push({ type: "color-pulse", targets, color: String(b), paint: attr, count: behavior.count ?? 1, ...timing, ...ease("linear") });
+      else {
+        if (behavior) notes.push(`${where}: a ${attr} ${behavior.type} became a plain colour change.`);
+        out.push({ type: "style", targets, [attr]: String(b), ...timing, ...ease(MOTION_EASE_IN_OUT) });
+      }
+    } else if (attr === "stroke-width") {
+      out.push({ type: "style", targets, strokeWidth: Number(b), ...timing, ...ease(MOTION_EASE_IN_OUT) });
+    } else if (attr === "transform") {
+      const p0 = poseOf(a, entry);
+      const p1 = poseOf(b, entry);
+      if (!p0 || !p1) {
+        notes.push(`${where}: a transform that skews was skipped (scenes move, turn and scale).`);
+        continue;
+      }
+      const d = { x: r3(p1.dx - p0.dx), y: r3(p1.dy - p0.dy), r: r3(p1.rotation - p0.rotation), sx: p1.sx / p0.sx, sy: p1.sy / p0.sy };
+      if (behavior) {
+        const linear = ease("linear");
+        const moves = d.x !== 0 || d.y !== 0;
+        const turns = d.r !== 0;
+        const scales = !near(d.sx, 1) || !near(d.sy, 1);
+        if (behavior.type === "pulse" && scales && !moves && !turns) out.push({ type: "pulse", targets, amount: r3(d.sx - 1), count: behavior.count ?? 1, ...timing, ...linear });
+        else if (behavior.type === "oscillate" && (behavior.decay ?? 0) > 0 && turns && !moves && !scales) out.push({ type: "teeter", targets, angle: d.r, count: behavior.count ?? 1, ...timing, ...linear });
+        else if (behavior.type === "oscillate" && (behavior.decay ?? 0) > 0 && moves && !turns && !scales && (d.x === 0 || d.y === 0))
+          out.push({ type: "shake", targets, amount: d.x || d.y, count: behavior.count ?? 1, ...d.x === 0 ? { axis: "vertical" } : {}, ...timing, ...linear });
+        else if (behavior.type === "oscillate" && !behavior.decay && d.x === 0 && d.y !== 0 && !turns && !scales) out.push({ type: "wave", targets, amount: -d.y, count: behavior.count ?? 1, ...timing, ...linear });
+        else if (behavior.type === "wriggle" && !scales)
+          out.push({ type: "wiggle", targets, amount: Math.max(Math.abs(d.x), Math.abs(d.y)), ...turns ? { rotate: Math.abs(d.r) } : {}, frequency: behavior.frequency ?? 2, octaves: behavior.octaves ?? 2, seed: behavior.seed ?? 42, ...timing, ...linear });
+        else notes.push(`${where}: a transform ${behavior.type} that is not a pulse, shake, teeter, wave or wiggle was skipped.`);
+        continue;
+      }
+      const e = ease(MOTION_EASE_IN_OUT);
+      if (d.x !== 0 || d.y !== 0) out.push({ type: "move", targets, by: { x: d.x, y: d.y }, ...timing, ...e });
+      if (d.r !== 0) out.push({ type: "rotate", targets, to: r3(p1.rotation), ...timing, ...e });
+      if (!near(d.sx, 1) || !near(d.sy, 1)) out.push({ type: "scale", targets, to: near(p1.sx, p1.sy) ? r3(p1.sx) : { x: r3(p1.sx), y: r3(p1.sy) }, ...timing, ...e });
+    } else notes.push(`${where}: changing "${attr}" is not part of scenes and was skipped.`);
+  }
+  return out;
+}
+function fromFlairSvgMotion(input, options = {}) {
+  const notes = [];
+  if (!input || typeof input.svg !== "string") throw new Error('Give a Flair SvgMotion: { svg: "<svg \u2026>", animate: [ \u2026 ] }.');
+  const { motion, controls } = resolvePlaceholders(input, notes);
+  const artwork = parseVectorSvg(motion.svg);
+  const nodes = indexMotionNodes(artwork.nodes);
+  const byStep = /* @__PURE__ */ new Map();
+  for (const anim of motion.animate ?? []) {
+    const step = Math.max(0, Math.floor(anim.step ?? 0));
+    if (!byStep.has(step)) byStep.set(step, []);
+    byStep.get(step).push(anim);
+  }
+  const steps = [...byStep.keys()].sort((a, b) => a - b);
+  if (steps.length > 1) notes.push("Each Flair step became a shot played after the one before (Flair steps wait for clicks or set times).");
+  const entered = /* @__PURE__ */ new Set();
+  const shots = steps.map((step, index) => {
+    const anims = [...byStep.get(step)].sort((a, b) => (a.delay ?? 0) - (b.delay ?? 0));
+    let camera;
+    let cameraMs = 0;
+    const run = [];
+    let last = 0;
+    for (const anim of anims) {
+      if (anim.view !== void 0) {
+        if (camera || (anim.delay ?? 0) > 0) {
+          notes.push(`Step ${step}: a camera move ${camera ? "after the first" : `${anim.delay} ms in`} was dropped; a shot frames the camera once, at its start.`);
+          continue;
+        }
+        const ms = anim.ms ?? 800;
+        const ease = easingOf(anim.ease, MOTION_EASE_IN_OUT);
+        camera = typeof anim.view === "string" ? { frame: anim.view, padding: 0, ms, ease } : { x: anim.view[0], y: anim.view[1], width: anim.view[2], height: anim.view[3], ms, ease };
+        cameraMs = index === 0 ? 0 : ms;
+        continue;
+      }
+      if (!anim.id) continue;
+      const at = Math.max(0, (anim.delay ?? 0) - cameraMs);
+      if (cameraMs && (anim.delay ?? 0) < cameraMs) notes.push(`Step ${step}: a change to "${anim.id}" during the camera move now starts after it.`);
+      for (const command2 of commandsFor(anim, nodes, entered, notes)) {
+        const first = run.length === 0;
+        run.push({ ...command2, ...first ? {} : { with: "previous" }, ...at - last > 0 || first ? { delay: first ? at : at - last } : {} });
+        if (first && at === 0) delete run[run.length - 1].delay;
+        last = at;
+      }
+    }
+    return { id: `step-${step}`, ...camera ? { camera } : {}, run, ...index === steps.length - 1 ? { hold: options.hold ?? 600 } : {} };
+  });
+  const scene = { version: 1, name: options.name ?? "from-flair", artwork, shots, ...controls.length ? { controls } : {} };
+  const problems = motionSceneShapeProblems(scene);
+  if (problems.length) throw new Error(`The imported scene is not well formed:
+${problems.join("\n")}`);
+  return { scene, notes: [...new Set(notes)], issues: checkMotionScene(scene) };
+}
+function fromFlairVectorEffect(effect, options = {}) {
+  if (!effect || effect.kind !== "vector" || !effect.motion) throw new Error('Give a Flair vector effect: { kind: "vector", id, name, motion: { svg, animate } }.');
+  const result = fromFlairSvgMotion(effect.motion, { name: options.name ?? effect.id ?? effect.name, hold: options.hold ?? effect.hold });
+  const names = new Set((result.scene.controls ?? []).map((c) => c.name));
+  const presets = (effect.presets ?? []).map((p) => ({ name: p.name, values: Object.fromEntries(Object.entries(p.values).filter(([k]) => names.has(k))) })).filter((p) => Object.keys(p.values).length);
+  const scene = { ...result.scene, ...effect.description ? { description: effect.description } : {}, ...presets.length ? { presets } : {} };
+  const notes = [...result.notes];
+  if (effect.trigger) notes.push(`The effect plays on ${effect.trigger}; scenes play through, so the trigger is not kept (pass it back to toFlairVectorEffect).`);
+  return { scene, notes, issues: checkMotionScene(scene) };
+}
+
 // src/animation-editor/controller.ts
 var BLANK = { width: 800, height: 450, background: "#ffffff", nodes: [] };
 var AnimationEditorController = class {
@@ -1924,10 +2232,29 @@ var MS = (what) => ({ type: "number", minimum: 0, description: `${what} in milli
 var FRACTION = (what) => ({ type: "number", minimum: 0, maximum: 1, description: what });
 var POINT = (what) => object({ x: { type: "number", description: "Document units." }, y: { type: "number", description: "Document units." } }, ["x", "y"], what);
 var EASE = {
-  description: `Easing: a preset (${ANIMATION_EASING_PRESETS.join(", ")}) or { "type": "cubic-bezier", "x1", "y1", "x2", "y2" }. Default: a cubic ease-out for entrances, cubic ease-in-out for moves.`,
+  description: `Easing: a preset (${ANIMATION_EASING_PRESETS.join(", ")}), { "type": "cubic-bezier", "x1", "y1", "x2", "y2" }, { "type": "spring", \u2026 } or { "type": "elastic", \u2026 }. The spring presets are Figma's: gentle, quick, bouncy, slow. A command with a spring and no "duration" lasts until the spring settles. Default: a cubic ease-out for entrances, cubic ease-in-out for moves.`,
   anyOf: [
     { type: "string", enum: [...ANIMATION_EASING_PRESETS] },
-    object({ type: { const: "cubic-bezier", description: "Curve kind." }, x1: { type: "number", description: "Out handle x (0\u20131)." }, y1: { type: "number", description: "Out handle y." }, x2: { type: "number", description: "In handle x (0\u20131)." }, y2: { type: "number", description: "In handle y." } }, ["type", "x1", "y1", "x2", "y2"])
+    object({ type: { const: "cubic-bezier", description: "Curve kind." }, x1: { type: "number", description: "Out handle x (0\u20131)." }, y1: { type: "number", description: "Out handle y." }, x2: { type: "number", description: "In handle x (0\u20131)." }, y2: { type: "number", description: "In handle y." } }, ["type", "x1", "y1", "x2", "y2"]),
+    object(
+      {
+        type: { const: "spring", description: "A damped spring (may overshoot)." },
+        stiffness: { type: "number", exclusiveMinimum: 0, description: "Stiffness (default 170; quick 300, bouncy 600)." },
+        damping: { type: "number", minimum: 0, description: "Damping (default 26; lower bounces more)." },
+        mass: { type: "number", exclusiveMinimum: 0, description: "Mass (default 1)." },
+        velocity: { type: "number", description: "Starting speed, in changes per second (default 0)." }
+      },
+      ["type"]
+    ),
+    object(
+      {
+        type: { const: "elastic", description: "A decaying wobble." },
+        amplitude: { type: "number", minimum: 0, description: "Overshoot factor (default 1)." },
+        period: { type: "number", exclusiveMinimum: 0, description: "Wobble period as a fraction of the length (default 0.3)." },
+        mode: { type: "string", enum: ["out", "in", "in-out"], description: "Where it wobbles (default out)." }
+      },
+      ["type"]
+    )
   ]
 };
 var BASE = {
@@ -1937,7 +2264,10 @@ var BASE = {
   stagger: MS("Start each further target this much later (default 0)"),
   with: { type: "string", enum: ["after", "previous"], description: '"after" (default) starts when the commands before it finish; "previous" starts together with the command before.' },
   ease: EASE,
-  note: { type: "string", description: "Why this command is here, in a few words." }
+  note: { type: "string", description: "Why this command is here, in a few words." },
+  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: "loop (default) restarts each cycle, mirror plays every other one backwards, offset carries on from where the last ended (rotate by 90 with repeat 4 makes a full turn)." },
+  steps: { type: "number", exclusiveMinimum: 0, maximum: 120, description: `Stepped time: hold on a grid of this many frames per second (12 = "on twos"). Default: the scene's steps, else smooth.` }
 };
 var command = (type, description, extra = {}, required = []) => object({ type: { const: type, description }, ...BASE, ...extra }, ["type", "targets", ...required], description);
 var MOTION_COMMAND_SCHEMA = {
@@ -1963,7 +2293,7 @@ var MOTION_COMMAND_SCHEMA = {
     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).") }),
     command("move", "Moves targets by an offset or so their centre lands on a point.", { by: POINT("Offset in document units."), to: POINT("Point (document coordinates) for the centre.") }),
     command("rotate", "Turns targets about their centre (degrees, clockwise).", { by: { type: "number", description: "Degrees to turn by." }, to: { type: "number", description: "Angle to turn to, in degrees from rest." } }),
-    command("scale", "Scales targets about their centre (1 = rest size).", { to: { description: "A factor, or { x, y } factors.", anyOf: [{ type: "number" }, POINT("Factors per axis.")] } }, ["to"]),
+    command("scale", "Scales targets about their centre (1 = rest size).", { 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"]),
     command("fade", "Changes opacity.", { to: FRACTION("Opacity at the end (0\u20131).") }, ["to"]),
     command("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())." },
@@ -2009,11 +2339,12 @@ var MOTION_COMMAND_SCHEMA = {
     )
   ]
 };
+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") }, ["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") }, ["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: 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"])
   ]
 };
 var SHOT_FIELDS = {
@@ -2039,6 +2370,7 @@ var SETTINGS = {
   description: { type: ["string", "null"], description: "What it shows; null clears." },
   loop: { type: "string", enum: ["none", "loop", "ping-pong"], description: "Playback past the end (default none)." },
   fps: { type: "number", minimum: 1, maximum: 120, description: "Sampling rate for exports (default 30)." },
+  steps: { anyOf: [{ type: "number", exclusiveMinimum: 0, maximum: 120 }, { type: "null" }], description: 'Stepped time for every command without its own: changes hold on a grid of this many frames per second (12 = "on twos" at 24 fps) for a hand-drawn look; null makes it smooth again (default).' },
   target: { anyOf: [{ type: "array", items: { type: "number", minimum: 0 }, minItems: 2, maxItems: 2 }, { type: "null" }], description: "Wanted length [min, max] in seconds; null clears." }
 };
 var EDIT_OP = {
@@ -2217,6 +2549,7 @@ 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 FLAIR_DESCRIPTION = "The Flair version to export for (default 0.39): springs and stepped time need 0.39, behaviours 0.38, cubic-bezier curves 0.36; older versions get those sampled into linear steps.";
   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",
@@ -2225,10 +2558,11 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     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 },
-      behaviors: { type: "boolean", description: BEHAVIORS_DESCRIPTION }
+      behaviors: { type: "boolean", description: BEHAVIORS_DESCRIPTION },
+      flair: { type: "string", pattern: "^\\d+\\.\\d+(\\.\\d+)?$", description: FLAIR_DESCRIPTION }
     }),
     annotations: { title: "Export as Flair vector motion", ...READ },
-    handler: ({ fps, curves, behaviors }) => controller.toFlairMotion({ ...fps ? { fps } : {}, ...curves === void 0 ? {} : { curves }, ...behaviors === void 0 ? {} : { behaviors } })
+    handler: ({ fps, curves, behaviors, flair }) => controller.toFlairMotion({ ...fps ? { fps } : {}, ...curves === void 0 ? {} : { curves }, ...behaviors === void 0 ? {} : { behaviors }, ...flair ? { flair } : {} })
   };
   const exportFlairEffect = {
     name: "export_flair_effect",
@@ -2241,7 +2575,8 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       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 },
-      behaviors: { type: "boolean", description: BEHAVIORS_DESCRIPTION }
+      behaviors: { type: "boolean", description: BEHAVIORS_DESCRIPTION },
+      flair: { type: "string", pattern: "^\\d+\\.\\d+(\\.\\d+)?$", description: FLAIR_DESCRIPTION }
     }),
     annotations: { title: "Export as a Flair effect", ...READ },
     handler: (args) => controller.toFlairEffect(args)
@@ -2262,6 +2597,34 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return apply({ op: "set_artwork", artwork }, "Replace artwork", (s) => ({ elements: describeMotionElements(s) }));
     }
   };
+  const importFlairEffect = {
+    name: "import_flair_effect",
+    title: "Import a Flair effect",
+    description: "Replaces the whole animation with a Flair vector effect or SvgMotion (one undo step): its SVG becomes the artwork, {{name: color}} placeholders become colour controls, and each Flair step becomes a shot of commands (fade, enter, style, move, rotate, scale, draw, follow, pulse, shake, teeter, wave, wiggle, color-pulse). Returns the shots, the elements, notes on anything not carried over and the issues. With dry_run it only reports what the import would give.",
+    inputSchema: object(
+      {
+        effect: { type: "object", description: 'A Flair catalog vector effect { kind: "vector", id, name, motion: { svg, animate }, hold?, presets? }. Give this or "motion".' },
+        motion: { type: "object", description: 'A Flair SvgMotion { svg, animate }. Give this or "effect".' },
+        name: { type: "string", minLength: 1, description: `Name for the scene (default: the effect's id, else "from-flair").` },
+        dry_run: { type: "boolean", description: "Report without replacing anything (default false)." }
+      },
+      []
+    ),
+    annotations: { title: "Import a Flair effect", ...DESTRUCTIVE },
+    handler: ({ effect, motion, name, dry_run = false }) => {
+      if (effect === void 0 === (motion === void 0)) throw new Error('Give exactly one of "effect" (a Flair vector effect) or "motion" (a Flair SvgMotion). Nothing was changed.');
+      let result;
+      try {
+        result = effect !== void 0 ? fromFlairVectorEffect(effect, name ? { name } : {}) : fromFlairSvgMotion(motion, name ? { name } : {});
+      } catch (error) {
+        throw new Error(`The Flair effect could not be imported: ${error.message} Nothing was changed.`);
+      }
+      const report = { notes: result.notes, issues: issueSummary(result.issues), shots: describeMotionShots(result.scene).map(({ id, start, end, commands }) => ({ id, start, end, commands: commands.length })) };
+      if (dry_run) return { dry_run: true, ...report, hint: "Nothing was replaced; call again without dry_run to import." };
+      const applied = controller.apply({ op: "replace_scene", scene: result.scene }, "Import Flair effect");
+      return outcome(applied, applied.ok ? { ...report, elements: describeMotionElements(result.scene) } : {});
+    }
+  };
   const insertShots = {
     name: "insert_shots",
     title: "Add shots",
@@ -2344,7 +2707,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
   const setSettings = {
     name: "set_animation_settings",
     title: "Change animation settings",
-    description: "Sets the name, description, loop mode, export frame rate or target length. Returns the timing.",
+    description: "Sets the name, description, loop mode, export frame rate, stepped time or target length. Returns the timing.",
     inputSchema: object(SETTINGS),
     annotations: { title: "Change animation settings", ...WRITE_IDEMPOTENT },
     handler: (args) => apply({ op: "set_settings", ...args }, "Change settings")
@@ -2423,7 +2786,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     }
   };
   const reads = [getAnimation, getShot, findElements, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, seekAnimation];
-  const writes = [setArtworkSvg, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
+  const writes = [setArtworkSvg, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
   return {
     id: options.id ?? "animation",
     namespace: options.namespace,
@@ -2458,11 +2821,14 @@ Commands
 - 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).
+- 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.
+- Springs ("spring-gentle", "spring-quick", "spring-bouncy", "spring-slow" or { "type": "spring", \u2026 }) feel physical; leave "duration" out and the spring sets it.
+- "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.
 - 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
-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).
+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 to start from a Flair effect and edit it).
 2. Plan a few shots, each one idea. Add them with insert_shots, or edit_animation to make several edits as one step (dry_run first when unsure).
 3. check_animation and fix every error and warning; render_animation_frame (shot + "end") to look at the result.
 4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.
@@ -2472,6 +2838,7 @@ export {
   ANIMATION_EDITOR_AGENT_INSTRUCTIONS,
   AnimationEditorController,
   FLAIR_EASES,
+  FLAIR_EXPORT_VERSION,
   MOTION_CAMERA_MS,
   MOTION_COMMAND_SCHEMA,
   MOTION_COMMAND_TYPES,
@@ -2489,6 +2856,7 @@ export {
   MOTION_IRIS_SHAPES,
   MOTION_ISSUE_CODES,
   MOTION_MIN_CHANGE_MS,
+  MOTION_REPEAT_MODES,
   MOTION_SPLIT_ORIENTATIONS,
   MotionSceneFormatError,
   activeSegment,
@@ -2502,15 +2870,20 @@ export {
   describeMotionElements,
   describeMotionShots,
   fitMotionRect,
+  flairAtLeast,
   flairCurveFor,
   flairEaseFor,
   freshShotId,
+  fromFlairSvgMotion,
+  fromFlairVectorEffect,
   indexMotionNodes,
   interpolateMotionValue,
   isMotionCommand,
   isMotionShot,
   motionClipAttrs,
   motionCommandDuration,
+  motionCommandRepeat,
+  motionCycleDuration,
   motionFlairPrimitive,
   motionFollowRoute,
   motionFrameAt,