@pixerate/editor 0.71.0 → 0.73.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", "motionBlur", "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,12 @@ 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.motionBlur !== void 0) {
+    const b = input.motionBlur;
+    if (!isObject(b) || Object.keys(b).some((k) => k !== "shutter" && k !== "samples") || b.shutter !== void 0 && !(isNum(b.shutter) && b.shutter > 0 && b.shutter <= 720) || b.samples !== void 0 && !(Number.isInteger(b.samples) && b.samples >= 2 && b.samples <= 32))
+      problems.push('Scene: "motionBlur" must be { "shutter"?: degrees above 0 up to 720 (default 180), "samples"?: 2 to 32 (default 8) }.');
+  }
   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 +851,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 +1298,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 +1396,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 +1426,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 +1483,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 };
@@ -1517,12 +1579,49 @@ function motionPathsSvg(paths, camera, color = "#f43f5e") {
     (p) => `<g data-motion-path="${p.id.replace(/"/g, "&quot;")}" fill="none" stroke="${color}" stroke-width="${f(w)}" stroke-linecap="round" stroke-linejoin="round" opacity="0.8"><polyline points="${p.points.map((q) => `${f(q.x)},${f(q.y)}`).join(" ")}" stroke-dasharray="${f(w * 3)} ${f(w * 2)}"/>${p.keys.map((k) => `<circle cx="${f(k.x)}" cy="${f(k.y)}" r="${f(w * 2.5)}" fill="${color}" stroke="none"/>`).join("")}</g>`
   ).join("");
 }
+function motionBlurTimes(scene, time, blur = {}) {
+  const shutter = Math.min(720, Math.max(0, blur.shutter ?? 180));
+  const most = Math.max(1, Math.min(32, Math.floor(blur.samples ?? 8)));
+  const span = 1e3 / (scene.fps ?? 30) * shutter / 360;
+  if (span <= 0 || most <= 1) return [time];
+  const ids = motionMovingIds(scene);
+  if (!ids.length) return [time];
+  const a = indexMotionNodes(motionFrameAt(scene, time - span / 2).document.nodes);
+  const b = indexMotionNodes(motionFrameAt(scene, time + span / 2).document.nodes);
+  let travel = 0;
+  for (const id of ids) {
+    const p = a.get(id)?.bounds;
+    const q = b.get(id)?.bounds;
+    if (p && q) travel = Math.max(travel, Math.abs(p.x - q.x), Math.abs(p.y - q.y), Math.abs(p.x + p.width - q.x - q.width), Math.abs(p.y + p.height - q.y - q.height));
+  }
+  const n = Math.min(most, Math.ceil(travel / 1.5));
+  if (n <= 1) return [time];
+  return Array.from({ length: n }, (_, k) => time - span / 2 + span * (k + 0.5) / n);
+}
+function averagedFrames(scene, times, options, prefix) {
+  const n = times.length;
+  return `<g data-motion-blur="${n}" style="isolation:isolate">${times.map((t, k) => {
+    const own = `${prefix}blur${k}-`;
+    const frame = motionFrameToSvg(scene, t, { ...options, idPrefix: own, background: false });
+    const view = /viewBox="([^"]*)"/.exec(frame)?.[1] ?? "";
+    const inner = k === n - 1 ? innerSvg(frame) : innerSvg(frame).replace(new RegExp(` id="(?!${own.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})[^"]*"`, "g"), "");
+    return `<svg viewBox="${view}" preserveAspectRatio="none" style="mix-blend-mode:plus-lighter" opacity="${Math.round(1e4 / n) / 1e4}">${inner}</svg>`;
+  }).join("")}</g>`;
+}
 var innerSvg = (svg) => svg.slice(svg.indexOf(">") + 1, svg.lastIndexOf("</svg>"));
 function motionStageSvg(scene, time, options = {}) {
-  const { onionSkin, motionPaths, motionPathColor, ...svgOptions } = options;
-  const current = motionFrameToSvg(scene, time, svgOptions);
-  if (!onionSkin && !motionPaths) return current;
+  const { onionSkin, motionPaths, motionPathColor, motionBlur, ...svgOptions } = options;
   const prefix = svgOptions.idPrefix ?? "vg-";
+  let current = motionFrameToSvg(scene, time, svgOptions);
+  const blur = motionBlur === false ? void 0 : motionBlur ?? scene.motionBlur;
+  const blurTimes = blur ? motionBlurTimes(scene, time, blur) : [time];
+  if (blurTimes.length > 1) {
+    const open2 = current.indexOf(">") + 1;
+    const body2 = current.slice(open2, current.lastIndexOf("</svg>"));
+    const bg2 = svgOptions.background !== false && scene.artwork.background ? /^\s*<rect[^>]*\/>/.exec(body2)?.[0] ?? "" : "";
+    current = `${current.slice(0, open2)}${bg2}${averagedFrames(scene, blurTimes, svgOptions, prefix)}</svg>`;
+  }
+  if (!onionSkin && !motionPaths) return current;
   const ghosts = onionSkin ? motionGhosts(scene, time, onionSkin).map((g, i) => {
     const own = `${prefix}ghost${i}-`;
     const inner = innerSvg(motionFrameToSvg(scene, g.time, { ...svgOptions, idPrefix: own, background: false })).replace(new RegExp(` id="(?!${own.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})[^"]*"`, "g"), "");
