@pixerate/editor 0.70.0 → 0.72.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_DRIVEN_PROPERTIES = ["x", "y", "rotation", "scaleX", "scaleY", "opacity"];
 var MOTION_CLIP_TARGET = "$";
 var MOTION_COMMAND_TYPES = [
   "enter",
@@ -141,6 +142,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." },
+  "driver-cycle": { severity: "error", wording: "Drivers follow each other in a loop, so none of them has a value." },
   "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)." },
@@ -219,7 +221,7 @@ ${problems.map((p) => `- ${p}`).join("\n")}`);
     this.problems = problems;
   }
 };
-var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "clips", "loop", "trigger", "fps", "steps", "beat", "narration", "target", "controls", "presets"];
+var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "clips", "drivers", "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"];
@@ -403,6 +405,23 @@ function clipsShapeProblems(clips) {
   }
   return problems;
 }
+function driversShapeProblems(drivers) {
+  if (!Array.isArray(drivers)) return ['Scene: "drivers" must be a list of { target, property, source: { node, property }, factor?, offset?, clamp? }.'];
+  const problems = [];
+  const props = MOTION_DRIVEN_PROPERTIES;
+  drivers.forEach((d, i) => {
+    const where = `Driver ${i + 1}`;
+    if (!isObject(d)) return void problems.push(`${where} must be an object.`);
+    unknownKeys(d, ["target", "property", "source", "factor", "offset", "clamp"], where, problems);
+    if (typeof d.target !== "string" || !d.target) problems.push(`${where}: "target" must be the id of the node that follows.`);
+    if (!props.includes(d.property)) problems.push(`${where}: "property" must be one of ${MOTION_DRIVEN_PROPERTIES.join(", ")}.`);
+    if (!isObject(d.source) || typeof d.source.node !== "string" || !d.source.node || !props.includes(d.source.property)) problems.push(`${where}: "source" must be { "node": id, "property": one of ${MOTION_DRIVEN_PROPERTIES.join(", ")} }.`);
+    if (d.factor !== void 0 && !isNum(d.factor)) problems.push(`${where}: "factor" must be a number.`);
+    if (d.offset !== void 0 && !isNum(d.offset)) problems.push(`${where}: "offset" must be a number.`);
+    if (d.clamp !== void 0 && !(Array.isArray(d.clamp) && d.clamp.length === 2 && d.clamp.every(isNum) && d.clamp[0] <= d.clamp[1])) problems.push(`${where}: "clamp" must be [min, max].`);
+  });
+  return problems;
+}
 function shotShapeProblems(shot, where) {
   if (!isObject(shot)) return [`${where} must be an object.`];
   const problems = [];
@@ -451,6 +470,7 @@ function motionSceneShapeProblems(input) {
   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.drivers !== void 0) problems.push(...driversShapeProblems(input.drivers));
   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.');
@@ -826,6 +846,41 @@ function motionCueTime(scene, cue) {
   if (typeof cue.word === "number") return scene.narration?.words[cue.word]?.start;
   return void 0;
 }
+var SCALE_LIKE = /* @__PURE__ */ new Set(["scaleX", "scaleY", "opacity"]);
+function motionPropertyValue(timeline, node, property, time, raw = false, depth = 0) {
+  const rest = property === "opacity" ? timeline.restOpacity?.get(node) ?? 1 : SCALE_LIKE.has(property) ? 1 : 0;
+  const v = trackValue(timeline.tracks.get(motionTrackKey(node, property)), time, raw);
+  const base = property === "opacity" ? typeof v === "number" ? v : rest : withMotionLayers(timeline, node, property, typeof v === "number" ? v : rest, time, raw);
+  return applyMotionDrivers(timeline, node, property, base, time, raw, depth);
+}
+function applyMotionDrivers(timeline, node, property, value, time, raw = false, depth = 0) {
+  if (!timeline.drivers || depth > 8) return value;
+  let v = value;
+  for (const d of timeline.drivers) {
+    if (d.target !== node || d.property !== property) continue;
+    const src = motionPropertyValue(timeline, d.source.node, d.source.property, time, raw, depth + 1);
+    const srcRest = d.source.property === "opacity" ? timeline.restOpacity?.get(d.source.node) ?? 1 : SCALE_LIKE.has(d.source.property) ? 1 : 0;
+    let change = (src - srcRest) * (d.factor ?? 1) + (d.offset ?? 0);
+    if (d.clamp) change = Math.min(d.clamp[1], Math.max(d.clamp[0], change));
+    v = SCALE_LIKE.has(property) ? v * (1 + change) : v + change;
+  }
+  return property === "opacity" ? Math.min(1, Math.max(0, v)) : v;
+}
+function motionDrivenNodes(timeline) {
+  return new Set((timeline.drivers ?? []).map((d) => d.target));
+}
+function motionDriverSources(timeline, node, properties, seen = /* @__PURE__ */ new Set()) {
+  const out = [];
+  for (const d of timeline.drivers ?? []) {
+    if (d.target !== node || !properties.includes(d.property)) continue;
+    const key = `${d.source.node}\0${d.source.property}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(...timeline.tracks.get(motionTrackKey(d.source.node, d.source.property)) ?? [], ...timeline.tracks.get(`${motionTrackKey(d.source.node, d.source.property)}\0add`) ?? []);
+    out.push(...motionDriverSources(timeline, d.source.node, [d.source.property], seen));
+  }
+  return out;
+}
 function motionCommandRepeat(command2) {
   if (command2.type === "wait" || command2.type === "enter" || command2.type === "exit") return 1;
   const n = command2.repeat ?? 1;
@@ -1238,7 +1293,7 @@ function compileMotionScene(scene) {
   for (const track of tracks.values()) track.sort((a, b) => a.start - b.start);
   segments.sort((a, b) => a.start - b.start);
   const duration = shots.length ? shots[shots.length - 1].end : 0;
-  const timeline = { duration, shots, commands, segments, tracks };
+  const timeline = { duration, shots, commands, segments, tracks, ...scene.drivers?.length ? { drivers: scene.drivers, restOpacity: new Map([...nodes].map(([id, e]) => [id, e.node.opacity ?? 1])) } : {} };
   timelineCache.set(scene, timeline);
   return timeline;
 }
@@ -1336,9 +1391,11 @@ function followAt(entry, timeline, nodes, time) {
 function motionNodeOffset(entry, timeline, time, nodes = indexMotionNodes([entry.node]), raw = false, follow = true) {
   const read = (p, rest) => {
     const v = trackValue(timeline.tracks.get(motionTrackKey(entry.node.id, p)), time, raw);
-    return withMotionLayers(timeline, entry.node.id, p, typeof v === "number" ? v : rest, time, raw);
+    const layered = withMotionLayers(timeline, entry.node.id, p, typeof v === "number" ? v : rest, time, raw);
+    return p === "follow" ? layered : applyMotionDrivers(timeline, entry.node.id, p, layered, time, raw);
   };
-  if (!TRANSFORM_PROPS.some((p) => (follow || p !== "follow") && (timeline.tracks.has(motionTrackKey(entry.node.id, p)) || timeline.tracks.has(motionAddTrackKey(entry.node.id, p))))) return null;
+  const driven = timeline.drivers?.some((d) => d.target === entry.node.id && d.property !== "opacity");
+  if (!driven && !TRANSFORM_PROPS.some((p) => (follow || p !== "follow") && (timeline.tracks.has(motionTrackKey(entry.node.id, p)) || timeline.tracks.has(motionAddTrackKey(entry.node.id, p))))) return null;
   const dx = read("x", 0);
   const dy = read("y", 0);
   const rotation = read("rotation", 0);
@@ -1364,7 +1421,7 @@ function motionFrameAt(scene, time, options = {}) {
   const nodes = indexMotionNodes(s.artwork.nodes);
   const drawOn = options.draw !== false;
   const value = (id, p) => trackValue(timeline.tracks.get(motionTrackKey(id, p)), time);
-  const animated = new Set(timeline.segments.map((seg) => seg.node));
+  const animated = /* @__PURE__ */ new Set([...timeline.segments.map((seg) => seg.node), ...motionDrivenNodes(timeline)]);
   const clips = {};
   const visit = (node) => {
     let out = node.type === "group" ? { ...node, children: node.children.map(visit) } : node;
@@ -1421,7 +1478,7 @@ function motionFrameAt(scene, time, options = {}) {
         return p;
       });
     }
-    const opacity = value(id, "opacity");
+    const opacity = timeline.drivers?.some((d) => d.target === id && d.property === "opacity") ? motionPropertyValue(timeline, id, "opacity", time) : value(id, "opacity");
     if (typeof opacity === "number") {
       const o = Math.min(1, Math.max(0, tidy(opacity)));
       out = { ...out, opacity: o };
@@ -1537,6 +1594,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;
@@ -1696,6 +1777,28 @@ function checkMotionScene(scene) {
       }
     });
   });
