@pixerate/editor 0.69.0 → 0.71.0

package/dist/animation-editor/index.js

@@ -223,10 +223,11 @@ var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "clips",
 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"],
@@ -270,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.`);
@@ -303,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).`);
@@ -1003,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";
@@ -1015,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;
         }
@@ -1049,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");
@@ -1064,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": {
@@ -1475,6 +1537,30 @@ function motionStageSvg(scene, time, options = {}) {
   const bg = svgOptions.background !== false && scene.artwork.background ? /^\s*<rect[^>]*\/>/.exec(body)?.[0] ?? "" : "";
   return `${current.slice(0, open)}${bg}${ghosts.join("")}${body.slice(bg.length)}${paths}</svg>`;
 }
+function motionContactSheetSvg(scene, times, options = {}) {
+  const { columns, labels = true, ...frameOptions } = options;
+  const n = Math.max(1, times.length);
+  const cols = Math.max(1, Math.min(n, Math.floor(columns ?? Math.ceil(Math.sqrt(n)))));
+  const rows = Math.ceil(n / cols);
+  const { width: w, height: h } = scene.artwork;
+  const gap = Math.round(Math.max(w, h) * 0.04);
+  const label = labels ? Math.round(Math.max(12, h * 0.08)) : 0;
+  const timeline = compileMotionScene(scene);
+  const W = cols * w + (cols + 1) * gap;
+  const H = rows * (h + label) + (rows + 1) * gap;
+  const prefix = frameOptions.idPrefix ?? "vg-";
+  const cells = times.map((t, i) => {
+    const x = gap + i % cols * (w + gap);
+    const y = gap + Math.floor(i / cols) * (h + label + gap);
+    const frame = motionStageSvg(scene, t, { ...frameOptions, idPrefix: `${prefix}f${i}-` });
+    const view = /viewBox="([^"]*)"/.exec(frame)?.[1] ?? `0 0 ${w} ${h}`;
+    const inner = innerSvg(frame).replace(new RegExp(` id="(?!${`${prefix}f${i}-`.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})[^"]*"`, "g"), "");
+    const shot = timeline.shots.find((s) => t >= s.start && t < s.end) ?? timeline.shots[timeline.shots.length - 1];
+    const caption = labels ? `<text x="${x + w / 2}" y="${y + h + label * 0.8}" font-family="system-ui, sans-serif" font-size="${Math.round(label * 0.7)}" text-anchor="middle" fill="#64748b">${(t / 1e3).toFixed(2)} s${shot ? ` \xB7 ${shot.id.replace(/[<&]/g, "")}` : ""}</text>` : "";
+    return `<svg x="${x}" y="${y}" width="${w}" height="${h}" viewBox="${view}" overflow="hidden">${inner}</svg><rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="#cbd5e1"/>${caption}`;
+  });
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}"><rect width="${W}" height="${H}" fill="#f8fafc"/>${cells.join("")}</svg>`;
+}
 
 // src/animation-editor/check.ts
 var MOTION_MIN_CHANGE_MS = 120;
@@ -1510,7 +1596,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 = [];
@@ -1924,6 +2014,56 @@ function applyMotionEdits(scene, edits) {
   if (added.length) return { ok: false, error: `Nothing was changed: ${added.map(motionIssueLine).join(" ")}` };
   return { ok: true, scene: next, issues, hints: editHints(before, issues) };
 }