@@ -1720,6 +1819,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") {
@@ -1810,6 +1931,7 @@ var MOTION_EDIT_OPS = [
   "set_artwork",
   "set_controls",
   "set_clip",
+  "set_drivers",
   "replace_scene"
 ];
 var EditError = class extends Error {
@@ -1854,18 +1976,25 @@ function applyOne(scene, edit) {
         if (!(typeof edit.steps === "number" && edit.steps > 0 && edit.steps <= 120)) fail('"steps" must be frames per second from above 0 to 120 (12 is "on twos" at 24 fps), or null for smooth.');
         next.steps = edit.steps;
       }
-      for (const key of ["beat", "narration"]) {
+      for (const key of ["beat", "narration", "motionBlur"]) {
         if (edit[key] === null) delete next[key];
         else if (edit[key] !== void 0) next[key] = edit[key];
       }
       {
-        const problems = motionSceneShapeProblems(next).filter((p) => /"beat"|"narration"/.test(p));
+        const problems = motionSceneShapeProblems(next).filter((p) => /"beat"|"narration"|"motionBlur"/.test(p));
         if (problems.length) fail(problems.join(" "));
       }
       if (edit.target === null) delete next.target;
       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 ?? {} };
@@ -2167,7 +2296,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 = [];
@@ -2214,10 +2349,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;
@@ -2230,7 +2366,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),
@@ -2375,6 +2511,7 @@ function toFlairSvgMotion(scene, options = {}) {
     }
     animate.sort((x, y) => (x.step ?? 0) - (y.step ?? 0) || (x.delay ?? 0) - (y.delay ?? 0));
   }
+  if (scene.motionBlur) notes.push("Motion blur is drawn on the stage only; Flair plays the scene sharp.");
   if (trigger && (scene.loop ?? "none") !== "none") notes.push(`The scene plays on ${trigger}, so its loop does not apply in Flair.`);
   let svg = vectorDocumentToSvg({ ...scene.artwork, nodes: expandVectorAppearances(scene.artwork.nodes) }, { pretty: false, precision, wrap });
   if (routes.length) svg = svg.replace(/^(<svg[^>]*>)/, `$1<defs>${routes.join("")}</defs>`);
