@pixerate/editor 0.68.0 → 0.70.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,14 +219,15 @@ ${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"];
+var DRAW_ORDER_KEYS = ["order", "pace", "align", "sortBy", "origin"];
 var COMMAND_KEYS = {
-  enter: [...BASE_KEYS, "style", "direction", "distance", "scale", "shape", "orientation"],
-  exit: [...BASE_KEYS, "style", "direction", "distance"],
-  draw: [...BASE_KEYS, "from", "to"],
+  enter: [...BASE_KEYS, ...DRAW_ORDER_KEYS, "style", "direction", "distance", "scale", "shape", "orientation"],
+  exit: [...BASE_KEYS, ...DRAW_ORDER_KEYS, "style", "direction", "distance"],
+  draw: [...BASE_KEYS, ...DRAW_ORDER_KEYS, "from", "to", "comet"],
   move: [...BASE_KEYS, "by", "to", "via", "pacing", "blend"],
   rotate: [...BASE_KEYS, "by", "to", "blend"],
   scale: [...BASE_KEYS, "to", "geometric", "blend"],
@@ -229,6 +235,7 @@ var COMMAND_KEYS = {
   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"],
@@ -264,6 +271,14 @@ function commandShapeProblems(command2, where) {
     if (command2[key] !== void 0 && !isNum(command2[key])) p(`"${key}" must be a number.`);
   };
   if (command2.with !== void 0 && command2.with !== "after" && command2.with !== "previous") p(`"with" must be "after" or "previous".`);
+  if (DRAW_ORDER_KEYS.some((k) => command2[k] !== void 0)) {
+    if (type === "enter" && command2.style !== "draw" || type === "exit" && command2.style !== "undraw") p(`"order", "pace", "align", "sortBy" and "origin" go with drawing: style "${type === "enter" ? "draw" : "undraw"}".`);
+    if (command2.order !== void 0 && command2.order !== "together" && command2.order !== "sequence") p(`"order" must be "together" or "sequence" (one stroke after another).`);
+    if (command2.pace !== void 0 && command2.pace !== "time" && command2.pace !== "speed") p(`"pace" must be "time" (each stroke takes the whole time) or "speed" (all at one speed).`);
+    if (command2.align !== void 0 && command2.align !== "start" && command2.align !== "end") p(`"align" must be "start" or "end".`);
+    if (command2.sortBy !== void 0 && command2.sortBy !== "document" && command2.sortBy !== "distance") p(`"sortBy" must be "document" or "distance".`);
+    if (command2.origin !== void 0 && !isPoint(command2.origin)) p(`"origin" must be { "x": number, "y": number } (document units).`);
+  }
   if (command2.note !== void 0 && typeof command2.note !== "string") p(`"note" must be a string.`);
   if (type === "wait") {
     if (!isNum(command2.duration) || command2.duration < 0) p(`"duration" must be a number of milliseconds \u2265 0.`);
@@ -297,6 +312,8 @@ function commandShapeProblems(command2, where) {
     case "draw":
       fraction("from");
       fraction("to");
+      fraction("comet");
+      if (command2.comet !== void 0 && (command2.from !== void 0 || command2.to !== void 0)) p(`"comet" runs the whole path; leave out "from" and "to".`);
       break;
     case "move":
       if (command2.by === void 0 && command2.to === void 0) p(`give "by" (an offset) or "to" (a point).`);
@@ -326,6 +343,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"}.`);
@@ -363,6 +384,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 = [];
@@ -410,6 +450,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.');
@@ -793,8 +834,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);
@@ -884,6 +955,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;
@@ -930,6 +1014,43 @@ function compileMotionScene(scene) {
       return typeof v === "number" ? v : 0;
     };
     const ease = command2.ease;
+    const drawWindows = (s, e, o) => {
+      const order2 = o.order ?? "together";
+      const pace = o.pace ?? "time";
+      if (order2 === "together" && pace === "time") return null;
+      const paths = entry.node.type === "path" ? [entry.node] : collectPathNodes(entry.node);
+      let list = paths.map((p) => {
+        const at = nodes.get(p.id);
+        let first = { x: 0, y: 0 };
+        try {
+          const m = vectorPathWorldBezier(p, at?.parentWorld ?? IDENTITY_MATRIX, { effects: false })[0];
+          if (m && m.type === "M") first = { x: m.x, y: m.y };
+        } catch {
+        }
+        return { id: p.id, len: Math.max(1e-6, motionPathLength(p, at?.parentWorld)), first };
+      });
+      if (!list.length) return null;
+      const span = Math.max(0, e - s);
+      if (order2 === "sequence") {
+        if (o.sortBy === "distance") {
+          const b = entry.bounds;
+          const origin = o.origin ?? (b ? { x: b.x + b.width / 2, y: b.y + b.height / 2 } : { x: 0, y: 0 });
+          list = [...list].sort((a, c) => Math.hypot(a.first.x - origin.x, a.first.y - origin.y) - Math.hypot(c.first.x - origin.x, c.first.y - origin.y));
+        }
+        const total = list.reduce((sum, p) => sum + p.len, 0);
+        let at = s;
+        return list.map((p) => {
+          const w = { id: p.id, start: at, end: at + span * p.len / total };
+          at = w.end;
+          return w;
+        });
+      }
+      const longest = Math.max(...list.map((p) => p.len));
+      return list.map((p) => {
+        const d = span * p.len / longest;
+        return o.align === "end" ? { id: p.id, start: e - d, end: e } : { id: p.id, start: s, end: s + d };
+      });
+    };
     switch (command2.type) {
       case "enter": {
         const style = command2.style ?? "fade";
@@ -942,7 +1063,9 @@ function compileMotionScene(scene) {
           break;
         }
         if (style === "draw") {
-          seg("drawEnd", 1, ease ?? MOTION_EASE_IN_OUT, start, start + duration2 * 0.75, { from: 0 });
+          const windows = drawWindows(start, start + duration2 * 0.75, command2);
+          if (windows) for (const w of windows) push({ node: w.id, property: "drawEnd", start: w.start, end: w.end, from: 0, to: 1, ease: ease ?? MOTION_EASE_IN_OUT, ...where });
+          else 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;
         }
@@ -976,7 +1099,9 @@ function compileMotionScene(scene) {
         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);
+          const windows = drawWindows(start, end, command2);
+          if (windows) for (const w of windows) push({ node: w.id, property: "drawEnd", start: w.start, end: w.end, from: valueAt(w.id, "drawEnd", w.start), to: 0, ease: ease ?? MOTION_EASE_IN_OUT, ...where });
+          else seg("drawEnd", 0, ease ?? MOTION_EASE_IN_OUT);
         } else if (style === "shrink") {
           seg("scaleX", 0, ease ?? "ease-in");
           seg("scaleY", 0, ease ?? "ease-in");
@@ -991,8 +1116,18 @@ function compileMotionScene(scene) {
         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 });
+        const e = ease ?? MOTION_EASE_IN_OUT;
+        const comet = command2.comet !== void 0 ? Math.min(1, Math.max(0, command2.comet)) : void 0;
+        const windows = drawWindows(start, end, command2) ?? [{ id: node, start, end }];
+        for (const w of windows) {
+          if (comet !== void 0) {
+            push({ node: w.id, property: "drawEnd", start: w.start, end: w.end, from: 0, to: 1 + comet, ease: e, ...where });
+            push({ node: w.id, property: "drawStart", start: w.start, end: w.end, from: -comet, to: 1, ease: e, ...where });
+            continue;
+          }
+          const drawn = tracks.has(motionTrackKey(w.id, "drawEnd"));
+          push({ node: w.id, property: "drawEnd", start: w.start, end: w.end, from: command2.from ?? (drawn ? valueAt(w.id, "drawEnd", w.start) : 0), to: command2.to ?? 1, ease: e, ...where });
+        }
         break;
       }
       case "move": {
@@ -1437,7 +1572,11 @@ function visibleAt(timeline, id, time, node) {
   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;
+  const drawn = num("drawEnd", 1) > 0.01 && (node.type === "path" || collectPathNodes(node).length === 0 || collectPathNodes(node).some((p) => {
+    const v = trackValue(timeline.tracks.get(motionTrackKey(p.id, "drawEnd")), time);
+    return typeof v !== "number" || v > 0.01;
+  }));
+  return drawn || hasFill && num("fillOpacity", 1) > 0.01;
 }
 function checkMotionScene(scene) {
   const issues = [];
@@ -1483,6 +1622,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) {
@@ -1555,6 +1696,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") {
@@ -1638,6 +1785,7 @@ var MOTION_EDIT_OPS = [
   "move_command",
   "set_artwork",
   "set_controls",
+  "set_clip",
   "replace_scene"
 ];
 var EditError = class extends Error {
@@ -1694,6 +1842,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) => {
@@ -2582,11 +2747,13 @@ function toLottie(scene, options = {}) {
     const widthFrom = owner(path, "strokeWidth");
     const fadeFrom = owner(path, "fillOpacity");
     const drawFrom = owner(path, "drawEnd");
-    if (drawFrom) {
-      const draw = track(drawFrom, "drawEnd");
-      items.push({ ty: "tm", nm: "Draw on", s: { a: 0, k: 0 }, e: animate(draw, (t) => [Math.min(1, Math.max(0, Number(trackValue(draw, t) ?? 1))) * 100]), o: { a: 0, k: 0 }, m: 1 });
+    const tailFrom = owner(path, "drawStart");
+    if (drawFrom || tailFrom) {
+      const pct = (track2, fallback) => (t) => [Math.min(1, Math.max(0, Number(trackValue(track2, t) ?? fallback))) * 100];
+      const head = drawFrom ? track(drawFrom, "drawEnd") : [];
+      const tail = tailFrom ? track(tailFrom, "drawStart") : [];
+      items.push({ ty: "tm", nm: "Draw on", s: tail.length ? animate(tail, pct(tail, 0)) : { a: 0, k: 0 }, e: head.length ? animate(head, pct(head, 1)) : { a: 0, k: 100 }, o: { a: 0, k: 0 }, m: 1 });
     }
-    if (owner(path, "drawStart")) notes.push(`"${path.id}": drawing from a start other than 0 is not exported.`);
     const stroke = paintOf(path.stroke, "stroke", path.id);
     if (stroke || strokeFrom) {
       const colour = strokeFrom ? track(strokeFrom, "stroke") : [];
@@ -2972,11 +3139,19 @@ var BLEND = (fallback) => ({
   enum: [...MOTION_BLENDS],
   description: `"add" makes it a layer over the pose that stacks with other changes (a shake on a slide); "replace" makes it a change the next one takes over from (default ${fallback}).`
 });
+var DRAW_ORDER = {
+  order: { type: "string", enum: ["together", "sequence"], description: "For drawing a group or several paths: together (default) or sequence (one stroke after another, each for a time in proportion to its length)." },
+  pace: { type: "string", enum: ["time", "speed"], description: "With together: time (default, every stroke takes the whole time) or speed (all at one speed, so short strokes take less)." },
+  align: { type: "string", enum: ["start", "end"], description: "With pace speed: start them together (default) or finish them together." },
+  sortBy: { type: "string", enum: ["document", "distance"], description: "With sequence: stacking order (default) or distance from origin (a radial reveal)." },
+  origin: object({ x: { type: "number", description: "Document units." }, y: { type: "number", description: "Document units." } }, ["x", "y"], "With sortBy distance: where strokes are drawn out from (default the target's centre).")
+};
 var command = (type, description, extra = {}, required = []) => object({ type: { const: type, description }, ...BASE, ...extra }, ["type", "targets", ...required], description);
 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.", {
+      ...DRAW_ORDER,
       style: {
         type: "string",
         enum: [...MOTION_ENTER_STYLES],
@@ -2989,11 +3164,12 @@ var MOTION_COMMAND_SCHEMA = {
       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.", {
+      ...DRAW_ORDER,
       style: { type: "string", enum: [...MOTION_EXIT_STYLES], description: "fade (default), shrink, slide, undraw, or wipe (hides behind a travelling edge through a clip over the target's box: a wipe in, reversed)." },
       direction: { type: "string", enum: [...MOTION_DIRECTIONS], description: "For slide: direction of travel (default down). For wipe: the way the edge travels (default right, hiding from the left)." },
       distance: { type: "number", description: "For slide: document units (default 40)." }
     }),
-    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("draw", "Draws strokes on (or off) to a fraction of their length.", { ...DRAW_ORDER, comet: FRACTION("A travelling stroke this fraction of the length long: it runs along the path and off the end (leave out from and to)."), to: FRACTION("Fraction drawn at the end (default 1)."), from: FRACTION("Fraction drawn at the start (default: what is drawn now).") }),
     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"]),
@@ -3003,6 +3179,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.", {
@@ -3211,6 +3401,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),
@@ -3456,6 +3647,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",
@@ -3632,7 +3885,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,
@@ -3664,6 +3917,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.
+- Drawing a group of strokes: "order": "sequence" draws them one after another (a signature, a diagram), "sortBy": "distance" from "origin" reveals outward, "pace": "speed" keeps one speed; draw with "comet": 0.2 sends a short stroke along a path and off the end.
+- 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).
@@ -3803,6 +4058,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)." };
@@ -3966,6 +4225,7 @@ export {
   MOTION_ADDITIVE_PROPERTIES,
   MOTION_BLENDS,
   MOTION_CAMERA_MS,
+  MOTION_CLIP_TARGET,
   MOTION_COMMAND_SCHEMA,
   MOTION_COMMAND_TYPES,
   MOTION_DEFAULT_DURATIONS,
@@ -3992,6 +4252,7 @@ export {
   applyMotionControlValues,
   applyMotionEdits,
   checkMotionScene,
+  clipsShapeProblems,
   commandShapeProblems,
   compileMotionScene,
   createAnimationEditorToolProvider,
@@ -4020,6 +4281,7 @@ export {
   motionBeatAt,
   motionBeatTime,
   motionClipAttrs,
+  motionClipLayout,
   motionCommandDuration,
   motionCommandFields,
   motionCommandRepeat,