@pixerate/editor 0.67.1 → 0.69.0

package/dist/animation-editor/index.js

@@ -56,6 +56,7 @@ import {
 
 // src/animation-editor/types.ts
 var MOTION_TRIGGERS = ["click", "hover", "press", "scroll"];
+var MOTION_CLIP_TARGET = "$";
 var MOTION_COMMAND_TYPES = [
   "enter",
   "exit",
@@ -67,6 +68,7 @@ var MOTION_COMMAND_TYPES = [
   "style",
   "morph",
   "match",
+  "play",
   "follow",
   "pulse",
   "shake",
@@ -94,6 +96,8 @@ var MOTION_DEFAULT_DURATIONS = {
   style: 500,
   morph: 900,
   match: 900,
+  /** A clip's length comes from its commands (this is only a fallback). */
+  play: 600,
   follow: 1400,
   pulse: 600,
   shake: 500,
@@ -137,6 +141,7 @@ var MOTION_ISSUE_CODES = {
   "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-clip": { severity: "error", wording: "A play command names a clip the scene does not have." },
   "unknown-shape": { severity: "error", wording: "A morph names a shape the artwork does not have." },
   "match-self": { severity: "error", wording: "A match turns a group into itself or into a group it holds (or that holds it)." },
   "match-unpaired": { severity: "note", wording: `Parts of a match's "into" group have no partner in the target, so they do not appear.` },
@@ -214,7 +219,7 @@ ${problems.map((p) => `- ${p}`).join("\n")}`);
     this.problems = problems;
   }
 };
-var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "loop", "trigger", "fps", "steps", "beat", "narration", "target", "controls", "presets"];
+var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "clips", "loop", "trigger", "fps", "steps", "beat", "narration", "target", "controls", "presets"];
 var SHOT_KEYS = ["id", "label", "camera", "at", "run", "hold", "speed"];
 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"];
@@ -222,13 +227,14 @@ 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", "blend"],
+  move: [...BASE_KEYS, "by", "to", "via", "pacing", "blend"],
   rotate: [...BASE_KEYS, "by", "to", "blend"],
   scale: [...BASE_KEYS, "to", "geometric", "blend"],
   fade: [...BASE_KEYS, "to"],
   style: [...BASE_KEYS, "fill", "stroke", "strokeWidth"],
   morph: [...BASE_KEYS, "into"],
   match: [...BASE_KEYS, "into"],
+  play: ["type", "targets", "delay", "stagger", "with", "note", "clip", "speed"],
   follow: [...BASE_KEYS, "path", "rotate", "from", "to"],
   pulse: [...BASE_KEYS, "amount", "count", "blend"],
   shake: [...BASE_KEYS, "amount", "count", "axis", "blend"],
@@ -303,6 +309,9 @@ function commandShapeProblems(command2, where) {
       if (command2.by !== void 0 && command2.to !== void 0) p(`give "by" or "to", not both.`);
       if (command2.by !== void 0 && !isPoint(command2.by)) p(`"by" must be { "x": number, "y": number }.`);
       if (command2.to !== void 0 && !isPoint(command2.to)) p(`"to" must be { "x": number, "y": number }.`);
+      if (command2.via !== void 0 && !(Array.isArray(command2.via) && command2.via.length > 0 && command2.via.length <= 64 && command2.via.every(isPoint))) p(`"via" must be a list of 1 to 64 points { "x": number, "y": number } (document units).`);
+      if (command2.pacing !== void 0 && command2.pacing !== "even" && command2.pacing !== "equal") p(`"pacing" must be "even" (steady speed) or "equal" (each leg the same time).`);
+      if (command2.pacing !== void 0 && command2.via === void 0) p(`"pacing" goes with "via".`);
       break;
     case "rotate":
       if (command2.by === void 0 && command2.to === void 0) p(`give "by" or "to" (degrees).`);
@@ -323,6 +332,10 @@ function commandShapeProblems(command2, where) {
       if (command2.stroke !== void 0 && typeof command2.stroke !== "string") p(`"stroke" must be a CSS colour.`);
       if (command2.strokeWidth !== void 0 && !(isNum(command2.strokeWidth) && command2.strokeWidth >= 0)) p(`"strokeWidth" must be a number \u2265 0.`);
       break;
+    case "play":
+      if (typeof command2.clip !== "string" || !command2.clip) p(`"clip" must be the name of one of the scene's clips.`);
+      if (command2.speed !== void 0 && !(isNum(command2.speed) && command2.speed >= 0.05 && command2.speed <= 20)) p(`"speed" must be a number from 0.05 to 20 (2 plays the clip twice as fast).`);
+      break;
     case "morph":
     case "match":
       if (typeof command2.into !== "string" || !command2.into) p(`"into" must be the id of a ${type === "match" ? "group to become" : "node whose shape to take"}.`);
@@ -360,6 +373,25 @@ function commandShapeProblems(command2, where) {
   }
   return problems;
 }
+function clipsShapeProblems(clips) {
+  if (!isObject(clips)) return ['Scene: "clips" must be an object of named clips { "pop": { "run": [ \u2026 ] } }.'];
+  const problems = [];
+  for (const [name, clip] of Object.entries(clips)) {
+    const where = `Clip "${name}"`;
+    if (!/^[A-Za-z_][\w-]*$/.test(name)) problems.push(`${where}: a clip name is letters, digits, "_" or "-" (e.g. "pop-in").`);
+    if (!isObject(clip) || !Array.isArray(clip.run)) {
+      problems.push(`${where} must be { "description"?, "run": [commands] }.`);
+      continue;
+    }
+    unknownKeys(clip, ["description", "run"], where, problems);
+    if (clip.description !== void 0 && typeof clip.description !== "string") problems.push(`${where}: "description" must be a string.`);
+    clip.run.forEach((command2, i) => {
+      if (isObject(command2) && command2.type === "play") problems.push(`${where}, command ${i + 1}: a clip cannot play another clip; copy its commands in instead.`);
+      else problems.push(...commandShapeProblems(command2, `${where}, command ${i + 1}`));
+    });
+  }
+  return problems;
+}
 function shotShapeProblems(shot, where) {
   if (!isObject(shot)) return [`${where} must be an object.`];
   const problems = [];
@@ -407,6 +439,7 @@ function motionSceneShapeProblems(input) {
   const art = input.artwork;
   if (!isObject(art) || !isNum(art.width) || !isNum(art.height) || !(art.width > 0) || !(art.height > 0) || !Array.isArray(art.nodes))
     problems.push('Scene: "artwork" must be a vector document { width, height, nodes }.');
+  if (input.clips !== void 0) problems.push(...clipsShapeProblems(input.clips));
   if (input.trigger !== void 0 && !MOTION_TRIGGERS.includes(input.trigger)) problems.push(`Scene: "trigger" must be one of ${MOTION_TRIGGERS.join(", ")}.`);
   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.');
@@ -503,6 +536,45 @@ function matchMotionNodes(from, into) {
   return out;
 }
 
+// src/animation-editor/smooth.ts
+function smoothMotionLegs(times, values) {
+  const n = values.length;
+  const slope = new Array(n).fill(0);
+  const secant = (i) => (values[i + 1] - values[i]) / Math.max(1e-9, times[i + 1] - times[i]);
+  for (let i = 1; i < n - 1; i++) {
+    const a = secant(i - 1);
+    const b = secant(i);
+    if (a * b <= 0) continue;
+    const ha = times[i] - times[i - 1];
+    const hb = times[i + 1] - times[i];
+    slope[i] = 3 * (ha + hb) / ((2 * hb + ha) / a + (hb + 2 * ha) / b);
+  }
+  const legs = [];
+  for (let i = 0; i + 1 < n; i++) {
+    const dt = times[i + 1] - times[i];
+    const dv = values[i + 1] - values[i];
+    if (Math.abs(dv) < 1e-9) {
+      legs.push({ start: times[i], end: times[i + 1], from: values[i], to: values[i + 1], ease: "linear" });
+      continue;
+    }
+    const y1 = slope[i] * dt / (3 * dv);
+    const y2 = 1 - slope[i + 1] * dt / (3 * dv);
+    legs.push({ start: times[i], end: times[i + 1], from: values[i], to: values[i + 1], ease: { type: "cubic-bezier", x1: 1 / 3, y1, x2: 2 / 3, y2 } });
+  }
+  return legs;
+}
+function smoothMotionTimes(points, start, duration, pacing = "even") {
+  const legs = points.slice(1).map((p, i) => pacing === "equal" ? 1 : Math.hypot(p.x - points[i].x, p.y - points[i].y));
+  const total = legs.reduce((a, b) => a + b, 0) || legs.length || 1;
+  const times = [start];
+  let acc = 0;
+  for (const l of legs) {
+    acc += total > 0 ? l : 1;
+    times.push(start + duration * acc / total);
+  }
+  return times;
+}
+
 // src/animation-editor/compile.ts
 var indexCache = /* @__PURE__ */ new WeakMap();
 function indexMotionNodes(nodes) {
@@ -751,8 +823,38 @@ function motionCommandRepeat(command2) {
 function motionCommandDuration(command2, scene, target) {
   return motionCycleDuration(command2, scene, target) * motionCommandRepeat(command2);
 }
+function motionClipLayout(scene, clip, target, speed = 1) {
+  const run = scene.clips?.[clip]?.run;
+  if (!run) return { items: [], length: 0 };
+  const f = speed > 0 && Number.isFinite(speed) ? 1 / speed : 1;
+  const items = [];
+  let runEnd = 0;
+  let prevStart = 0;
+  run.forEach((raw, i) => {
+    const base = raw.with === "previous" && i > 0 ? prevStart : runEnd;
+    if (raw.type === "wait") {
+      prevStart = base;
+      runEnd = Math.max(runEnd, base + raw.duration * f);
+      return;
+    }
+    if (raw.type === "play") return;
+    const command2 = { ...raw, targets: raw.targets.map((t) => t === MOTION_CLIP_TARGET ? target : t) };
+    const begin = base + (command2.delay ?? 0) * f;
+    let end = begin;
+    command2.targets.forEach((t, k) => {
+      const cycle = motionCycleDuration(command2, scene, t) * f;
+      const s = begin + k * (command2.stagger ?? 0) * f;
+      items.push({ command: command2, target: t, start: s, cycle });
+      end = Math.max(end, s + cycle * motionCommandRepeat(command2));
+    });
+    prevStart = begin;
+    runEnd = Math.max(runEnd, end);
+  });
+  return { items, length: runEnd };
+}
 function motionCycleDuration(command2, scene, target) {
   if (command2.type === "wait") return command2.duration;
+  if (command2.type === "play") return motionClipLayout(scene, command2.clip, target ?? MOTION_CLIP_TARGET, command2.speed).length;
   if (command2.duration !== void 0) return command2.duration;
   if (command2.ease !== void 0) {
     const ease = resolveEasing(command2.ease);
@@ -764,6 +866,7 @@ function motionCycleDuration(command2, scene, target) {
     const ms = length * MOTION_DRAW_MS_PER_UNIT;
     return Math.round(Math.min(MOTION_DRAW_RANGE[1], Math.max(MOTION_DRAW_RANGE[0], ms)));
   }
+  if (command2.type === "move" && command2.via?.length) return MOTION_DEFAULT_DURATIONS.move + 400 * command2.via.length;
   return MOTION_DEFAULT_DURATIONS[command2.type];
 }
 var MOTION_EASE_OUT = { type: "cubic-bezier", x1: 1 / 3, y1: 1, x2: 2 / 3, y2: 1 };
@@ -841,6 +944,19 @@ function compileMotionScene(scene) {
     const shot = scene.shots[timing.shotIndex];
     const command2 = shot.run[timing.command];
     if (command2.type === "wait") continue;
+    if (command2.type === "play") {
+      const f = motionShotTimeScale(shot);
+      command2.targets.forEach((target, k) => {
+        if (!nodes.has(target)) return;
+        const at = timing.start + k * (command2.stagger ?? 0) * f;
+        for (const item of motionClipLayout(scene, command2.clip, target, (command2.speed ?? 1) / f).items) {
+          const entry = nodes.get(item.target);
+          if (!entry) continue;
+          jobs.push({ start: at + item.start, order: order++, run: () => compileRepeated(item.command, item.target, entry, at + item.start, item.cycle, timing) });
+        }
+      });
+      continue;
+    }
     command2.targets.forEach((target, k) => {
       const entry = nodes.get(target);
       if (!entry) return;
@@ -962,6 +1078,20 @@ function compileMotionScene(scene) {
           dx = target.x - (entry.center.x + num("x"));
           dy = target.y - (entry.center.y + num("y"));
         }
+        if (command2.via?.length) {
+          const inv = invertMatrix(entry.parentWorld);
+          const x0 = num("x");
+          const y0 = num("y");
+          const add = command2.blend === "add";
+          const offsets = [{ x: 0, y: 0 }, ...command2.via.map((p) => applyMatrix(inv, p)).map((p) => ({ x: p.x - entry.center.x - x0, y: p.y - entry.center.y - y0 })), { x: dx, y: dy }];
+          const times = smoothMotionTimes(offsets, start, end - start, command2.pacing ?? "even");
+          for (const axis of ["x", "y"]) {
+            const base = add ? 0 : axis === "x" ? x0 : y0;
+            for (const leg of smoothMotionLegs(times, offsets.map((o) => o[axis])))
+              seg(axis, base + leg.to, leg.ease, leg.start, leg.end, { from: base + leg.from, ...add ? { blend: "add" } : {} });
+          }
+          break;
+        }
         if (command2.blend === "add") {
           seg("x", dx, e, start, end, { from: 0, blend: "add" });
           seg("y", dy, e, start, end, { from: 0, blend: "add" });
@@ -1426,6 +1556,8 @@ 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);
+      if (command2.type === "play" && !scene.clips?.[command2.clip])
+        issues.push(motionIssue("unknown-clip", `There is no clip ${namedWithSuggestion(command2.clip, Object.keys(scene.clips ?? {}))}; define it with set_animation_clip.`, where));
       if (command2.type === "match" && known(command2.into, "unknown-shape", "group", where)) {
         const into = nodes.get(command2.into);
         for (const id of targets) {
@@ -1498,6 +1630,12 @@ function checkMotionScene(scene) {
       }
     });
   });
+  for (const [name, clip] of Object.entries(scene.clips ?? {}))
+    for (const command2 of clip.run)
+      if (command2.type !== "wait") {
+        for (const id of command2.targets)
+          if (id !== MOTION_CLIP_TARGET && !nodes.has(id)) issues.push(motionIssue("unknown-target", `Clip "${name}" names ${namedWithSuggestion(id, [...nodes.keys()])}, which the artwork does not have; use "$" for the node the clip is played on.`, { ids: [id] }));
+      }
   if (scene.trigger) {
     if ((scene.loop ?? "none") !== "none") issues.push(motionIssue("trigger-loop", `The scene plays on ${scene.trigger}, so its "${scene.loop}" loop does not apply; set loop to "none" or remove the trigger.`, {}));
     if (scene.trigger === "click") {
@@ -1581,6 +1719,7 @@ var MOTION_EDIT_OPS = [
   "move_command",
   "set_artwork",
   "set_controls",
+  "set_clip",
   "replace_scene"
 ];
 var EditError = class extends Error {
@@ -1637,6 +1776,23 @@ function applyOne(scene, edit) {
       else if (edit.target !== void 0) next.target = edit.target;
       return next;
     }
+    case "set_clip": {
+      if (typeof edit.name !== "string" || !edit.name) fail('Give the clip a "name".');
+      const clips = { ...scene.clips ?? {} };
+      if (edit.clip === null) {
+        if (!clips[edit.name]) fail(`There is no clip ${namedWithSuggestion(edit.name, Object.keys(clips))} to delete.`);
+        const playing = scene.shots.filter((s) => s.run.some((c) => c.type === "play" && c.clip === edit.name)).map((s) => `"${s.id}"`);
+        if (playing.length) fail(`Clip "${edit.name}" is played in shot${playing.length > 1 ? "s" : ""} ${playing.join(", ")}; remove those play commands first.`);
+        delete clips[edit.name];
+      } else {
+        const problems = clipsShapeProblems({ [edit.name]: edit.clip });
+        if (problems.length) fail(problems.join(" "));
+        clips[edit.name] = edit.clip;
+      }
+      const next = { ...scene, clips };
+      if (!Object.keys(clips).length) delete next.clips;
+      return next;
+    }
     case "insert_shots": {
       if (!edit.shots.length) fail("Give at least one shot.");
       edit.shots.forEach((shot, i) => {
@@ -2937,7 +3093,7 @@ var MOTION_COMMAND_SCHEMA = {
       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).") }),
-    command("move", "Moves targets by an offset or so their centre lands on a point.", { blend: BLEND("replace"), by: POINT("Offset in document units."), to: POINT("Point (document coordinates) for the centre.") }),
+    command("move", "Moves targets by an offset or so their centre lands on a point.", { via: { type: "array", items: POINT("A point the centre passes through."), minItems: 1, maxItems: 64, description: 'Waypoints (document units) the centre passes through on the way to "to" or "by", smoothly (velocity carries through each) and without overshooting any. Default length 700 ms + 400 per waypoint.' }, pacing: { type: "string", enum: ["even", "equal"], description: "With via: even (default) keeps the speed steady along the path; equal gives each stretch the same time." }, blend: BLEND("replace"), by: POINT("Offset in document units."), to: POINT("Point (document coordinates) for the centre.") }),
     command("rotate", "Turns targets about their centre (degrees, clockwise).", { blend: BLEND("replace"), by: { type: "number", description: "Degrees to turn by." }, to: { type: "number", description: "Angle to turn to, in degrees from rest." } }),
     command("scale", "Scales targets about their centre (1 = rest size).", { blend: BLEND("replace"), to: { description: "A factor, or { x, y } factors.", anyOf: [{ type: "number" }, POINT("Factors per axis.")] }, geometric: { type: "boolean", description: "Grow by a steady factor, which reads as an even zoom (default false)." } }, ["to"]),
     command("fade", "Changes opacity.", { to: FRACTION("Opacity at the end (0\u20131).") }, ["to"]),
@@ -2946,6 +3102,20 @@ var MOTION_COMMAND_SCHEMA = {
       stroke: { type: "string", description: "CSS colour (hex, rgb(), rgba())." },
       strokeWidth: { type: "number", minimum: 0, description: "Document units." }
     }),
+    object(
+      {
+        type: { const: "play", description: 'Plays a clip (set_animation_clip) on the targets: its commands, with "$" standing for each target, timed as in a shot.' },
+        targets: NODE_IDS,
+        clip: { type: "string", minLength: 1, description: "The clip's name (get_animation lists them)." },
+        speed: { type: "number", minimum: 0.05, maximum: 20, description: "Play it this many times as fast (default 1)." },
+        delay: BASE.delay,
+        stagger: BASE.stagger,
+        with: BASE.with,
+        note: BASE.note
+      },
+      ["type", "targets", "clip"],
+      "Plays a clip on the targets."
+    ),
     command("match", `Smart Animate: tweens a group into another group (usually hidden), part by part. Parts pair by name, then by id with the group ids taken out (card-a-title \u2194 card-b-title), then by kind in order; each takes its partner's shape, paint and place. Unpaired parts fade out; parts of "into" with no partner do not appear (check_animation lists them).`, { into: { type: "string", minLength: 1, description: "Id of the group to become." } }, ["into"]),
     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.", {
@@ -3154,6 +3324,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
         ...s.target ? { target: s.target } : {},
         ...includeElements ? { elements: describeMotionElements(s) } : {},
         shots: describeMotionShots(s),
+        ...s.clips ? { clips: Object.fromEntries(Object.entries(s.clips).map(([name, c]) => [name, { ...c.description ? { description: c.description } : {}, commands: c.run.length, length: Math.round(motionClipLayout(s, name, "$").length) }])) } : {},
         ...s.controls ? { controls: s.controls } : {},
         ...s.presets ? { presets: s.presets } : {},
         issues: issueSummary(controller.getState().issues),
@@ -3399,6 +3570,68 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return apply(edits, "Fit to length", () => report);
     }
   };
+  const setClip = {
+    name: "set_animation_clip",
+    title: "Define a reusable clip",
+    description: `Defines, replaces or (with clip null) deletes a named clip: commands written against the target "$" that a play command plays on any node, e.g. a "pop-settle" or "attention" used many times. One undo step. Returns the clip's length and the timing.`,
+    inputSchema: object(
+      {
+        name: { type: "string", pattern: "^[A-Za-z_][\\w-]*$", description: 'Clip name, e.g. "pop-settle".' },
+        clip: {
+          anyOf: [object({ description: { type: "string", description: "What it does, in a few words." }, run: { type: "array", items: MOTION_COMMAND_SCHEMA, minItems: 1, description: 'Commands, timed as in a shot; target "$" for the node it is played on. Clips cannot play clips.' } }, ["run"]), { type: "null" }],
+          description: "The clip, or null to delete it (refused while a play command uses it)."
+        }
+      },
+      ["name", "clip"]
+    ),
+    annotations: { title: "Define a reusable clip", ...WRITE_IDEMPOTENT },
+    handler: ({ name, clip }) => apply({ op: "set_clip", name, clip }, clip === null ? "Delete clip" : "Set clip", (s) => clip === null ? { deleted: name } : { clip: name, length: Math.round(motionClipLayout(s, name, "$").length) })
+  };
+  const copyAnimation = {
+    name: "copy_animation",
+    title: "Copy one node's animation to others",
+    description: 'Copies every command that animates "from" (in all shots, or the ones given) so it also animates "to": each copy goes right after its original and starts with it. One undo step. Returns how many commands were copied per shot. For motion you will reuse often, a clip (set_animation_clip + play) is tidier.',
+    inputSchema: object(
+      {
+        from: { type: "string", minLength: 1, description: "Element id whose commands to copy." },
+        to: { type: "array", items: { type: "string", minLength: 1 }, minItems: 1, description: "Element ids to give the same motion." },
+        shots: { type: "array", items: SHOT_ID, description: "Only these shots (default all)." },
+        stagger: MS("Start each copy this much after the one before (default 0)")
+      },
+      ["from", "to"]
+    ),
+    annotations: { title: "Copy one node's animation to others", ...WRITE },
+    handler: ({ from, to, shots, stagger }) => {
+      const s = scene();
+      const ids = describeMotionElements(s).map((e) => e.id);
+      for (const id of [from, ...to]) if (!ids.includes(id)) throw new Error(`There is no element ${namedWithSuggestion(id, ids)}. Nothing was changed.`);
+      if (to.includes(from)) throw new Error(`"to" includes "${from}" itself; give other elements. Nothing was changed.`);
+      const only = shots ? new Set(shots) : null;
+      if (only) {
+        for (const id of only) if (!s.shots.some((x) => x.id === id)) throw new Error(`There is no shot ${namedWithSuggestion(id, s.shots.map((x) => x.id))}. Nothing was changed.`);
+      }
+      const copied = {};
+      const edits = [];
+      for (const shot of s.shots) {
+        if (only && !only.has(shot.id)) continue;
+        const run = [];
+        let n = 0;
+        for (const c of shot.run) {
+          run.push(c);
+          if (c.type === "wait" || !c.targets.includes(from)) continue;
+          const { delay: _delay, ...rest } = c;
+          run.push({ ...rest, targets: to, with: "previous", ...stagger ? { stagger } : {} });
+          n++;
+        }
+        if (n) {
+          copied[shot.id] = n;
+          edits.push({ op: "update_shot", shot: shot.id, set: { run } });
+        }
+      }
+      if (!edits.length) throw new Error(`No command animates "${from}"${only ? " in those shots" : ""}; nothing to copy.`);
+      return apply(edits, "Copy animation", () => ({ copied }));
+    }
+  };
   const insertShots = {
     name: "insert_shots",
     title: "Add shots",
@@ -3575,7 +3808,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     }
   };
   const reads = [getAnimation, getShot, findElements, getMotionPath, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation];
-  const writes = [setArtworkSvg, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, moveCommand, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
+  const writes = [setArtworkSvg, setClip, copyAnimation, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, moveCommand, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
   return {
     id: options.id ?? "animation",
     namespace: options.namespace,
@@ -3607,6 +3840,8 @@ 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.
+- Reuse motion: set_animation_clip defines a clip (commands targeting "$"), and { "type": "play", "clip": name, "targets": [...] } plays it on any nodes (with stagger and speed). copy_animation gives other nodes one node's motion.
+- move takes "via" waypoints for a curved, smooth path that passes exactly through each point (steady speed by default); use it instead of chaining moves, which stop at each point.
 - 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); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); follow moves along a path node (with "rotate", moves made meanwhile turn with the path).
 - 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).
@@ -3745,6 +3980,10 @@ function defaultMotionCommand(type, targets, scene) {
       const into = other((e) => e.node.type === "group" && e.node.visible === false) ?? other((e) => e.node.type === "group");
       return into ? { type, ...base, into } : { error: "Match needs another group to become; group the end state (it can stay hidden)." };
     }
+    case "play": {
+      const clip = Object.keys(scene.clips ?? {})[0];
+      return clip ? { type, ...base, clip } : { error: 'Play needs a clip; define one first (set_animation_clip), with "$" as its target.' };
+    }
     case "follow": {
       const path = other((e) => e.node.type === "path" && e.node.visible === false) ?? other((e) => e.node.type === "path");
       return path ? { type, ...base, path } : { error: "Follow needs a path to travel along; draw one (it can stay hidden)." };
@@ -3908,6 +4147,7 @@ export {
   MOTION_ADDITIVE_PROPERTIES,
   MOTION_BLENDS,
   MOTION_CAMERA_MS,
+  MOTION_CLIP_TARGET,
   MOTION_COMMAND_SCHEMA,
   MOTION_COMMAND_TYPES,
   MOTION_DEFAULT_DURATIONS,
@@ -3934,6 +4174,7 @@ export {
   applyMotionControlValues,
   applyMotionEdits,
   checkMotionScene,
+  clipsShapeProblems,
   commandShapeProblems,
   compileMotionScene,
   createAnimationEditorToolProvider,
@@ -3962,6 +4203,7 @@ export {
   motionBeatAt,
   motionBeatTime,
   motionClipAttrs,
+  motionClipLayout,
   motionCommandDuration,
   motionCommandFields,
   motionCommandRepeat,
@@ -4012,6 +4254,8 @@ export {
   segmentProgress,
   segmentValue,
   shotShapeProblems,
+  smoothMotionLegs,
+  smoothMotionTimes,
   suggestName,
   toFlairEffectDocument,
   toFlairSvgMotion,