+  const drivers = scene.drivers ?? [];
+  drivers.forEach((d, i) => {
+    for (const id of [d.target, d.source.node])
+      if (!nodes.has(id)) issues.push(motionIssue("unknown-target", `Driver ${i + 1} names ${namedWithSuggestion(id, [...nodes.keys()])}, which the artwork does not have.`, { ids: [id] }));
+  });
+  {
+    const key = (n, p) => `${n}.${p}`;
+    const edges = /* @__PURE__ */ new Map();
+    for (const d of drivers) edges.set(key(d.target, d.property), [...edges.get(key(d.target, d.property)) ?? [], key(d.source.node, d.source.property)]);
+    const state = /* @__PURE__ */ new Map();
+    const loop = [];
+    const visit = (k, trail) => {
+      if (state.get(k) === 2) return false;
+      if (state.get(k) === 1) return loop.push(...trail.slice(trail.indexOf(k)), k), true;
+      state.set(k, 1);
+      for (const n of edges.get(k) ?? []) if (visit(n, [...trail, k])) return true;
+      state.set(k, 2);
+      return false;
+    };
+    for (const k of edges.keys()) if (visit(k, [])) break;
+    if (loop.length) issues.push(motionIssue("driver-cycle", `Drivers follow each other round in a loop (${loop.join(" \u2190 ")}); remove one of them.`, { ids: [...new Set(loop.map((k) => k.split(".")[0]))] }));
+  }
   for (const [name, clip] of Object.entries(scene.clips ?? {}))
     for (const command2 of clip.run)
       if (command2.type !== "wait") {
@@ -1786,6 +1889,7 @@ var MOTION_EDIT_OPS = [
   "set_artwork",
   "set_controls",
   "set_clip",
+  "set_drivers",
   "replace_scene"
 ];
 var EditError = class extends Error {
@@ -1842,6 +1946,13 @@ function applyOne(scene, edit) {
       else if (edit.target !== void 0) next.target = edit.target;
       return next;
     }
+    case "set_drivers": {
+      const problems = driversShapeProblems(edit.drivers);
+      if (problems.length) fail(problems.join(" "));
+      const next = { ...scene, drivers: edit.drivers };
+      if (!edit.drivers.length) delete next.drivers;
+      return next;
+    }
     case "set_clip": {
       if (typeof edit.name !== "string" || !edit.name) fail('Give the clip a "name".');
       const clips = { ...scene.clips ?? {} };
@@ -1990,6 +2101,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 ?? [] };
 }
@@ -2093,7 +2254,13 @@ function toFlairSvgMotion(scene, options = {}) {
     if (!entry) return void 0;
     return [...entry.ancestors, path.id].find((id) => timeline.tracks.has(motionTrackKey(id, p)));
   };
-  const animatedNodes = new Set(timeline.segments.map((s) => s.node).filter(Boolean));
+  const animatedNodes = /* @__PURE__ */ new Set([...timeline.segments.map((s) => s.node).filter(Boolean), ...motionDrivenNodes(timeline)]);
+  const drivenBy = /* @__PURE__ */ new WeakSet();
+  const sourcesOf = (id, props) => motionDriverSources(timeline, id, props).map((s) => {
+    const copy = { ...s };
+    drivenBy.add(copy);
+    return copy;
+  });
   const pathsSeen = /* @__PURE__ */ new Set();
   const wrap = {};
   const routes = [];
@@ -2140,10 +2307,11 @@ function toFlairSvgMotion(scene, options = {}) {
         follows.push({ id, wrapper, routes: ids, segments: followSegments.filter((seg) => seg.path && ids.has(seg.path)) });
       }
     }
