@pixerate/editor 0.64.0 → 0.65.0

package/dist/animation-editor/index.cjs

@@ -1258,10 +1258,92 @@ function withViewBox(svg, box) {
   return svg.replace(/viewBox="[^"]*"/, `viewBox="${f(box.x)} ${f(box.y)} ${f(box.width)} ${f(box.height)}"`);
 }
 
+// src/animation-editor/onion.ts
+function motionGhosts(scene, time, onion = {}) {
+  const before = Math.max(0, Math.floor(_nullishCoalesce(onion.before, () => ( 2))));
+  const after = Math.max(0, Math.floor(_nullishCoalesce(onion.after, () => ( 0))));
+  const base = Math.min(1, Math.max(0, _nullishCoalesce(onion.opacity, () => ( 0.35))));
+  const timeline = compileMotionScene(scene);
+  const ghosts = [];
+  const push = (t, offset) => ghosts.push({ time: t, offset, opacity: Math.round(base / Math.abs(offset) * 1e3) / 1e3 });
+  if (onion.spacing === "commands") {
+    const marks = [...new Set(timeline.commands.flatMap((c) => [c.start, c.end]))].sort((a, b) => a - b);
+    marks.filter((t) => t < time - 1e-6).reverse().slice(0, before).forEach((t, i) => push(t, -(i + 1)));
+    marks.filter((t) => t > time + 1e-6).slice(0, after).forEach((t, i) => push(t, i + 1));
+    return ghosts;
+  }
+  const spacing = typeof onion.spacing === "number" && onion.spacing > 0 ? onion.spacing : 1e3 / 12;
+  for (let i = 1; i <= before && time - i * spacing >= 0; i++) push(time - i * spacing, -i);
+  for (let i = 1; i <= after && time + i * spacing <= timeline.duration; i++) push(time + i * spacing, i);
+  return ghosts;
+}
+var MOVING = ["x", "y", "rotation", "scaleX", "scaleY", "follow", "shape"];
+function motionMovingIds(scene) {
+  const timeline = compileMotionScene(scene);
+  const nodes = indexMotionNodes(scene.artwork.nodes);
+  const moving = new Set(timeline.segments.filter((s) => s.node && MOVING.includes(s.property)).map((s) => s.node));
+  return [...nodes.values()].filter((e) => e.node.visible !== false && (moving.has(e.node.id) || e.ancestors.some((a) => moving.has(a)))).map((e) => e.node.id);
+}
+function motionPath(scene, id, options = {}) {
+  const nodes = indexMotionNodes(scene.artwork.nodes);
+  const entry = nodes.get(id);
+  if (!entry) throw new Error(`There is no element "${id}" in the artwork.`);
+  const timeline = compileMotionScene(scene);
+  const from = Math.max(0, _nullishCoalesce(options.from, () => ( 0)));
+  const to = Math.min(timeline.duration, _nullishCoalesce(options.to, () => ( timeline.duration)));
+  let step = options.step && options.step > 0 ? options.step : 1e3 / 30;
+  if ((to - from) / step > 400) step = (to - from) / 400;
+  const r = (n) => Math.round(n * 100) / 100;
+  const centreAt = (t) => {
+    const node = indexMotionNodes(motionFrameAtCache(scene, t)).get(id);
+    const b = _optionalChain([node, 'optionalAccess', _34 => _34.bounds]);
+    return b ? { t: r(t), x: r(b.x + b.width / 2), y: r(b.y + b.height / 2) } : null;
+  };
+  const points = [];
+  for (let t = from; t <= to + 1e-6; t += step) {
+    const p = centreAt(Math.min(t, to));
+    if (p) points.push(p);
+  }
+  const owners = /* @__PURE__ */ new Set([id, ...entry.ancestors]);
+  const times = [...new Set(timeline.segments.filter((s) => owners.has(s.node) && MOVING.includes(s.property)).flatMap((s) => [s.start, s.end]))].filter((t) => t >= from && t <= to).sort((a, b) => a - b);
+  const keys = times.map(centreAt).filter((p) => p !== null);
+  return { id, points, keys };
+}
+function motionFrameAtCache(scene, t) {
+  return motionFrameAt(scene, t).document.nodes;
+}
+function motionPathsSvg(paths, camera, color = "#f43f5e") {
+  const w = Math.max(camera.width, camera.height) / 400;
+  const f = (n) => String(Math.round(n * 100) / 100);
+  return paths.filter((p) => p.points.length > 1).map(
+    (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("");
+}
+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 prefix = _nullishCoalesce(svgOptions.idPrefix, () => ( "vg-"));
+  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"), "");
+    return `<g data-onion="${g.offset < 0 ? "before" : "after"}" opacity="${g.opacity}">${inner}</g>`;
+  }) : [];
+  const camera = motionFrameAt(scene, time).camera;
+  const ids = motionPaths === true ? motionMovingIds(scene) : motionPaths ? [...motionPaths] : [];
+  const paths = ids.length ? motionPathsSvg(ids.map((id) => motionPath(scene, id)), camera, motionPathColor) : "";
+  const open = current.indexOf(">") + 1;
+  const close = current.lastIndexOf("</svg>");
+  const body = current.slice(open, close);
+  const bg = svgOptions.background !== false && scene.artwork.background ? _nullishCoalesce(_optionalChain([/^\s*<rect[^>]*\/>/, 'access', _35 => _35.exec, 'call', _36 => _36(body), 'optionalAccess', _37 => _37[0]]), () => ( "")) : "";
+  return `${current.slice(0, open)}${bg}${ghosts.join("")}${body.slice(bg.length)}${paths}</svg>`;
+}
+
 // src/animation-editor/check.ts
 var MOTION_MIN_CHANGE_MS = 120;
 var NUMERIC_PARAMS = (node, effectId) => {
-  const effect = _optionalChain([node, 'access', _34 => _34.effects, 'optionalAccess', _35 => _35.find, 'call', _36 => _36((e) => e.id === effectId)]);
+  const effect = _optionalChain([node, 'access', _38 => _38.effects, 'optionalAccess', _39 => _39.find, 'call', _40 => _40((e) => e.id === effectId)]);
   if (!effect) return null;
   return Object.entries(effect.params).filter(([, v]) => typeof v === "number").map(([k]) => k);
 };
