@pixerate/editor 0.64.0 → 0.66.0

package/dist/animation-editor/index.js

@@ -45,6 +45,7 @@ import {
   rgbaToHex
 } from "../chunk-TGD52FEZ.js";
 import {
+  ANIMATION_EASING_LABELS,
   ANIMATION_EASING_PRESETS,
   evaluateEasing,
   isAnimationEasing,
@@ -1258,6 +1259,88 @@ 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(onion.before ?? 2));
+  const after = Math.max(0, Math.floor(onion.after ?? 0));
+  const base = Math.min(1, Math.max(0, 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, options.from ?? 0);
+  const to = Math.min(timeline.duration, 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 = node?.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 = 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 ? /^\s*<rect[^>]*\/>/.exec(body)?.[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) => {
@@ -1481,6 +1564,7 @@ var MOTION_EDIT_OPS = [
   "add_commands",
   "update_command",
   "delete_commands",
+  "move_command",
   "set_artwork",
   "set_controls",
   "replace_scene"
@@ -1605,6 +1689,16 @@ function applyOne(scene, edit) {
       const drop = new Set(edit.commands);
       return replaceShot(scene, i, { ...scene.shots[i], run: run.filter((_, k) => !drop.has(k)) });
     }
+    case "move_command": {
+      const i = shotIndex(scene, edit.shot);
+      const run = [...scene.shots[i].run];
+      if (!Number.isInteger(edit.command) || edit.command < 0 || edit.command >= run.length)
+        fail(`Shot "${edit.shot}" has ${run.length} command${run.length === 1 ? "" : "s"}; "command" must be an index from 0 to ${run.length - 1} (got ${edit.command}).`);
+      const to = position(edit.to, run.length - 1, '"to"');
+      const [moved] = run.splice(edit.command, 1);
+      run.splice(to, 0, moved);
+      return replaceShot(scene, i, { ...scene.shots[i], run });
+    }
     case "set_artwork":
       return { ...scene, artwork: edit.artwork };
     case "set_controls": {
@@ -2173,11 +2267,17 @@ function fromFlairSvgMotion(input, options = {}) {
 ${problems.join("\n")}`);
   return { scene, notes: [...new Set(notes)], issues: checkMotionScene(scene) };
 }
+function presetColor(value) {
+  if (typeof value === "string") return /^#[0-9a-f]{6}$/i.test(value) ? value.toLowerCase() : value;
+  if (Array.isArray(value) && value.length >= 3 && value.slice(0, 3).every((n) => typeof n === "number" && Number.isFinite(n)))
+    return `#${value.slice(0, 3).map((n) => Math.round(Math.min(1, Math.max(0, n)) * 255).toString(16).padStart(2, "0")).join("")}`;
+  return void 0;
+}
 function fromFlairVectorEffect(effect, options = {}) {
   if (!effect || effect.kind !== "vector" || !effect.motion) throw new Error('Give a Flair vector effect: { kind: "vector", id, name, motion: { svg, animate } }.');
   const result = fromFlairSvgMotion(effect.motion, { name: options.name ?? effect.id ?? effect.name, hold: options.hold ?? effect.hold });
   const names = new Set((result.scene.controls ?? []).map((c) => c.name));
-  const presets = (effect.presets ?? []).map((p) => ({ name: p.name, values: Object.fromEntries(Object.entries(p.values).filter(([k]) => names.has(k))) })).filter((p) => Object.keys(p.values).length);
+  const presets = (effect.presets ?? []).map((p) => ({ name: p.name, values: Object.fromEntries(Object.entries(p.values).flatMap(([k, v]) => names.has(k) && presetColor(v) ? [[k, presetColor(v)]] : [])) })).filter((p) => Object.keys(p.values).length);
   const scene = { ...result.scene, ...effect.description ? { description: effect.description } : {}, ...presets.length ? { presets } : {} };
   const notes = [...result.notes];
   if (effect.trigger) notes.push(`The effect plays on ${effect.trigger}; scenes play through, so the trigger is not kept (pass it back to toFlairVectorEffect).`);
@@ -2701,7 +2801,7 @@ var AnimationEditorController = 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 = {}) {
@@ -2914,6 +3014,7 @@ var EDIT_OP = {
     object({ op: { const: "move_shot", description: "Like move_shot." }, shot: SHOT_ID, to: { type: "integer", minimum: 0, description: "New position (0 = first)." } }, ["op", "shot", "to"]),
     object({ op: { const: "add_commands", description: "Like add_commands." }, shot: SHOT_ID, commands: { type: "array", items: MOTION_COMMAND_SCHEMA, minItems: 1, description: "Commands to add." }, at: { type: "integer", minimum: 0, description: "Index in the shot's run (default: the end)." } }, ["op", "shot", "commands"]),
     object({ op: { const: "update_command", description: "Like update_command." }, shot: SHOT_ID, command: { type: "integer", minimum: 0, description: "Index in the shot's run." }, set: { type: "object", description: "Command fields to replace." }, remove: { type: "array", items: { type: "string" }, description: "Command fields to clear." } }, ["op", "shot", "command"]),
+    object({ op: { const: "move_command", description: "Like move_command." }, shot: SHOT_ID, command: { type: "integer", minimum: 0, description: "Index in the shot's run." }, to: { type: "integer", minimum: 0, description: "New index in the run (0 = first)." } }, ["op", "shot", "command", "to"]),
     object({ op: { const: "delete_commands", description: "Like delete_commands." }, shot: SHOT_ID, commands: { type: "array", items: { type: "integer", minimum: 0 }, minItems: 1, description: "Indexes in the shot's run." } }, ["op", "shot", "commands"]),
     object({ op: { const: "set_controls", description: "Like set_controls." }, controls: { type: "array", items: CONTROL, description: "Controls (empty clears)." }, presets: { type: "array", items: PRESET, description: "Presets (empty clears)." } }, ["op", "controls"])
   ]
@@ -3061,10 +3162,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 = time ?? controller.getState().time;
       if (shot !== void 0) {
@@ -3072,7 +3183,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 });
@@ -3120,6 +3235,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",
@@ -3302,6 +3435,21 @@ function createAnimationEditorToolProvider(controller, options = {}) {
     annotations: { title: "Delete commands", ...DESTRUCTIVE },
     handler: ({ shot, commands }) => apply({ op: "delete_commands", shot, commands }, "Delete commands")
   };
+  const moveCommand = {
+    name: "move_command",
+    title: "Reorder a command",
+    description: `Moves one command to a new index in its shot's run (0 = first), as one undo step; the others close up around it. A command with "with": "previous" then starts with its new neighbour. Returns the command's new index, its old one and the shot's timing.`,
+    inputSchema: object(
+      {
+        shot: SHOT_ID,
+        command: { type: "integer", minimum: 0, description: "Index of the command in the shot's run (from get_animation)." },
+        to: { type: "integer", minimum: 0, description: "Its new index, 0 = first (at most the last index)." }
+      },
+      ["shot", "command", "to"]
+    ),
+    annotations: { title: "Reorder a command", ...WRITE },
+    handler: ({ shot, command: command2, to }) => apply({ op: "move_command", shot, command: command2, to }, "Move command", (s) => ({ shot, command: to, from: command2, commands: describeMotionShots(s).find((x) => x.id === shot).commands.map((c) => ({ index: c.index, type: c.type, start: c.start, end: c.end })) }))
+  };
   const setSettings = {
     name: "set_animation_settings",
     title: "Change animation settings",
@@ -3383,8 +3531,8 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getAnimation, getShot, findElements, 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];
+  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, moveCommand, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
   return {
     id: options.id ?? "animation",
     namespace: options.namespace,
@@ -3429,11 +3577,285 @@ 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.
+2. Plan a few shots, each one idea. Add them with insert_shots (add_commands, update_command, move_command and delete_commands refine a shot), or edit_animation to make several edits as one step (dry_run first when unsure).
+3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + "end") to look at the result; add onion_skin or motion_paths to see the motion in one picture, or get_motion_path for the numbers.
 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.`;
+
+// src/animation-editor/form.ts
+var TIMING = /* @__PURE__ */ new Set(["duration", "delay", "stagger", "with", "ease", "repeat", "repeatMode", "steps", "note"]);
+var COLORS = /* @__PURE__ */ new Set(["fill", "stroke", "color"]);
+var NODES = /* @__PURE__ */ new Set(["into", "path"]);
+function branch(type) {
+  return (MOTION_COMMAND_SCHEMA.oneOf ?? []).find((b) => b.properties?.type?.const === type);
+}
+function unitOf(type, name) {
+  if (name === "duration" || name === "delay" || name === "stagger") return "ms";
+  if (name === "steps") return "fps";
+  if (name === "frequency") return "Hz";
+  if (name === "repeat" || name === "count") return "\xD7";
+  if (name === "distance" || name === "strokeWidth") return "units";
+  if (name === "angle") return "\xB0";
+  if (name === "amount") return type === "pulse" ? "\xD7" : "units";
+  if (name === "rotate" && type === "wiggle") return "\xB0";
+  if ((name === "by" || name === "to") && type === "rotate") return "\xB0";
+  if (name === "scale" || name === "to" && type === "scale") return "\xD7";
+  if ((name === "from" || name === "to") && (type === "draw" || type === "fade" || type === "follow")) return "0\u20131";
+  return void 0;
+}
+function motionFieldLabel(name) {
+  const words = name.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function kindOf(name, schema) {
+  if (name === "targets") return "targets";
+  if (name === "ease") return "ease";
+  if (schema.enum) return "enum";
+  if (schema.anyOf) return "scale";
+  if (schema.type === "object") return "point";
+  if (schema.type === "boolean") return "boolean";
+  if (schema.type === "integer") return "integer";
+  if (schema.type === "number") return "number";
+  if (COLORS.has(name)) return "color";
+  if (NODES.has(name)) return "node";
+  return "text";
+}
+function motionCommandFields(type) {
+  const schema = branch(type);
+  if (!schema?.properties) return [];
+  const required = new Set(schema.required ?? []);
+  const fields = Object.entries(schema.properties).filter(([name]) => name !== "type").map(([name, s]) => {
+    const kind = kindOf(name, s);
+    const min = typeof s.minimum === "number" ? s.minimum : typeof s.exclusiveMinimum === "number" ? s.exclusiveMinimum : void 0;
+    return {
+      name,
+      kind,
+      label: motionFieldLabel(name),
+      description: s.description ?? "",
+      required: required.has(name),
+      ...s.enum ? { options: s.enum.map(String) } : {},
+      ...min !== void 0 ? { min } : {},
+      ...typeof s.maximum === "number" ? { max: s.maximum } : {},
+      ...unitOf(type, name) ? { unit: unitOf(type, name) } : {},
+      group: TIMING.has(name) ? "timing" : "main"
+    };
+  });
+  return [...fields.filter((f) => f.group === "main"), ...fields.filter((f) => f.group === "timing")];
+}
+function parseMotionFieldInput(field, raw) {
+  if (field.kind === "boolean") return raw === true ? { set: true } : { remove: true };
+  if (field.kind === "targets") {
+    const ids = (Array.isArray(raw) ? raw : String(raw).split(",")).map((s) => String(s).trim()).filter(Boolean);
+    return ids.length ? { set: ids } : { error: "Pick at least one target." };
+  }
+  if (field.kind === "point" || field.kind === "scale" && typeof raw === "object" && !Array.isArray(raw)) {
+    const p = raw;
+    if (p.x.trim() === "" && p.y.trim() === "") return field.required ? { error: `${field.label} is required.` } : { remove: true };
+    const x = Number(p.x);
+    const y = Number(p.y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return { error: `${field.label} needs a number for x and for y.` };
+    return { set: { x, y } };
+  }
+  const text = String(raw).trim();
+  if (text === "") return field.required ? { error: `${field.label} is required.` } : { remove: true };
+  if (field.kind === "number" || field.kind === "integer" || field.kind === "scale") {
+    const n = Number(text);
+    if (!Number.isFinite(n)) return { error: `${field.label} must be a number${field.unit ? ` (${field.unit})` : ""}.` };
+    if (field.kind === "integer" && !Number.isInteger(n)) return { error: `${field.label} must be a whole number.` };
+    if (field.min !== void 0 && n < field.min) return { error: `${field.label} must be at least ${field.min}.` };
+    if (field.max !== void 0 && n > field.max) return { error: `${field.label} must be at most ${field.max}.` };
+    return { set: n };
+  }
+  if (field.kind === "enum" && field.options && !field.options.includes(text)) return { error: `${field.label} must be one of ${field.options.join(", ")}.` };
+  return { set: text };
+}
+function motionFieldEdit(shot, command2, field, raw) {
+  const input = parseMotionFieldInput(field, raw);
+  if ("error" in input) return input;
+  if ("remove" in input) return { op: "update_command", shot, command: command2, remove: [field.name] };
+  return { op: "update_command", shot, command: command2, set: { [field.name]: input.set } };
+}
+function defaultMotionCommand(type, targets, scene) {
+  if (type === "wait") return { type: "wait", duration: 500 };
+  if (!targets.length) return { error: "Pick a target first: click an element on the stage." };
+  const nodes = [...indexMotionNodes(scene.artwork.nodes).values()];
+  const other = (pred) => nodes.find((e) => !targets.includes(e.node.id) && pred(e))?.node.id;
+  const base = { targets: [...targets] };
+  switch (type) {
+    case "scale":
+      return { type, ...base, to: 1.2 };
+    case "fade":
+      return { type, ...base, to: 0.5 };
+    case "move":
+      return { type, ...base, by: { x: 40, y: 0 } };
+    case "rotate":
+      return { type, ...base, by: 90 };
+    case "style":
+      return { type, ...base, fill: "#f59e0b" };
+    case "morph": {
+      const into = other((e) => e.node.type === "path" && e.node.visible === false) ?? other((e) => e.node.type === "path");
+      return into ? { type, ...base, into } : { error: "Morph needs another shape to become; draw one (it can stay hidden)." };
+    }
+    case "match": {
+      const into = other((e) => e.node.type === "group" && e.node.visible === false) ?? other((e) => e.node.type === "group");
+      return into ? { type, ...base, into } : { error: "Match needs another group to become; group the end state (it can stay hidden)." };
+    }
+    case "follow": {
+      const path = other((e) => e.node.type === "path" && e.node.visible === false) ?? other((e) => e.node.type === "path");
+      return path ? { type, ...base, path } : { error: "Follow needs a path to travel along; draw one (it can stay hidden)." };
+    }
+    case "effect": {
+      for (const id of targets) {
+        const node = nodes.find((e) => e.node.id === id)?.node;
+        for (const effect of node?.effects ?? []) {
+          const param = Object.entries(effect.params).find(([, v]) => typeof v === "number");
+          if (param) return { type, ...base, effect: effect.id, param: param[0], to: param[1] + 1 };
+        }
+      }
+      return { error: "Effect needs a target with a live path effect (wiggle, twist, zig zag\u2026)." };
+    }
+    default:
+      return { type, ...base };
+  }
+}
+function motionCommandSummary(command2) {
+  const c = command2;
+  const what = [command2.type, typeof c.style === "string" ? c.style : ""].filter(Boolean).join(" ");
+  if (command2.type === "wait") return `wait ${command2.duration} ms`;
+  const extra = typeof c.into === "string" ? ` \u2192 ${c.into}` : typeof c.path === "string" ? ` along ${c.path}` : "";
+  return `${what} \xB7 ${(command2.targets ?? []).join(", ")}${extra}`;
+}
+function motionCommandRows(scene, shotId) {
+  const index = scene.shots.findIndex((s) => s.id === shotId);
+  if (index < 0) return [];
+  const timeline = compileMotionScene(scene);
+  return scene.shots[index].run.map((command2, i) => {
+    const t = timeline.commands.find((c) => c.shotIndex === index && c.command === i);
+    const primitive = motionFlairPrimitive(command2);
+    return { index: i, command: command2, summary: motionCommandSummary(command2), start: t?.start ?? 0, end: t?.end ?? 0, ...primitive ? { flairPrimitive: primitive } : {} };
+  });
+}
+function duplicateMotionCommandEdit(scene, shot, command2) {
+  const run = scene.shots.find((s) => s.id === shot)?.run ?? [];
+  return { op: "add_commands", shot, commands: run[command2] ? [structuredClone(run[command2])] : [], at: command2 + 1 };
+}
+var MOTION_EASE_CHOICES = [
+  { value: "", label: "Default" },
+  ...ANIMATION_EASING_PRESETS.map((p) => ({ value: p, label: ANIMATION_EASING_LABELS[p] }))
+];
+function motionEaseKey(ease) {
+  if (ease === void 0 || ease === null) return "";
+  return typeof ease === "string" ? ease : "custom";
+}
+function motionEasingCurve(ease, samples = 48, durationMs = 1e3) {
+  const resolved = resolveEasing(ease);
+  const ms = resolved !== "hold" && resolved.type === "spring" ? springSettleMs(resolved) : durationMs;
+  const n = Math.max(2, Math.floor(samples));
+  const points = [];
+  for (let i = 0; i <= n; i++) {
+    const u = i / n;
+    points.push({ u, v: resolved === "hold" ? i === n ? 1 : 0 : evaluateEasing(ease, u, ms) });
+  }
+  const values = points.map((p) => p.v);
+  return { points, min: Math.min(0, ...values), max: Math.max(1, ...values), durationMs: ms };
+}
+function motionEasingPath(curve, width, height, pad = 4) {
+  const span = curve.max - curve.min || 1;
+  const f = (n) => String(Math.round(n * 100) / 100);
+  return curve.points.map((p, i) => `${i ? "L" : "M"}${f(pad + p.u * (width - 2 * pad))} ${f(pad + (1 - (p.v - curve.min) / span) * (height - 2 * pad))}`).join(" ");
+}
+function motionEasingGuides(curve, height, pad = 4) {
+  const span = curve.max - curve.min || 1;
+  const y = (v) => pad + (1 - (v - curve.min) / span) * (height - 2 * pad);
+  return { zero: y(0), one: y(1) };
+}
+function motionNodeAtElement(scene, target, root) {
+  const ids = indexMotionNodes(scene.artwork.nodes);
+  for (let el = target; el && el !== root; el = el.parentElement) {
+    const id = el.getAttribute("id");
+    if (id && ids.has(id)) return id;
+  }
+  return null;
+}
+var escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function highlightMotionSvg(svg, ids, color = "#f43f5e") {
+  if (!ids.length) return svg;
+  let out = svg;
+  for (const id of ids) {
+    const escaped = id.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+    out = out.replace(new RegExp(` id="${escapeRegExp(escaped)}"`), ` id="${escaped}" data-picked=""`);
+  }
+  return out.replace(/(<svg\b[^>]*>)/, `$1<style>[data-picked]{filter:drop-shadow(0 0 1px #fff) drop-shadow(0 0 3px ${color}) drop-shadow(0 0 3px ${color})}</style>`);
+}
+function motionRulerTicks(duration, width, minGap = 56) {
+  const span = Math.max(1, duration);
+  const steps = [100, 250, 500, 1e3, 2e3, 5e3, 1e4, 3e4, 6e4];
+  const step = steps.find((s) => s / span * Math.max(1, width) >= minGap) ?? steps[steps.length - 1];
+  const ticks = [];
+  for (let t = 0; t <= span + 1e-6; t += step / 2) {
+    const major = Math.round(t / (step / 2)) % 2 === 0;
+    ticks.push({ time: t, major, label: major ? `${step < 1e3 ? (t / 1e3).toFixed(step < 500 ? 2 : 1) : String(Math.round(t / 1e3))}s` : "" });
+  }
+  return ticks;
+}
+function fitMotionSceneEdits(scene, ms, options = {}) {
+  const fit = fitMotionScene(scene, ms, options);
+  return fit.scene.shots.flatMap((shot, i) => {
+    const before = scene.shots[i].speed;
+    if (before === shot.speed) return [];
+    return shot.speed === void 0 ? [{ op: "update_shot", shot: shot.id, remove: ["speed"] }] : [{ op: "update_shot", shot: shot.id, set: { speed: shot.speed } }];
+  });
+}
+function motionCueKey(cue) {
+  if (!cue) return "";
+  if (typeof cue.beat === "number") return `beat:${cue.beat}`;
+  if (typeof cue.word === "number") return `word:${cue.word}`;
+  if (typeof cue.ms === "number") return `ms:${cue.ms}`;
+  return "";
+}
+function motionCueFromKey(key) {
+  const m = /^(beat|word|ms):(-?\d+(?:\.\d+)?)$/.exec(key);
+  if (!m) return void 0;
+  return { [m[1]]: Number(m[2]) };
+}
+function motionCueChoices(scene, limit = 256) {
+  const choices = [];
+  const s = (ms) => `${(ms / 1e3).toFixed(2)} s`;
+  const end = Math.max(compileMotionScene(scene).duration, ...scene.narration?.words.map((w) => w.end ?? w.start) ?? [0]) + 2e3;
+  if (scene.beat && scene.beat.bpm > 0) {
+    for (let beat = 0; choices.length < limit; beat++) {
+      const time = motionBeatTime(scene.beat, beat);
+      if (time > end) break;
+      if (time < 0) continue;
+      const at = motionBeatAt(scene.beat, time);
+      choices.push({ value: `beat:${beat}`, label: `Beat ${beat} (bar ${at.bar}.${at.beatInBar}) \xB7 ${s(time)}`, time });
+    }
+  }
+  scene.narration?.words.forEach((w, i) => {
+    if (choices.length < limit * 2) choices.push({ value: `word:${i}`, label: `Word ${i} \u201C${w.text}\u201D \xB7 ${s(w.start)}`, time: w.start });
+  });
+  return choices;
+}
+function motionShotCueTime(scene, cue) {
+  return cue ? motionCueTime(scene, cue) : void 0;
+}
+function formatMotionNarration(narration) {
+  return (narration?.words ?? []).map((w) => `${w.start} ${w.text}`).join("\n");
+}
+function parseMotionNarration(text) {
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  if (!lines.length) return { narration: null };
+  const words = [];
+  for (const [i, line] of lines.entries()) {
+    const m = /^(\d+(?:\.\d+)?)\s+(.+)$/.exec(line);
+    if (!m) return { error: `Line ${i + 1} ("${line}") should be a start time in ms and a word, e.g. "1200 hello".` };
+    const start = Number(m[1]);
+    if (words.length && start < words[words.length - 1].start) return { error: `Line ${i + 1} starts before the word above it; keep the words in time order.` };
+    words.push({ text: m[2], start });
+  }
+  return { narration: { words } };
+}
 export {
   ANIMATION_EDITOR_AGENT_INSTRUCTIONS,
   AnimationEditorController,
@@ -3450,6 +3872,7 @@ export {
   MOTION_DRAW_EFFECT_ID,
   MOTION_DRAW_MS_PER_UNIT,
   MOTION_DRAW_RANGE,
+  MOTION_EASE_CHOICES,
   MOTION_EASE_IN_OUT,
   MOTION_EASE_OUT,
   MOTION_EDIT_OPS,
@@ -3470,16 +3893,21 @@ export {
   compileMotionScene,
   createAnimationEditorToolProvider,
   createMotionScene,
+  defaultMotionCommand,
   describeMotionElements,
   describeMotionShots,
+  duplicateMotionCommandEdit,
   fitMotionRect,
   fitMotionScene,
+  fitMotionSceneEdits,
   flairAtLeast,
   flairCurveFor,
   flairEaseFor,
+  formatMotionNarration,
   freshShotId,
   fromFlairSvgMotion,
   fromFlairVectorEffect,
+  highlightMotionSvg,
   indexMotionNodes,
   interpolateMotionValue,
   isMotionCommand,
@@ -3490,28 +3918,50 @@ export {
   motionBeatTime,
   motionClipAttrs,
   motionCommandDuration,
+  motionCommandFields,
   motionCommandRepeat,
+  motionCommandRows,
+  motionCommandSummary,
+  motionCueChoices,
+  motionCueFromKey,
+  motionCueKey,
   motionCueTime,
   motionCycleDuration,
+  motionEaseKey,
+  motionEasingCurve,
+  motionEasingGuides,
+  motionEasingPath,
+  motionFieldEdit,
+  motionFieldLabel,
   motionFlairPrimitive,
   motionFollowRoute,
   motionFrameAt,
   motionFrameToSvg,
+  motionGhosts,
   motionIssue,
   motionIssueKey,
   motionIssueLine,
+  motionMovingIds,
+  motionNodeAtElement,
   motionNodeClips,
   motionNodeOffset,
+  motionPath,
   motionPathLength,
+  motionPathsSvg,
   motionRestValue,
   motionRevealClip,
   motionRevealPadding,
+  motionRulerTicks,
   motionSceneShapeProblems,
   motionSceneToJson,
   motionShotAt,
+  motionShotCueTime,
   motionShotTimeScale,
+  motionStageSvg,
   motionTrackKey,
   namedWithSuggestion,
+  parseMotionFieldInput,
+  parseMotionNarration,
   parseMotionScene,
   resolveMotionCamera,
   segmentProgress,