-    if (timeline.tracks.has(motionTrackKey(id, "opacity")))
-      channels.push({ id, kind: "attr", attr: "opacity", segments: [...track(id, "opacity")], exact: plays, value: (t) => round2(Math.min(1, Math.max(0, Number(trackValue(track(id, "opacity"), t))))) });
+    const opacitySources = sourcesOf(id, ["opacity"]);
+    if (timeline.tracks.has(motionTrackKey(id, "opacity")) || opacitySources.length)
+      channels.push({ id, kind: "attr", attr: "opacity", segments: [...track(id, "opacity"), ...opacitySources], exact: (s) => plays(s) && !drivenBy.has(s), value: (t) => round2(motionPropertyValue(timeline, id, "opacity", t)) });
     const followed = follows.some((x) => x.id === id);
-    const transformSegments = TRANSFORM_PROPS2.flatMap((p) => followed && p === "follow" ? [] : [...track(id, p), ...timeline.tracks.get(motionAddTrackKey(id, p)) ?? []]);
+    const transformSegments = [...TRANSFORM_PROPS2.flatMap((p) => followed && p === "follow" ? [] : [...track(id, p), ...timeline.tracks.get(motionAddTrackKey(id, p)) ?? []]), ...sourcesOf(id, ["x", "y", "rotation", "scaleX", "scaleY"])];
     if (transformSegments.length) {
       const base = node.transform ? ` matrix(${node.transform.map(f).join(" ")})` : "";
       const c = entry.center;
@@ -2156,7 +2324,7 @@ function toFlairSvgMotion(scene, options = {}) {
         kind: "attr",
         attr: "transform",
         segments: transformSegments,
-        exact: (s) => LINEAR_TRANSFORM.has(s.property) && plays(s),
+        exact: (s) => LINEAR_TRANSFORM.has(s.property) && plays(s) && !drivenBy.has(s),
         overshoot: true,
         // x, y and the angle are the transform's numbers 0, 1 and 2 (`MotionSegment.index`).
         value: (t) => transformAt(t, false),
@@ -2688,16 +2856,22 @@ function toLottie(scene, options = {}) {
     const tr = STATIC_TR();
     const c = [entry.center.x, entry.center.y].map(round2);
     const own = (p) => track(id, p);
-    const layered = ["x", "y", "rotation", "scaleX", "scaleY"].some((p) => layers(id, p).length);
+    const sources = motionDriverSources(timeline, id, ["x", "y", "rotation", "scaleX", "scaleY"]);
+    const layered = ["x", "y", "rotation", "scaleX", "scaleY"].some((p) => layers(id, p).length) || sources.length > 0;
     const moving = ["x", "y", "rotation", "scaleX", "scaleY", "follow"].some((p) => own(p).length) || layered;
     if (moving) {
       const mixed = own("follow").length > 0 || layered;
       tr.a = { a: 0, k: c };
-      tr.p = animate(mixed ? [...own("x"), ...own("y"), ...own("follow"), ...layers(id, "x"), ...layers(id, "y")] : [...own("x"), ...own("y")], (t) => poseAt(entry, t).p, !mixed);
-      tr.r = animate(mixed ? [...own("rotation"), ...own("follow"), ...layers(id, "rotation")] : own("rotation"), (t) => [poseAt(entry, t).r], !mixed);
-      tr.s = animate(mixed ? [...own("scaleX"), ...own("scaleY"), ...layers(id, "scaleX"), ...layers(id, "scaleY")] : [...own("scaleX"), ...own("scaleY")], (t) => poseAt(entry, t).s, !mixed);
+      tr.p = animate(mixed ? [...own("x"), ...own("y"), ...own("follow"), ...layers(id, "x"), ...layers(id, "y"), ...sources] : [...own("x"), ...own("y")], (t) => poseAt(entry, t).p, !mixed);
+      tr.r = animate(mixed ? [...own("rotation"), ...own("follow"), ...layers(id, "rotation"), ...sources] : own("rotation"), (t) => [poseAt(entry, t).r], !mixed);
+      tr.s = animate(mixed ? [...own("scaleX"), ...own("scaleY"), ...layers(id, "scaleX"), ...layers(id, "scaleY"), ...sources] : [...own("scaleX"), ...own("scaleY")], (t) => poseAt(entry, t).s, !mixed);
       if (tr.p.a === 0) tr.p = { a: 0, k: poseAt(entry, 0).p.map(round2) };
     }
+    const opacitySources = motionDriverSources(timeline, id, ["opacity"]);
+    if (opacitySources.length) {
+      tr.o = animate([...own("opacity"), ...opacitySources], (t) => [motionPropertyValue(timeline, id, "opacity", t) * 100], false);
+      return tr;
+    }
     const opacity = own("opacity");
     const rest = entry.node.opacity ?? 1;
     tr.o = opacity.length ? animate(opacity, (t) => [Math.min(1, Math.max(0, Number(trackValue(opacity, t) ?? rest))) * 100]) : { a: 0, k: round2(rest * 100) };
@@ -3302,9 +3476,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"])
   ]
 };
@@ -3402,6 +3576,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
         ...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.drivers ? { drivers: s.drivers } : {},
         ...s.controls ? { controls: s.controls } : {},
         ...s.presets ? { presets: s.presets } : {},
         issues: issueSummary(controller.getState().issues),
@@ -3448,7 +3623,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".' },
@@ -3463,10 +3638,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) {
@@ -3478,7 +3655,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 });
@@ -3647,6 +3835,36 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return apply(edits, "Fit to length", () => report);
     }
   };