@@ -1414,7 +1496,7 @@ function checkMotionScene(scene) {
     if (!shot.at) return;
     const timing = timeline.shots[i];
     if (timing.cue === void 0) {
-      const what = shot.at.beat !== void 0 ? `beat ${shot.at.beat}, but the scene has no beat grid; set one with set_animation_settings ({ "beat": { "bpm": \u2026 } })` : `word ${shot.at.word}, but the narration has ${_nullishCoalesce(_optionalChain([scene, 'access', _37 => _37.narration, 'optionalAccess', _38 => _38.words, 'access', _39 => _39.length]), () => ( 0))} words (indexes from 0)`;
+      const what = shot.at.beat !== void 0 ? `beat ${shot.at.beat}, but the scene has no beat grid; set one with set_animation_settings ({ "beat": { "bpm": \u2026 } })` : `word ${shot.at.word}, but the narration has ${_nullishCoalesce(_optionalChain([scene, 'access', _41 => _41.narration, 'optionalAccess', _42 => _42.words, 'access', _43 => _43.length]), () => ( 0))} words (indexes from 0)`;
       issues.push(motionIssue("unknown-cue", `Shot "${shot.id}" is cued to ${what}.`, { shot: shot.id }));
     } else if (timing.missedBy !== void 0) {
       const late = Math.round(timing.missedBy);
@@ -1447,7 +1529,7 @@ function checkMotionScene(scene) {
     const cam = frame.camera;
     const docIndex = indexMotionNodes(frame.document.nodes);
     for (const id of command2.targets) {
-      const b = _optionalChain([docIndex, 'access', _40 => _40.get, 'call', _41 => _41(id), 'optionalAccess', _42 => _42.bounds]);
+      const b = _optionalChain([docIndex, 'access', _44 => _44.get, 'call', _45 => _45(id), 'optionalAccess', _46 => _46.bounds]);
       if (!b || reported.has(id) || !visibleAt(timeline, id, timing.end, nodes.get(id).node)) continue;
       const outside = b.x + b.width < cam.x || b.y + b.height < cam.y || b.x > cam.x + cam.width || b.y > cam.y + cam.height;
       if (outside) {
@@ -1637,9 +1719,9 @@ function applyMotionEdits(scene, edits) {
   let next = scene;
   for (let i = 0; i < list.length; i++) {
     const edit = list[i];
-    const prefix = list.length > 1 ? `op ${i + 1} (${_optionalChain([edit, 'optionalAccess', _43 => _43.op])}): ` : "";
+    const prefix = list.length > 1 ? `op ${i + 1} (${_optionalChain([edit, 'optionalAccess', _47 => _47.op])}): ` : "";
     if (!edit || !MOTION_EDIT_OPS.includes(edit.op))
-      return { ok: false, error: `${prefix}Unknown op ${namedWithSuggestion(String(_optionalChain([edit, 'optionalAccess', _44 => _44.op])), MOTION_EDIT_OPS)}. Nothing was changed.` };
+      return { ok: false, error: `${prefix}Unknown op ${namedWithSuggestion(String(_optionalChain([edit, 'optionalAccess', _48 => _48.op])), MOTION_EDIT_OPS)}. Nothing was changed.` };
     try {
       next = applyOne(next, edit);
     } catch (error) {
@@ -1799,7 +1881,7 @@ function toFlairSvgMotion(scene, options = {}) {
         const wrapper = freshId(`${id}--follow`);
         const centre = freshId(`${id}--follow-centre`);
         const c = entry.center;
-        const at = _optionalChain([motionNodeOffset, 'call', _45 => _45(entry, timeline, 0, nodes), 'optionalAccess', _46 => _46.follow]);
+        const at = _optionalChain([motionNodeOffset, 'call', _49 => _49(entry, timeline, 0, nodes), 'optionalAccess', _50 => _50.follow]);
         const placed = at ? `translate(${f(at.x)} ${f(at.y)})${at.angle ? ` rotate(${f(at.angle)})` : ""}` : void 0;
         (wrap[id] ??= []).push({ id: wrapper, ...placed ? { transform: placed } : {} }, { id: centre, transform: `translate(${f(-c.x)} ${f(-c.y)})` });
         follows.push({ id, wrapper, routes: ids, segments: followSegments.filter((seg) => seg.path && ids.has(seg.path)) });
@@ -1859,7 +1941,7 @@ function toFlairSvgMotion(scene, options = {}) {
           exact: () => false,
           value: (t) => {
             const frame = motionFrameAt(scene, t, { draw: false, offsets: false });
-            const now = _chunkYJLCBA7Vcjs.expandVectorAppearance.call(void 0, _optionalChain([indexMotionNodes, 'call', _47 => _47(frame.document.nodes), 'access', _48 => _48.get, 'call', _49 => _49(id), 'optionalAccess', _50 => _50.node]));
+            const now = _chunkYJLCBA7Vcjs.expandVectorAppearance.call(void 0, _optionalChain([indexMotionNodes, 'call', _51 => _51(frame.document.nodes), 'access', _52 => _52.get, 'call', _53 => _53(id), 'optionalAccess', _54 => _54.node]));
             if (!now || now.type !== "path") return "";
             const bezier = _chunkO2UH7LZEcjs.transformBezierPath.call(void 0, _chunkYJLCBA7Vcjs.vectorPathWorldBezier.call(void 0, now, _chunkYJLCBA7Vcjs.IDENTITY_MATRIX, { effects: false }), inverse);
             return _chunkO2UH7LZEcjs.bezierPathToSvg.call(void 0, bezier, { precision: Math.min(precision, 2) });
@@ -1880,8 +1962,8 @@ function toFlairSvgMotion(scene, options = {}) {
       ...delay > 0 ? { delay: round2(delay) } : {},
       ms: round2(ms),
       ease: written,
-      ..._optionalChain([segment, 'optionalAccess', _51 => _51.behavior]) ? { behavior: segment.behavior } : {},
-      ..._optionalChain([segment, 'optionalAccess', _52 => _52.steps]) ? { strobe: segment.steps } : {}
+      ..._optionalChain([segment, 'optionalAccess', _55 => _55.behavior]) ? { behavior: segment.behavior } : {},
+      ..._optionalChain([segment, 'optionalAccess', _56 => _56.steps]) ? { strobe: segment.steps } : {}
     };
     if (channel.kind === "view") animate.push({ ...base, view: to });
     else if (channel.kind === "draw") animate.push({ ...base, draw: [from, to] });
@@ -1954,7 +2036,7 @@ function toFlairSvgMotion(scene, options = {}) {
   if (routes.length) svg = svg.replace(/^(<svg[^>]*>)/, `$1<defs>${routes.join("")}</defs>`);
   const lastChange = animate.reduce((m, a) => Math.max(m, (_nullishCoalesce(a.delay, () => ( 0))) + (_nullishCoalesce(a.ms, () => ( 0)))), 0);
   let motion = { svg, animate };
-  if (_optionalChain([scene, 'access', _53 => _53.controls, 'optionalAccess', _54 => _54.length])) {
+  if (_optionalChain([scene, 'access', _57 => _57.controls, 'optionalAccess', _58 => _58.length])) {
     const declarations = scene.controls.map((c) => `{{${c.name}: color default=${c.default.toUpperCase()}${c.label ? ` label='${c.label.replace(/'/g, "\u2019")}'` : ""}}}`).join(" ");
     const swap = (text) => scene.controls.reduce((s, c) => s.replace(new RegExp(`${c.default}(?![0-9a-fA-F])`, "gi"), `{{${c.name}}}`), text);
     svg = svg.replace(/^(<svg[^>]*>)/, `$1<!-- ${declarations} -->`);
@@ -1976,7 +2058,7 @@ function toFlairVectorEffect(scene, options = {}) {
     tags: _nullishCoalesce(options.tags, () => ( [])),
     motion: out.motion,
     hold: out.hold,
-    ..._optionalChain([scene, 'access', _55 => _55.presets, 'optionalAccess', _56 => _56.length]) ? { presets: scene.presets } : {},
+    ..._optionalChain([scene, 'access', _59 => _59.presets, 'optionalAccess', _60 => _60.length]) ? { presets: scene.presets } : {},
     ...options.trigger ? { trigger: options.trigger } : {}
   };
 }
@@ -2019,7 +2101,7 @@ function resolvePlaceholders(motion, notes) {
   const filled = text.replace(PLACEHOLDER, (_, name) => {
     const d = declared.get(name);
     if (!d) unknown.add(name);
-    return (_nullishCoalesce(_optionalChain([d, 'optionalAccess', _57 => _57.value]), () => ( ""))).replace(/"/g, '\\"');
+    return (_nullishCoalesce(_optionalChain([d, 'optionalAccess', _61 => _61.value]), () => ( ""))).replace(/"/g, '\\"');
   });
   for (const name of unknown) notes.push(`Placeholder "{{${name}}}" has no declaration, so it was left empty.`);
   return { motion: JSON.parse(filled), controls };
@@ -2073,7 +2155,7 @@ function commandsFor(anim, nodes, entered, notes) {
   if (anim.along) {
     const path = nodes.get(anim.along);
     if (!path || path.node.type !== "path") notes.push(`${where} follows "${anim.along}", which is not a path in the artwork; the follow was skipped.`);
-    else out.push({ type: "follow", targets, path: anim.along, from: _nullishCoalesce(_optionalChain([anim, 'access', _58 => _58.at, 'optionalAccess', _59 => _59[0]]), () => ( 0)), to: _nullishCoalesce(_optionalChain([anim, 'access', _60 => _60.at, 'optionalAccess', _61 => _61[1]]), () => ( 1)), ...anim.orient ? { rotate: true } : {}, ...timing, ...ease(MOTION_EASE_IN_OUT) });
+    else out.push({ type: "follow", targets, path: anim.along, from: _nullishCoalesce(_optionalChain([anim, 'access', _62 => _62.at, 'optionalAccess', _63 => _63[0]]), () => ( 0)), to: _nullishCoalesce(_optionalChain([anim, 'access', _64 => _64.at, 'optionalAccess', _65 => _65[1]]), () => ( 1)), ...anim.orient ? { rotate: true } : {}, ...timing, ...ease(MOTION_EASE_IN_OUT) });
   }
   for (const [attr, [a, b]] of Object.entries(_nullishCoalesce(anim.attrs, () => ( {})))) {
     if (attr === "opacity") {
@@ -2084,7 +2166,7 @@ function commandsFor(anim, nodes, entered, notes) {
         out.push({ type: "enter", targets, style: "fade", ...timing, ...ease(MOTION_EASE_OUT) });
       } else out.push({ type: "fade", targets, to: Math.min(1, Math.max(0, to)), ...timing, ...ease(MOTION_EASE_IN_OUT) });
     } else if (attr === "fill" || attr === "stroke") {
-      if (_optionalChain([behavior, 'optionalAccess', _62 => _62.type]) === "pulse") out.push({ type: "color-pulse", targets, color: String(b), paint: attr, count: _nullishCoalesce(behavior.count, () => ( 1)), ...timing, ...ease("linear") });
+      if (_optionalChain([behavior, 'optionalAccess', _66 => _66.type]) === "pulse") out.push({ type: "color-pulse", targets, color: String(b), paint: attr, count: _nullishCoalesce(behavior.count, () => ( 1)), ...timing, ...ease("linear") });
       else {
         if (behavior) notes.push(`${where}: a ${attr} ${behavior.type} became a plain colour change.`);
         out.push({ type: "style", targets, [attr]: String(b), ...timing, ...ease(MOTION_EASE_IN_OUT) });
@@ -2360,7 +2442,7 @@ function toLottie(scene, options = {}) {
     const shapeSegments = [...timeline.tracks.entries()].filter(([k]) => k.startsWith(`${path.id}\0`) && (k.endsWith("\0shape") || k.includes("\0effect:"))).flatMap(([, v]) => v);
     const geometryAt = (t) => {
       if (!shapeSegments.length) return _chunkYJLCBA7Vcjs.vectorPathWorldBezier.call(void 0, path);
-      const now = _optionalChain([indexMotionNodes, 'call', _63 => _63(motionFrameAt(scene, t, { draw: false, offsets: false }).document.nodes), 'access', _64 => _64.get, 'call', _65 => _65(path.id), 'optionalAccess', _66 => _66.node]);
+      const now = _optionalChain([indexMotionNodes, 'call', _67 => _67(motionFrameAt(scene, t, { draw: false, offsets: false }).document.nodes), 'access', _68 => _68.get, 'call', _69 => _69(path.id), 'optionalAccess', _70 => _70.node]);
       return now && now.type === "path" ? _chunkYJLCBA7Vcjs.vectorPathWorldBezier.call(void 0, _chunkYJLCBA7Vcjs.expandVectorAppearances.call(void 0, [now])[0]) : _chunkYJLCBA7Vcjs.vectorPathWorldBezier.call(void 0, path);
     };
     const rest = lottieContours(_chunkO2UH7LZEcjs.toBezierPath.call(void 0, geometryAt(0)), round2);
@@ -2406,7 +2488,7 @@ function toLottie(scene, options = {}) {
         lj: path.strokeLinejoin === "round" ? 2 : path.strokeLinejoin === "bevel" ? 3 : 1,
         ml: 4
       });
-      if (_optionalChain([path, 'access', _67 => _67.strokeDasharray, 'optionalAccess', _68 => _68.length])) notes.push(`"${path.id}": its dashes are not exported; the stroke is solid.`);
+      if (_optionalChain([path, 'access', _71 => _71.strokeDasharray, 'optionalAccess', _72 => _72.length])) notes.push(`"${path.id}": its dashes are not exported; the stroke is solid.`);
       if (path.strokeAlign && path.strokeAlign !== "center") notes.push(`"${path.id}": its stroke is drawn centred (Lottie has no inside or outside strokes).`);
     }
     const fill = paintOf(path.fill, "fill", path.id);
@@ -2556,7 +2638,7 @@ var AnimationEditorController = (_class = class {
       time: p.time,
       playing: p.playing,
       loop: p.loop,
-      currentShot: _nullishCoalesce(_optionalChain([motionShotAt, 'call', _69 => _69(timeline, p.time), 'optionalAccess', _70 => _70.id]), () => ( null)),
+      currentShot: _nullishCoalesce(_optionalChain([motionShotAt, 'call', _73 => _73(timeline, p.time), 'optionalAccess', _74 => _74.id]), () => ( null)),
       selection: this.selection,
       readOnly: this.readOnly,
       error: this.error,
@@ -2595,7 +2677,7 @@ var AnimationEditorController = (_class = class {
       this.applying = false;
     }
     this.notify();
-    _optionalChain([this, 'access', _71 => _71.onChange, 'optionalCall', _72 => _72(scene)]);
+    _optionalChain([this, 'access', _75 => _75.onChange, 'optionalCall', _76 => _76(scene)]);
   }
   commit(label, next) {
     const before = this.scene;
@@ -2701,7 +2783,7 @@ var AnimationEditorController = (_class = class {
   }
   /** The scene at `time` (default: the playhead) as SVG. */
   toSvg(time = this.player.currentTime, options = {}) {
-    return motionFrameToSvg(this.scene, time, options);
+    return motionStageSvg(this.scene, time, options);
   }
   /** The scene as a Flair `SvgMotion`. */
   toFlairMotion(options = {}) {
@@ -3061,10 +3143,20 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       time: MS("Time from the start"),
       shot: { ...SHOT_ID, description: 'Render a moment of this shot instead of "time".' },
       at: { type: "string", enum: ["start", "middle", "end"], description: "With shot: which moment (default end: everything drawn, before the next shot)." },
-      format: { type: "string", enum: ["svg", "png"], description: "svg (default) or png (only when the host supports it)." }
+      format: { type: "string", enum: ["svg", "png"], description: "svg (default) or png (only when the host supports it)." },
+      onion_skin: object(
+        {
+          before: { type: "integer", minimum: 0, maximum: 12, description: "Ghost frames before the moment (default 2)." },
+          after: { type: "integer", minimum: 0, maximum: 12, description: "Ghost frames after it (default 0)." },
+          spacing: { anyOf: [{ type: "number", exclusiveMinimum: 0 }, { type: "string", enum: ["commands"] }], description: 'Ms between ghosts (default 83, every other frame at 24 fps), or "commands" for the moments commands start and end.' }
+        },
+        [],
+        "Draw faded frames either side of the moment, to see motion in one picture."
+      ),
+      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" }) => {
+    handler: async ({ time, shot, at = "end", format = "svg", onion_skin, motion_paths }) => {
       const s = scene();
       let t = _nullishCoalesce(time, () => ( controller.getState().time));
       if (shot !== void 0) {
@@ -3072,7 +3164,11 @@ function createAnimationEditorToolProvider(controller, options = {}) {
         if (!timing) throw new Error(`There is no shot "${shot}"; the shots are ${s.shots.map((x) => `"${x.id}"`).join(", ") || "none yet"}.`);
         t = at === "start" ? timing.start : at === "middle" ? (timing.commandsStart + timing.commandsEnd) / 2 : Math.max(timing.start, timing.end - 1);
       }
-      const svg = controller.toSvg(t, { pretty: false });
+      if (Array.isArray(motion_paths)) {
+        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 } : {} });
       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 });
@@ -3097,9 +3193,9 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     handler: ({ from = 0, to, limit = 200 }) => {
       const s = scene();
       const timeline = compileMotionScene(s);
-      const words = _nullishCoalesce(_optionalChain([s, 'access', _73 => _73.narration, 'optionalAccess', _74 => _74.words]), () => ( []));
+      const words = _nullishCoalesce(_optionalChain([s, 'access', _77 => _77.narration, 'optionalAccess', _78 => _78.words]), () => ( []));
       const end = _nullishCoalesce(to, () => ( Math.max(timeline.duration, words.length ? _nullishCoalesce(words[words.length - 1].end, () => ( words[words.length - 1].start)) : 0)));
-      const shotAt = (ms) => _optionalChain([timeline, 'access', _75 => _75.shots, 'access', _76 => _76.find, 'call', _77 => _77((x) => ms >= x.start && ms < x.end), 'optionalAccess', _78 => _78.id]);
+      const shotAt = (ms) => _optionalChain([timeline, 'access', _79 => _79.shots, 'access', _80 => _80.find, 'call', _81 => _81((x) => ms >= x.start && ms < x.end), 'optionalAccess', _82 => _82.id]);
       const beats = [];
       if (s.beat && s.beat.bpm > 0) {
         const first = Math.max(0, Math.ceil(motionBeatAt(s.beat, from).beat - 1e-9));
@@ -3120,6 +3216,24 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       };
     }
   };
+  const getMotionPath = {
+    name: "get_motion_path",
+    title: "Read where a node travels",
+    description: "Returns where a node's centre is over time, in document units (sampled), and where it is each time a change that moves it starts or ends. Use it to check a path, spacing or arc without reading pictures; render_animation_frame with motion_paths draws it.",
+    inputSchema: object({
+      node: { type: "string", minLength: 1, description: "Element id from get_animation." },
+      from: { type: "number", minimum: 0, description: "From this time, ms (default 0)." },
+      to: { type: "number", minimum: 0, description: "To this time, ms (default the end)." },
+      step: { type: "number", exclusiveMinimum: 0, description: "Ms between samples (default 33; at most 400 samples)." }
+    }, ["node"]),
+    annotations: { title: "Read where a node travels", ...READ },
+    handler: ({ node, from, to, step }) => {
+      const s = scene();
+      const ids = describeMotionElements(s).map((e) => e.id);
+      if (!ids.includes(node)) throw new Error(`There is no element ${namedWithSuggestion(node, ids)}.`);
+      return motionPath(s, node, { from, to, step });
+    }
+  };
   const exportFlairMotion = {
     name: "export_flair_motion",
     title: "Export as Flair vector motion",
@@ -3269,7 +3383,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     inputSchema: object({ 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 run (default: the end)." } }, ["shot", "commands"]),
     annotations: { title: "Add commands to a shot", ...WRITE },
     handler: ({ shot, commands, at }) => {
-      const before = _nullishCoalesce(_optionalChain([scene, 'call', _79 => _79(), 'access', _80 => _80.shots, 'access', _81 => _81.find, 'call', _82 => _82((s) => s.id === shot), 'optionalAccess', _83 => _83.run, 'access', _84 => _84.length]), () => ( 0));
+      const before = _nullishCoalesce(_optionalChain([scene, 'call', _83 => _83(), 'access', _84 => _84.shots, 'access', _85 => _85.find, 'call', _86 => _86((s) => s.id === shot), 'optionalAccess', _87 => _87.run, 'access', _88 => _88.length]), () => ( 0));
       const first = _nullishCoalesce(at, () => ( before));
       return apply({ op: "add_commands", shot, commands, at }, "Add commands", (s) => {
         const shots = describeMotionShots(s);
@@ -3383,7 +3497,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getAnimation, getShot, findElements, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation];
+  const reads = [getAnimation, getShot, findElements, getMotionPath, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation];
   const writes = [setArtworkSvg, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
   return {
     id: _nullishCoalesce(options.id, () => ( "animation")),
@@ -3430,7 +3544,7 @@ 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, 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.
+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.
 4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.
 
 Keep motion purposeful: one thing moving at a time reads best, ease-out for arrivals, ease-in for exits, and hold long enough to see each result.`;
@@ -3525,5 +3639,10 @@ Keep motion purposeful: one thing moving at a time reads best, ease-out for arri
 
 
 
-exports.ANIMATION_EDITOR_AGENT_INSTRUCTIONS = ANIMATION_EDITOR_AGENT_INSTRUCTIONS; exports.AnimationEditorController = AnimationEditorController; exports.FLAIR_EASES = FLAIR_EASES; exports.FLAIR_EXPORT_VERSION = FLAIR_EXPORT_VERSION; exports.MOTION_ADDITIVE_PROPERTIES = MOTION_ADDITIVE_PROPERTIES; exports.MOTION_BLENDS = MOTION_BLENDS; exports.MOTION_CAMERA_MS = MOTION_CAMERA_MS; exports.MOTION_COMMAND_SCHEMA = MOTION_COMMAND_SCHEMA; exports.MOTION_COMMAND_TYPES = MOTION_COMMAND_TYPES; exports.MOTION_DEFAULT_DURATIONS = MOTION_DEFAULT_DURATIONS; exports.MOTION_DEFAULT_HOLD = MOTION_DEFAULT_HOLD; exports.MOTION_DIRECTIONS = MOTION_DIRECTIONS; exports.MOTION_DRAW_EFFECT_ID = MOTION_DRAW_EFFECT_ID; exports.MOTION_DRAW_MS_PER_UNIT = MOTION_DRAW_MS_PER_UNIT; exports.MOTION_DRAW_RANGE = MOTION_DRAW_RANGE; exports.MOTION_EASE_IN_OUT = MOTION_EASE_IN_OUT; exports.MOTION_EASE_OUT = MOTION_EASE_OUT; exports.MOTION_EDIT_OPS = MOTION_EDIT_OPS; exports.MOTION_ENTER_STYLES = MOTION_ENTER_STYLES; exports.MOTION_EXIT_STYLES = MOTION_EXIT_STYLES; exports.MOTION_IRIS_SHAPES = MOTION_IRIS_SHAPES; exports.MOTION_ISSUE_CODES = MOTION_ISSUE_CODES; exports.MOTION_MIN_CHANGE_MS = MOTION_MIN_CHANGE_MS; exports.MOTION_REPEAT_MODES = MOTION_REPEAT_MODES; exports.MOTION_SPEED_RANGE = MOTION_SPEED_RANGE; exports.MOTION_SPLIT_ORIENTATIONS = MOTION_SPLIT_ORIENTATIONS; exports.MotionSceneFormatError = MotionSceneFormatError; exports.activeSegment = activeSegment; exports.applyMotionControlValues = applyMotionControlValues; exports.applyMotionEdits = applyMotionEdits; exports.checkMotionScene = checkMotionScene; exports.commandShapeProblems = commandShapeProblems; exports.compileMotionScene = compileMotionScene; exports.createAnimationEditorToolProvider = createAnimationEditorToolProvider; exports.createMotionScene = createMotionScene; exports.describeMotionElements = describeMotionElements; exports.describeMotionShots = describeMotionShots; exports.fitMotionRect = fitMotionRect; exports.fitMotionScene = fitMotionScene; exports.flairAtLeast = flairAtLeast; exports.flairCurveFor = flairCurveFor; exports.flairEaseFor = flairEaseFor; exports.freshShotId = freshShotId; exports.fromFlairSvgMotion = fromFlairSvgMotion; exports.fromFlairVectorEffect = fromFlairVectorEffect; exports.indexMotionNodes = indexMotionNodes; exports.interpolateMotionValue = interpolateMotionValue; exports.isMotionCommand = isMotionCommand; exports.isMotionShot = isMotionShot; exports.matchMotionNodes = matchMotionNodes; exports.motionAddTrackKey = motionAddTrackKey; exports.motionBeatAt = motionBeatAt; exports.motionBeatTime = motionBeatTime; exports.motionClipAttrs = motionClipAttrs; exports.motionCommandDuration = motionCommandDuration; exports.motionCommandRepeat = motionCommandRepeat; exports.motionCueTime = motionCueTime; exports.motionCycleDuration = motionCycleDuration; exports.motionFlairPrimitive = motionFlairPrimitive; exports.motionFollowRoute = motionFollowRoute; exports.motionFrameAt = motionFrameAt; exports.motionFrameToSvg = motionFrameToSvg; exports.motionIssue = motionIssue; exports.motionIssueKey = motionIssueKey; exports.motionIssueLine = motionIssueLine; exports.motionNodeClips = motionNodeClips; exports.motionNodeOffset = motionNodeOffset; exports.motionPathLength = motionPathLength; exports.motionRestValue = motionRestValue; exports.motionRevealClip = motionRevealClip; exports.motionRevealPadding = motionRevealPadding; exports.motionSceneShapeProblems = motionSceneShapeProblems; exports.motionSceneToJson = motionSceneToJson; exports.motionShotAt = motionShotAt; exports.motionShotTimeScale = motionShotTimeScale; exports.motionTrackKey = motionTrackKey; exports.namedWithSuggestion = namedWithSuggestion; exports.parseMotionScene = parseMotionScene; exports.resolveMotionCamera = resolveMotionCamera; exports.segmentProgress = segmentProgress; exports.segmentValue = segmentValue; exports.shotShapeProblems = shotShapeProblems; exports.suggestName = suggestName; exports.toFlairEffectDocument = toFlairEffectDocument; exports.toFlairSvgMotion = toFlairSvgMotion; exports.toFlairVectorEffect = toFlairVectorEffect; exports.toLottie = toLottie; exports.trackValue = trackValue; exports.withMotionLayers = withMotionLayers; exports.withViewBox = withViewBox;
+
+
+
+
+
+exports.ANIMATION_EDITOR_AGENT_INSTRUCTIONS = ANIMATION_EDITOR_AGENT_INSTRUCTIONS; exports.AnimationEditorController = AnimationEditorController; exports.FLAIR_EASES = FLAIR_EASES; exports.FLAIR_EXPORT_VERSION = FLAIR_EXPORT_VERSION; exports.MOTION_ADDITIVE_PROPERTIES = MOTION_ADDITIVE_PROPERTIES; exports.MOTION_BLENDS = MOTION_BLENDS; exports.MOTION_CAMERA_MS = MOTION_CAMERA_MS; exports.MOTION_COMMAND_SCHEMA = MOTION_COMMAND_SCHEMA; exports.MOTION_COMMAND_TYPES = MOTION_COMMAND_TYPES; exports.MOTION_DEFAULT_DURATIONS = MOTION_DEFAULT_DURATIONS; exports.MOTION_DEFAULT_HOLD = MOTION_DEFAULT_HOLD; exports.MOTION_DIRECTIONS = MOTION_DIRECTIONS; exports.MOTION_DRAW_EFFECT_ID = MOTION_DRAW_EFFECT_ID; exports.MOTION_DRAW_MS_PER_UNIT = MOTION_DRAW_MS_PER_UNIT; exports.MOTION_DRAW_RANGE = MOTION_DRAW_RANGE; exports.MOTION_EASE_IN_OUT = MOTION_EASE_IN_OUT; exports.MOTION_EASE_OUT = MOTION_EASE_OUT; exports.MOTION_EDIT_OPS = MOTION_EDIT_OPS; exports.MOTION_ENTER_STYLES = MOTION_ENTER_STYLES; exports.MOTION_EXIT_STYLES = MOTION_EXIT_STYLES; exports.MOTION_IRIS_SHAPES = MOTION_IRIS_SHAPES; exports.MOTION_ISSUE_CODES = MOTION_ISSUE_CODES; exports.MOTION_MIN_CHANGE_MS = MOTION_MIN_CHANGE_MS; exports.MOTION_REPEAT_MODES = MOTION_REPEAT_MODES; exports.MOTION_SPEED_RANGE = MOTION_SPEED_RANGE; exports.MOTION_SPLIT_ORIENTATIONS = MOTION_SPLIT_ORIENTATIONS; exports.MotionSceneFormatError = MotionSceneFormatError; exports.activeSegment = activeSegment; exports.applyMotionControlValues = applyMotionControlValues; exports.applyMotionEdits = applyMotionEdits; exports.checkMotionScene = checkMotionScene; exports.commandShapeProblems = commandShapeProblems; exports.compileMotionScene = compileMotionScene; exports.createAnimationEditorToolProvider = createAnimationEditorToolProvider; exports.createMotionScene = createMotionScene; exports.describeMotionElements = describeMotionElements; exports.describeMotionShots = describeMotionShots; exports.fitMotionRect = fitMotionRect; exports.fitMotionScene = fitMotionScene; exports.flairAtLeast = flairAtLeast; exports.flairCurveFor = flairCurveFor; exports.flairEaseFor = flairEaseFor; exports.freshShotId = freshShotId; exports.fromFlairSvgMotion = fromFlairSvgMotion; exports.fromFlairVectorEffect = fromFlairVectorEffect; exports.indexMotionNodes = indexMotionNodes; exports.interpolateMotionValue = interpolateMotionValue; exports.isMotionCommand = isMotionCommand; exports.isMotionShot = isMotionShot; exports.matchMotionNodes = matchMotionNodes; exports.motionAddTrackKey = motionAddTrackKey; exports.motionBeatAt = motionBeatAt; exports.motionBeatTime = motionBeatTime; exports.motionClipAttrs = motionClipAttrs; exports.motionCommandDuration = motionCommandDuration; exports.motionCommandRepeat = motionCommandRepeat; exports.motionCueTime = motionCueTime; exports.motionCycleDuration = motionCycleDuration; exports.motionFlairPrimitive = motionFlairPrimitive; exports.motionFollowRoute = motionFollowRoute; exports.motionFrameAt = motionFrameAt; exports.motionFrameToSvg = motionFrameToSvg; exports.motionGhosts = motionGhosts; exports.motionIssue = motionIssue; exports.motionIssueKey = motionIssueKey; exports.motionIssueLine = motionIssueLine; exports.motionMovingIds = motionMovingIds; exports.motionNodeClips = motionNodeClips; exports.motionNodeOffset = motionNodeOffset; exports.motionPath = motionPath; exports.motionPathLength = motionPathLength; exports.motionPathsSvg = motionPathsSvg; exports.motionRestValue = motionRestValue; exports.motionRevealClip = motionRevealClip; exports.motionRevealPadding = motionRevealPadding; exports.motionSceneShapeProblems = motionSceneShapeProblems; exports.motionSceneToJson = motionSceneToJson; exports.motionShotAt = motionShotAt; exports.motionShotTimeScale = motionShotTimeScale; exports.motionStageSvg = motionStageSvg; exports.motionTrackKey = motionTrackKey; exports.namedWithSuggestion = namedWithSuggestion; exports.parseMotionScene = parseMotionScene; exports.resolveMotionCamera = resolveMotionCamera; exports.segmentProgress = segmentProgress; exports.segmentValue = segmentValue; exports.shotShapeProblems = shotShapeProblems; exports.suggestName = suggestName; exports.toFlairEffectDocument = toFlairEffectDocument; exports.toFlairSvgMotion = toFlairSvgMotion; exports.toFlairVectorEffect = toFlairVectorEffect; exports.toLottie = toLottie; exports.trackValue = trackValue; exports.withMotionLayers = withMotionLayers; exports.withViewBox = withViewBox;
 //# sourceMappingURL=index.cjs.map