@pixerate/editor 0.71.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 };
@@ -1720,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") {
@@ -1810,6 +1889,7 @@ var MOTION_EDIT_OPS = [
   "set_artwork",
   "set_controls",
   "set_clip",
+  "set_drivers",
   "replace_scene"
 ];
 var EditError = class extends Error {
@@ -1866,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 ?? {} };
@@ -2167,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 = [];
@@ -2214,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;
@@ -2230,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),
@@ -2762,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) };
@@ -3476,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),
@@ -3734,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",
@@ -3974,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,
@@ -4007,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".
@@ -4307,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,
@@ -4324,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,
@@ -4340,6 +4494,7 @@ export {
   MotionSceneFormatError,
   activeSegment,
   applyMotionControlValues,
+  applyMotionDrivers,
   applyMotionEdits,
   checkMotionScene,
   clipsShapeProblems,
@@ -4350,6 +4505,7 @@ export {
   defaultMotionCommand,
   describeMotionElements,
   describeMotionShots,
+  driversShapeProblems,
   duplicateMotionCommandEdit,
   fitMotionRect,
   fitMotionScene,
@@ -4357,6 +4513,7 @@ export {
   flairAtLeast,
   flairCurveFor,
   flairEaseFor,
+  formatMotionDrivers,
   formatMotionNarration,
   freshShotId,
   fromFlairSvgMotion,
@@ -4383,6 +4540,8 @@ export {
   motionCueKey,
   motionCueTime,
   motionCycleDuration,
+  motionDrivenNodes,
+  motionDriverSources,
   motionEaseKey,
   motionEasingCurve,
   motionEasingGuides,
@@ -4404,6 +4563,7 @@ export {
   motionPath,
   motionPathLength,
   motionPathsSvg,
+  motionPropertyValue,
   motionRestValue,
   motionRevealClip,
   motionRevealPadding,
@@ -4416,6 +4576,7 @@ export {
   motionStageSvg,
   motionTrackKey,
   namedWithSuggestion,
+  parseMotionDrivers,
   parseMotionFieldInput,
   parseMotionNarration,
   parseMotionScene,