+  const PROP = { type: "string", enum: ["x", "y", "rotation", "scaleX", "scaleY", "opacity"], description: "x / y (offset, document units), rotation (degrees), scaleX / scaleY or opacity (1 = rest)." };
+  const setDrivers = {
+    name: "set_animation_drivers",
+    title: "Make properties follow others",
+    description: "Replaces the drivers (empty clears them): each makes a target's property follow a source node's property, as a change from rest \u2014 target change = source change \xB7 factor + offset, clamped \u2014 added to offsets and turns, multiplied into scales and opacity, on top of the target's own commands. For parallax (x follows x \xB7 0.5), a wheel turning as it rolls (rotation follows x \xB7 360 / (2\u03C0\xB7radius)), a shadow fading as a ball rises (opacity follows y \xB7 0.005). One undo step; loops between drivers are refused by check_animation. Returns the timing and issues.",
+    inputSchema: object(
+      {
+        drivers: {
+          type: "array",
+          maxItems: 64,
+          items: object(
+            {
+              target: { type: "string", minLength: 1, description: "Element id that follows." },
+              property: PROP,
+              source: object({ node: { type: "string", minLength: 1, description: "Element id it follows." }, property: PROP }, ["node", "property"], "What it follows."),
+              factor: { type: "number", description: "Multiplies the source's change (default 1)." },
+              offset: { type: "number", description: "Added to the change (default 0)." },
+              clamp: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2, description: "Limits the change to [min, max]." }
+            },
+            ["target", "property", "source"],
+            "One property following another."
+          ),
+          description: "Every driver (the list replaces the current one)."
+        }
+      },
+      ["drivers"]
+    ),
+    annotations: { title: "Make properties follow others", ...WRITE_IDEMPOTENT },
+    handler: ({ drivers }) => apply({ op: "set_drivers", drivers }, "Set drivers")
+  };
   const setClip = {
     name: "set_animation_clip",
     title: "Define a reusable clip",
@@ -3822,12 +4040,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 = {
@@ -3885,7 +4105,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     }
   };
   const reads = [getAnimation, getShot, findElements, getMotionPath, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation];