@@ -2691,6 +2828,7 @@ function toLottie(scene, options = {}) {
   const timeline = compileMotionScene(scene);
   const nodes = indexMotionNodes(scene.artwork.nodes);
   const notes = [];
+  if (scene.motionBlur) notes.push("Motion blur is drawn on the stage only; the Lottie plays sharp.");
   if (scene.trigger) notes.push(`The scene plays on ${scene.trigger}; Lottie has no trigger, so it plays through (markers show where each shot starts, for a player to stop at).`);
   let sampled = 0;
   const track = (id, p) => timeline.tracks.get(motionTrackKey(id, p)) ?? [];
@@ -2762,16 +2900,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) };
@@ -3351,6 +3495,10 @@ var SETTINGS = {
   },
   fps: { type: "number", minimum: 1, maximum: 120, description: "Sampling rate for exports (default 30)." },
   steps: { anyOf: [{ type: "number", exclusiveMinimum: 0, maximum: 120 }, { type: "null" }], description: 'Stepped time for every command without its own: changes hold on a grid of this many frames per second (12 = "on twos" at 24 fps) for a hand-drawn look; null makes it smooth again (default).' },
+  motionBlur: {
+    anyOf: [object({ shutter: { type: "number", exclusiveMinimum: 0, maximum: 720, description: "Shutter angle in degrees of a frame (default 180; 360 is a whole frame, more blur)." }, samples: { type: "integer", minimum: 2, maximum: 32, description: "Most moments a frame averages (default 8)." } }), { type: "null" }],
+    description: "Motion blur on the stage and in rendered frames (not exported to Flair or Lottie); null turns it off."
+  },
   beat: {
     anyOf: [
       object({ bpm: { type: "number", minimum: 1, maximum: 1e3, description: "Beats a minute." }, offset: { type: "number", description: "When beat 0 falls, ms (default 0)." }, meter: { type: "integer", minimum: 1, description: "Beats a bar (default 4)." } }, ["bpm"]),
@@ -3476,6 +3624,8 @@ 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.motionBlur ? { motionBlur: s.motionBlur } : {},
         ...s.controls ? { controls: s.controls } : {},
         ...s.presets ? { presets: s.presets } : {},
         issues: issueSummary(controller.getState().issues),
@@ -3734,6 +3884,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",
@@ -3974,7 +4154,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,
@@ -4007,6 +4187,8 @@ 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.
+- Fast motion reads better with blur: set_animation_settings { "motionBlur": { "shutter": 180 } } (stage and rendered frames only).
+- 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".
@@ -4307,6 +4489,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,
@@ -4324,6 +4527,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,
@@ -4340,6 +4544,7 @@ export {
   MotionSceneFormatError,
   activeSegment,
   applyMotionControlValues,
+  applyMotionDrivers,
   applyMotionEdits,
   checkMotionScene,
   clipsShapeProblems,
@@ -4350,6 +4555,7 @@ export {
   defaultMotionCommand,
   describeMotionElements,
   describeMotionShots,
+  driversShapeProblems,
   duplicateMotionCommandEdit,
   fitMotionRect,
   fitMotionScene,
@@ -4357,6 +4563,7 @@ export {
   flairAtLeast,
   flairCurveFor,
   flairEaseFor,
+  formatMotionDrivers,
   formatMotionNarration,
   freshShotId,
   fromFlairSvgMotion,
@@ -4370,6 +4577,7 @@ export {
   motionAddTrackKey,
   motionBeatAt,
   motionBeatTime,
+  motionBlurTimes,
   motionClipAttrs,
   motionClipLayout,
   motionCommandDuration,
@@ -4383,6 +4591,8 @@ export {
   motionCueKey,
   motionCueTime,
   motionCycleDuration,
+  motionDrivenNodes,
+  motionDriverSources,
   motionEaseKey,
   motionEasingCurve,
   motionEasingGuides,
@@ -4404,6 +4614,7 @@ export {
   motionPath,
   motionPathLength,
   motionPathsSvg,
+  motionPropertyValue,
   motionRestValue,
   motionRevealClip,
   motionRevealPadding,
@@ -4416,6 +4627,7 @@ export {
   motionStageSvg,
   motionTrackKey,
   namedWithSuggestion,
+  parseMotionDrivers,
   parseMotionFieldInput,
   parseMotionNarration,
   parseMotionScene,