+var REF = /^\$(\d+|last)((?:\.[A-Za-z_]\w*|\[\d+\])+)$/;
+function resolveMotionEditRefs(scene, edits) {
+  const outcomes = [];
+  const resolved = [];
+  let next = scene;
+  for (let i = 0; i < edits.length; i++) {
+    const where = `op ${i + 1} (${edits[i]?.op})`;
+    let problem = null;
+    const walk = (v) => {
+      if (typeof v === "string") {
+        if (v.startsWith("$$")) return v.slice(1);
+        const m = REF.exec(v);
+        if (!m) return v;
+        const n = m[1] === "last" ? i - 1 : Number(m[1]);
+        if (!(n >= 0 && n < i)) {
+          problem = `${where}: "${v}" refers to op ${n + 1}, but only ops before this one (1 to ${i}) can be referred to.`;
+          return v;
+        }
+        let value = outcomes[n];
+        for (const part of m[2].match(/\.[A-Za-z_]\w*|\[\d+\]/g) ?? []) value = value == null ? void 0 : value[part.startsWith(".") ? part.slice(1) : part.slice(1, -1)];
+        if (value === void 0) problem = `${where}: "${v}" has no value; op ${n + 1} made ${JSON.stringify(outcomes[n])}.`;
+        return value;
+      }
+      if (Array.isArray(v)) return v.map(walk);
+      if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+      return v;
+    };
+    const edit = walk(edits[i]);
+    if (problem) return { ok: false, error: `${problem} Nothing was changed.` };
+    const before = next;
+    try {
+      next = applyOne(next, edit);
+    } catch (error) {
+      if (error instanceof EditError) return { ok: false, error: `${where}: ${error.message} Nothing was changed.` };
+      throw error;
+    }
+    resolved.push(edit);
+    const out = { op: edit.op };
+    if (edit.op === "insert_shots") out.shots = edit.shots.map((s) => s.id);
+    if ("shot" in edit && typeof edit.shot === "string") out.shot = edit.op === "update_shot" && edit.set?.id ? edit.set.id : edit.shot;
+    if (edit.op === "add_commands") {
+      const at = edit.at ?? before.shots.find((s) => s.id === edit.shot)?.run.length ?? 0;
+      out.indexes = edit.commands.map((_, k) => at + k);
+    }
+    if (edit.op === "move_command") out.indexes = [edit.to];
+    if (edit.op === "set_clip") out.clip = edit.name;
+    outcomes.push(out);
+  }
+  return { ok: true, edits: resolved, outcomes };
+}
 function createMotionScene(artwork, init = {}) {
   return { version: 1, name: init.name ?? "animation", ...init, artwork, shots: init.shots ?? [] };
 }
@@ -2681,11 +2821,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") : [];
@@ -3071,11 +3213,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],
@@ -3088,11 +3238,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"]),
@@ -3225,9 +3376,9 @@ var EDIT_OP = {
     object({ op: { const: "delete_shots", description: "Like delete_shots." }, shots: { type: "array", items: SHOT_ID, minItems: 1, description: "Shot ids." } }, ["op", "shots"]),
     object({ op: { const: "move_shot", description: "Like move_shot." }, shot: SHOT_ID, to: { type: "integer", minimum: 0, description: "New position (0 = first)." } }, ["op", "shot", "to"]),
     object({ op: { const: "add_commands", description: "Like add_commands." }, shot: SHOT_ID, commands: { type: "array", items: MOTION_COMMAND_SCHEMA, minItems: 1, description: "Commands to add." }, at: { type: "integer", minimum: 0, description: "Index in the shot's run (default: the end)." } }, ["op", "shot", "commands"]),
-    object({ op: { const: "update_command", description: "Like update_command." }, shot: SHOT_ID, command: { type: "integer", minimum: 0, description: "Index in the shot's run." }, set: { type: "object", description: "Command fields to replace." }, remove: { type: "array", items: { type: "string" }, description: "Command fields to clear." } }, ["op", "shot", "command"]),
-    object({ op: { const: "move_command", description: "Like move_command." }, shot: SHOT_ID, command: { type: "integer", minimum: 0, description: "Index in the shot's run." }, to: { type: "integer", minimum: 0, description: "New index in the run (0 = first)." } }, ["op", "shot", "command", "to"]),
-    object({ op: { const: "delete_commands", description: "Like delete_commands." }, shot: SHOT_ID, commands: { type: "array", items: { type: "integer", minimum: 0 }, minItems: 1, description: "Indexes in the shot's run." } }, ["op", "shot", "commands"]),
+    object({ op: { const: "update_command", description: "Like update_command." }, shot: SHOT_ID, command: { anyOf: [{ type: "integer", minimum: 0 }, { type: "string", pattern: "^\\$(\\d+|last)[.\\[]" }], description: `Index in the shot's run, or a reference to an earlier op's outcome such as "$0.indexes[0]".` }, set: { type: "object", description: "Command fields to replace." }, remove: { type: "array", items: { type: "string" }, description: "Command fields to clear." } }, ["op", "shot", "command"]),
+    object({ op: { const: "move_command", description: "Like move_command." }, shot: SHOT_ID, command: { anyOf: [{ type: "integer", minimum: 0 }, { type: "string", pattern: "^\\$(\\d+|last)[.\\[]" }], description: `Index in the shot's run, or a reference to an earlier op's outcome such as "$0.indexes[0]".` }, to: { type: "integer", minimum: 0, description: "New index in the run (0 = first)." } }, ["op", "shot", "command", "to"]),
+    object({ op: { const: "delete_commands", description: "Like delete_commands." }, shot: SHOT_ID, commands: { type: "array", items: { anyOf: [{ type: "integer", minimum: 0 }, { type: "string", pattern: "^\\$(\\d+|last)[.\\[]" }], description: `An index, or a reference to an earlier op's outcome such as "$0.indexes[0]".` }, minItems: 1, description: "Indexes in the shot's run." } }, ["op", "shot", "commands"]),
     object({ op: { const: "set_controls", description: "Like set_controls." }, controls: { type: "array", items: CONTROL, description: "Controls (empty clears)." }, presets: { type: "array", items: PRESET, description: "Presets (empty clears)." } }, ["op", "controls"])
   ]
 };