-  const writes = [setArtworkSvg, setClip, copyAnimation, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, moveCommand, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
+  const writes = [setArtworkSvg, setDrivers, 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,
@@ -3918,6 +4138,7 @@ Commands
 - 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.
+- Tie properties together with set_animation_drivers: parallax layers, a wheel that turns as it rolls, a shadow that fades as something rises. Drivers add to the target's own commands.
 - 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".
@@ -3934,7 +4155,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.
 
@@ -4217,6 +4439,27 @@ function parseMotionNarration(text) {
   }
   return { narration: { words } };
 }
+function formatMotionDrivers(drivers) {
+  return (drivers ?? []).map((d) => `${d.target}.${d.property} <- ${d.source.node}.${d.source.property}${d.factor !== void 0 && d.factor !== 1 ? ` * ${d.factor}` : ""}${d.offset ? ` ${d.offset < 0 ? "-" : "+"} ${Math.abs(d.offset)}` : ""}${d.clamp ? ` [${d.clamp[0]}, ${d.clamp[1]}]` : ""}`).join("\n");
+}
+function parseMotionDrivers(text) {
+  const props = MOTION_DRIVEN_PROPERTIES;
+  const drivers = [];
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  for (const [i, line] of lines.entries()) {
+    const m = /^([\w.-]+)\.(\w+)\s*<-\s*([\w.-]+)\.(\w+)\s*(?:\*\s*(-?[\d.]+(?:e-?\d+)?))?\s*(?:([+-])\s*([\d.]+(?:e-?\d+)?))?\s*(?:\[\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*\])?$/.exec(line);
+    if (!m) return { error: `Line ${i + 1} ("${line}") should read "target.property <- source.property", optionally "* factor", "+ offset" and "[min, max]", e.g. "dot.x <- box.x * 0.5".` };
+    const [, target, property, node, sourceProperty, factor, sign, offset, min, max] = m;
+    for (const p of [property, sourceProperty]) if (!props.includes(p)) return { error: `Line ${i + 1}: "${p}" is not a property drivers use; use ${MOTION_DRIVEN_PROPERTIES.join(", ")}.` };
+    const d = { target, property, source: { node, property: sourceProperty } };
+    if (factor !== void 0) d.factor = Number(factor);
+    if (offset !== void 0) d.offset = (sign === "-" ? -1 : 1) * Number(offset);
+    if (min !== void 0) d.clamp = [Number(min), Number(max)];
+    if ([d.factor, d.offset, ...d.clamp ?? []].some((n) => n !== void 0 && !Number.isFinite(n))) return { error: `Line ${i + 1} has a number that cannot be read.` };
+    drivers.push(d);
+  }
+  return { drivers };
+}
 export {
   ANIMATION_EDITOR_AGENT_INSTRUCTIONS,
   AnimationEditorController,
@@ -4234,6 +4477,7 @@ export {
   MOTION_DRAW_EFFECT_ID,
   MOTION_DRAW_MS_PER_UNIT,
   MOTION_DRAW_RANGE,
+  MOTION_DRIVEN_PROPERTIES,
   MOTION_EASE_CHOICES,
   MOTION_EASE_IN_OUT,
   MOTION_EASE_OUT,
@@ -4250,6 +4494,7 @@ export {
   MotionSceneFormatError,
   activeSegment,
   applyMotionControlValues,
+  applyMotionDrivers,
   applyMotionEdits,
   checkMotionScene,
   clipsShapeProblems,
@@ -4260,6 +4505,7 @@ export {
   defaultMotionCommand,
   describeMotionElements,
   describeMotionShots,
+  driversShapeProblems,
   duplicateMotionCommandEdit,
   fitMotionRect,
   fitMotionScene,
@@ -4267,6 +4513,7 @@ export {
   flairAtLeast,
   flairCurveFor,
   flairEaseFor,
+  formatMotionDrivers,
   formatMotionNarration,
   freshShotId,
   fromFlairSvgMotion,
@@ -4287,11 +4534,14 @@ export {
   motionCommandRepeat,
   motionCommandRows,
   motionCommandSummary,
+  motionContactSheetSvg,
   motionCueChoices,
   motionCueFromKey,
   motionCueKey,
   motionCueTime,
   motionCycleDuration,
+  motionDrivenNodes,
+  motionDriverSources,
   motionEaseKey,
   motionEasingCurve,
   motionEasingGuides,
@@ -4313,6 +4563,7 @@ export {
   motionPath,
   motionPathLength,
   motionPathsSvg,
+  motionPropertyValue,
   motionRestValue,
   motionRevealClip,
   motionRevealPadding,
@@ -4325,10 +4576,12 @@ export {
   motionStageSvg,
   motionTrackKey,
   namedWithSuggestion,
+  parseMotionDrivers,
   parseMotionFieldInput,
   parseMotionNarration,
   parseMotionScene,
   resolveMotionCamera,
+  resolveMotionEditRefs,
   segmentProgress,
   segmentValue,
   shotShapeProblems,