@@ -3371,7 +3522,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
   const renderFrame = {
     name: "render_animation_frame",
     title: "Render a frame",
-    description: 'Draws the animation at one moment without changing it, to check it: standalone SVG by default, or a PNG image (format "png") when the host can rasterize. Give a time in ms, or a shot and where in it.',
+    description: 'Draws the animation at one moment (or, with times, several moments as one labelled contact sheet) without changing it, to check it: standalone SVG by default, or a PNG image (format "png") when the host can rasterize. Give a time in ms, or a shot and where in it.',
     inputSchema: object({
       time: MS("Time from the start"),
       shot: { ...SHOT_ID, description: 'Render a moment of this shot instead of "time".' },
@@ -3386,10 +3537,12 @@ function createAnimationEditorToolProvider(controller, options = {}) {
         [],
         "Draw faded frames either side of the moment, to see motion in one picture."
       ),
+      times: { type: "array", items: { type: "number", minimum: 0 }, minItems: 2, maxItems: 16, description: "Several moments (ms) to draw as one contact sheet, each labelled with its time and shot, instead of one frame. Overrides time and shot." },
+      columns: { type: "integer", minimum: 1, maximum: 8, description: "With times: frames a row (default about square)." },
       motion_paths: { anyOf: [{ type: "boolean" }, { type: "array", items: { type: "string", minLength: 1 } }], description: "Draw where nodes travel (dashed, with a dot where each change starts or ends): true for every node whose place changes, or a list of ids." }
     }),
     annotations: { title: "Render a frame", ...READ },
-    handler: async ({ time, shot, at = "end", format = "svg", onion_skin, motion_paths }) => {
+    handler: async ({ time, shot, at = "end", format = "svg", onion_skin, motion_paths, times, columns }) => {
       const s = scene();
       let t = time ?? controller.getState().time;
       if (shot !== void 0) {
@@ -3401,7 +3554,18 @@ function createAnimationEditorToolProvider(controller, options = {}) {
         const known = new Set(describeMotionElements(s).map((e) => e.id));
         for (const id of motion_paths) if (!known.has(id)) throw new Error(`There is no element ${namedWithSuggestion(id, known)} to draw a motion path for.`);
       }
-      const svg = controller.toSvg(t, { pretty: false, ...onion_skin ? { onionSkin: onion_skin } : {}, ...motion_paths ? { motionPaths: motion_paths } : {} });
+      const overlays = { ...onion_skin ? { onionSkin: onion_skin } : {}, ...motion_paths ? { motionPaths: motion_paths } : {} };
+      if (times) {
+        const sheet = motionContactSheetSvg(s, times, { pretty: false, ...overlays, ...columns ? { columns } : {} });
+        if (format === "png") {
+          if (!options.rasterize) throw new Error('This host cannot make PNG images; call render_animation_frame with format "svg".');
+          const size = /width="(\d+)" height="(\d+)"/.exec(sheet);
+          const image = await options.rasterize(sheet, { width: Number(size[1]), height: Number(size[2]) });
+          return { content: [{ type: "image", data: image.data, mimeType: image.mimeType }] };
+        }
+        return { times, svg: sheet };
+      }
+      const svg = controller.toSvg(t, { pretty: false, ...overlays });
       if (format === "png") {
         if (!options.rasterize) throw new Error('This host cannot make PNG images; call render_animation_frame with format "svg".');
         const image = await options.rasterize(svg, { width: s.artwork.width, height: s.artwork.height });
@@ -3745,12 +3909,14 @@ function createAnimationEditorToolProvider(controller, options = {}) {
   const editAnimation = {
     name: "edit_animation",
     title: "Make several edits at once",
-    description: 'Applies several edits in order as one undo step, all or nothing: if one fails, nothing changes and the error names the op ("op 2 (add_commands): \u2026"). With dry_run it only reports the timing and issues the edits would give.',
+    description: `Applies several edits in order as one undo step, all or nothing: if one fails, nothing changes and the error names the op ("op 2 (add_commands): \u2026"). A later op can use what an earlier one made: "$0.indexes[0]" is the index of the first command op 1 added, "$last.shot" the shot the op before changed. Returns each op's outcome (shot, shots, indexes, clip), the timing and issues. With dry_run it only reports them.`,
     inputSchema: object({ ops: { type: "array", items: EDIT_OP, minItems: 1, description: "Edits, applied in order." }, dry_run: { type: "boolean", description: "Check without applying (default false)." } }, ["ops"]),
     annotations: { title: "Make several edits at once", ...WRITE },
     handler: ({ ops, dry_run = false }) => {
-      const result = controller.apply(ops, "Edit animation", { dryRun: dry_run });
-      return outcome(result, dry_run ? { dry_run: true, hint: "Nothing was applied; call again without dry_run to apply." } : {});
+      const refs = resolveMotionEditRefs(controller.getScene(), ops);
+      if (!refs.ok) throw new Error(refs.error);
+      const result = controller.apply(refs.edits, "Edit animation", { dryRun: dry_run });
+      return outcome(result, { outcomes: refs.outcomes, ...dry_run ? { dry_run: true, hint: "Nothing was applied; call again without dry_run to apply." } : {} });
     }
   };
   const writeAnimation = {
@@ -3840,6 +4006,7 @@ 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".
@@ -3856,7 +4023,8 @@ Commands
 Working method
 1. get_animation to learn the element ids (set_animation_artwork_svg first if there is no artwork: give every element you will animate an id; or import_flair_effect to start from a Flair effect and edit it).
 2. Plan a few shots, each one idea. Add them with insert_shots (add_commands, update_command, move_command and delete_commands refine a shot), or edit_animation to make several edits as one step (dry_run first when unsure).
-3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + "end") to look at the result; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.
+- In edit_animation, a later op can use what an earlier one made: "$0.indexes[0]" (the first command op 1 added), "$last.shot".
+3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + "end") to look at the result, or with "times" for a contact sheet of several moments; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.
 - For something the viewer plays (a button, a toggle, a step-by-step explainer), set "trigger" with set_animation_settings: click plays the next shot on each click and then starts over (make the last shot put things back for a toggle), hover or press plays and rewinds, scroll scrubs.
 4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.
 
@@ -4209,6 +4377,7 @@ export {
   motionCommandRepeat,
   motionCommandRows,
   motionCommandSummary,
+  motionContactSheetSvg,
   motionCueChoices,
   motionCueFromKey,
   motionCueKey,
@@ -4251,6 +4420,7 @@ export {
   parseMotionNarration,
   parseMotionScene,
   resolveMotionCamera,
+  resolveMotionEditRefs,
   segmentProgress,
   segmentValue,
   shotShapeProblems,