@pixerate/editor 0.74.0 → 0.75.0

package/dist/animation-editor/index.js

@@ -20,14 +20,14 @@ import {
   vectorDocumentToSvg,
   vectorNodeBounds,
   vectorPathWorldBezier
-} from "../chunk-3TLL5OID.js";
+} from "../chunk-4JLB2USO.js";
 import {
   bezierPathLength,
   bezierPathPointAtLength,
   bezierPathToSvg,
   toBezierPath,
   transformBezierPath
-} from "../chunk-GTMJ4Y3S.js";
+} from "../chunk-YCSFS3GK.js";
 import {
   readZip
 } from "../chunk-33AHNSEB.js";
@@ -61,6 +61,8 @@ import {
 
 // src/animation-editor/types.ts
 var MOTION_TRIGGERS = ["click", "hover", "press", "scroll"];
+var MOTION_TEXT_UNITS = ["letter", "word", "line"];
+var MOTION_CASCADES = ["forward", "backward", "center", "edges", "random"];
 var MOTION_DRIVEN_PROPERTIES = ["x", "y", "rotation", "scaleX", "scaleY", "opacity"];
 var MOTION_CLIP_TARGET = "$";
 var MOTION_COMMAND_TYPES = [
@@ -148,6 +150,7 @@ var MOTION_ISSUE_CODES = {
   "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." },
+  "split-not-text": { severity: "warning", wording: "A command splits a target into letters, but it is not a group of letter paths, so it animates as a whole." },
   "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)." },
@@ -229,7 +232,7 @@ ${problems.map((p) => `- ${p}`).join("\n")}`);
 var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "clips", "drivers", "motionBlur", "loop", "trigger", "fps", "steps", "beat", "narration", "target", "controls", "presets"];
 var SHOT_KEYS = ["id", "label", "camera", "at", "run", "hold", "speed"];
 var CAMERA_KEYS = ["x", "y", "width", "height", "frame", "padding", "ease", "ms", "geometric"];
-var BASE_KEYS = ["type", "targets", "duration", "delay", "stagger", "with", "ease", "note", "repeat", "repeatMode", "steps"];
+var BASE_KEYS = ["type", "targets", "duration", "delay", "stagger", "with", "ease", "note", "repeat", "repeatMode", "steps", "split", "cascade"];
 var DRAW_ORDER_KEYS = ["order", "pace", "align", "sortBy", "origin"];
 var COMMAND_KEYS = {
   enter: [...BASE_KEYS, ...DRAW_ORDER_KEYS, "style", "direction", "distance", "scale", "shape", "orientation"],
@@ -301,6 +304,9 @@ function commandShapeProblems(command3, where) {
     else if (!(Number.isInteger(command3.repeat) && command3.repeat >= 1 && command3.repeat <= 1e3)) p(`"repeat" must be a whole number from 1 to 1000.`);
   }
   if (command3.blend !== void 0 && !MOTION_BLENDS.includes(command3.blend)) p(`"blend" must be "replace" (the change takes over) or "add" (a layer on top).`);
+  if (command3.split !== void 0 && !MOTION_TEXT_UNITS.includes(command3.split)) p(`"split" must be letter, word or line (for outlined text: a group of letter paths).`);
+  if (command3.cascade !== void 0 && !MOTION_CASCADES.includes(command3.cascade)) p(`"cascade" must be one of ${MOTION_CASCADES.join(", ")}.`);
+  if (command3.cascade !== void 0 && command3.split === void 0) p(`"cascade" goes with "split".`);
   if (command3.repeatMode !== void 0 && !MOTION_REPEAT_MODES.includes(command3.repeatMode)) p(`"repeatMode" must be one of ${MOTION_REPEAT_MODES.join(", ")}.`);
   if (command3.steps !== void 0 && !(isNum(command3.steps) && command3.steps > 0 && command3.steps <= 120)) p(`"steps" must be frames per second from above 0 to 120 (12 holds each pose for two frames at 24 fps).`);
   switch (type) {
@@ -616,6 +622,87 @@ function smoothMotionTimes(points, start, duration, pacing = "even") {
   return times;
 }
 
+// src/animation-editor/text.ts
+function motionTextLayout(nodes, id) {
+  const group = nodes.get(id)?.node;
+  if (!group || group.type !== "group") return null;
+  const letters = collectPathNodes(group).map((p) => ({ id: p.id, b: nodes.get(p.id)?.bounds })).filter((l) => !!l.b && l.b.width + l.b.height > 0);
+  if (!letters.length) return null;
+  const lines = [];
+  for (const l of [...letters].sort((a, c) => a.b.y + a.b.height / 2 - (c.b.y + c.b.height / 2))) {
+    const cy = l.b.y + l.b.height / 2;
+    const line = lines.find((x) => cy >= x.top && cy <= x.bottom);
+    if (line) {
+      line.letters.push(l);
+      line.top = Math.min(line.top, l.b.y);
+      line.bottom = Math.max(line.bottom, l.b.y + l.b.height);
+    } else lines.push({ top: l.b.y, bottom: l.b.y + l.b.height, letters: [l] });
+  }
+  lines.sort((a, c) => a.top - c.top);
+  return {
+    lines: lines.map((line) => {
+      const row = [...line.letters].sort((a, c) => a.b.x - c.b.x);
+      const heights = row.map((l) => l.b.height).sort((a, c) => a - c);
+      const gap = heights[Math.floor(heights.length / 2)] * 0.35;
+      const words = [];
+      row.forEach((l, i) => {
+        const prev = row[i - 1];
+        if (!prev || l.b.x - (prev.b.x + prev.b.width) > gap) words.push({ letters: [] });
+        words[words.length - 1].letters.push(l.id);
+      });
+      return { words };
+    })
+  };
+}
+function motionTextUnits(layout, by) {
+  if (by === "line") return layout.lines.map((l) => l.words.flatMap((w) => w.letters));
+  if (by === "word") return layout.lines.flatMap((l) => l.words.map((w) => w.letters));
+  return layout.lines.flatMap((l) => l.words.flatMap((w) => w.letters.map((id) => [id])));
+}
+function motionCascade(units, cascade = "forward", seed = 1) {
+  const n = units.length;
+  const mid = (n - 1) / 2;
+  const indexed = units.map((u, i) => ({ u, i }));
+  if (cascade === "backward") return [...units].reverse();
+  if (cascade === "center") return indexed.sort((a, b) => Math.abs(a.i - mid) - Math.abs(b.i - mid) || a.i - b.i).map((x) => x.u);
+  if (cascade === "edges") return indexed.sort((a, b) => Math.abs(b.i - mid) - Math.abs(a.i - mid) || a.i - b.i).map((x) => x.u);
+  if (cascade === "random") {
+    let s = seed >>> 0 || 1;
+    const rand = () => {
+      s = s + 1831565813 >>> 0;
+      let t = s;
+      t = Math.imul(t ^ t >>> 15, t | 1);
+      t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+      return ((t ^ t >>> 14) >>> 0) / 4294967296;
+    };
+    const out = [...units];
+    for (let i = n - 1; i > 0; i--) {
+      const j = Math.floor(rand() * (i + 1));
+      [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out;
+  }
+  return [...units];
+}
+var MOTION_TEXT_STAGGER = { letter: 40, word: 120, line: 300 };
+function motionCommandSlots(nodes, command3) {
+  if (!command3.split) return { slots: command3.targets.map((id, k) => ({ id, slot: k })), stagger: command3.stagger ?? 0 };
+  const slots = [];
+  let slot = 0;
+  for (const target of command3.targets) {
+    const layout = motionTextLayout(nodes, target);
+    if (!layout) {
+      slots.push({ id: target, slot: slot++ });
+      continue;
+    }
+    for (const unit of motionCascade(motionTextUnits(layout, command3.split), command3.cascade, motionSeedFromId(target))) {
+      for (const id of unit) slots.push({ id, slot });
+      slot++;
+    }
+  }
+  return { slots, stagger: command3.stagger ?? MOTION_TEXT_STAGGER[command3.split] };
+}
+
 // src/animation-editor/compile.ts
 var indexCache = /* @__PURE__ */ new WeakMap();
 function indexMotionNodes(nodes) {
@@ -982,10 +1069,11 @@ function compileMotionScene(scene) {
     shot.run.forEach((command3, i) => {
       const base = command3.with === "previous" && i > 0 ? prevStart : runEnd;
       const begin = base + (command3.type === "wait" ? 0 : (command3.delay ?? 0) * f);
-      const targets = command3.type === "wait" ? [] : command3.targets;
-      const durations = command3.type === "wait" ? [command3.duration * f] : targets.map((id) => motionCommandDuration(command3, scene, id) * f);
-      const stagger = command3.type === "wait" ? 0 : (command3.stagger ?? 0) * f;
-      const end2 = durations.reduce((m, d, k) => Math.max(m, begin + k * stagger + d), begin);
+      const split = command3.type === "wait" ? null : motionCommandSlots(nodes, command3);
+      const slots = split?.slots ?? [];
+      const durations = command3.type === "wait" ? [command3.duration * f] : slots.map((s) => motionCommandDuration(command3, scene, s.id) * f);
+      const stagger = (split?.stagger ?? 0) * f;
+      const end2 = durations.reduce((m, d, k) => Math.max(m, begin + (slots[k]?.slot ?? k) * stagger + d), begin);
       commands.push({ shot: shot.id, shotIndex: index, command: i, type: command3.type, start: begin, end: end2, duration: durations[0] ?? 0 });
       prevStart = begin;
       runEnd = Math.max(runEnd, end2);
@@ -1033,14 +1121,15 @@ function compileMotionScene(scene) {
       });
       continue;
     }
-    command3.targets.forEach((target, k) => {
+    const split = motionCommandSlots(nodes, command3);
+    for (const { id: target, slot } of split.slots) {
       const entry = nodes.get(target);
-      if (!entry) return;
+      if (!entry) continue;
       const f = motionShotTimeScale(shot);
-      const start = timing.start + k * (command3.stagger ?? 0) * f;
+      const start = timing.start + slot * split.stagger * f;
       const cycle = motionCycleDuration(command3, scene, target) * f;
       jobs.push({ start, order: order++, run: () => compileRepeated(command3, target, entry, start, cycle, timing) });
-    });
+    }
   }
   jobs.sort((a, b) => a.start - b.start || a.order - b.order).forEach((job) => job.run());
   function compileRepeated(command3, node, entry, start, cycle, timing) {
@@ -1750,6 +1839,11 @@ function checkMotionScene(scene) {
       if (command3.type === "follow" && known(command3.path, "unknown-path", "path", where) && nodes.get(command3.path).node.type !== "path")
         issues.push(motionIssue("not-a-path", `"${command3.path}" is a group; follow a single path node.`, { ...where, ids: [command3.path] }));
       if (command3.type === "morph") known(command3.into, "unknown-shape", "shape", where);
+      if (command3.type !== "play" && command3.split) {
+        for (const id of targets)
+          if (!motionTextLayout(nodes, id))
+            issues.push(motionIssue("split-not-text", `"${id}" is not a group of letter paths, so "split": "${command3.split}" animates it as a whole; convert the text to outlines and group the letters (get_text_layout shows how they read).`, { ...where, ids: [id] }));
+      }
       if (command3.type === "play" && !scene.clips?.[command3.clip])
         issues.push(motionIssue("unknown-clip", `There is no clip ${namedWithSuggestion(command3.clip, Object.keys(scene.clips ?? {}))}; define it with set_animation_clip.`, where));
       if (command3.type === "match" && known(command3.into, "unknown-shape", "group", where)) {
@@ -3730,6 +3824,8 @@ var BASE = {
   with: { type: "string", enum: ["after", "previous"], description: '"after" (default) starts when the commands before it finish; "previous" starts together with the command before.' },
   ease: EASE,
   note: { type: "string", description: "Why this command is here, in a few words." },
+  split: { type: "string", enum: ["letter", "word", "line"], description: "For outlined text (a group of letter paths): animate it a letter, word or line at a time in reading order, staggered (default 40 ms a letter, 120 a word, 300 a line). get_text_layout shows the units." },
+  cascade: { type: "string", enum: ["forward", "backward", "center", "edges", "random"], description: "With split: the order units go in (default forward; random is the same every time)." },
   repeat: { type: "integer", minimum: 1, maximum: 1e3, description: 'Play it this many times (default 1); "duration" is one cycle. Not for enter or exit.' },
   repeatMode: { type: "string", enum: [...MOTION_REPEAT_MODES], description: "loop (default) restarts each cycle, mirror plays every other one backwards, offset carries on from where the last ended (rotate by 90 with repeat 4 makes a full turn)." },
   steps: { type: "number", exclusiveMinimum: 0, maximum: 120, description: `Stepped time: hold on a grid of this many frames per second (12 = "on twos"). Default: the scene's steps, else smooth.` }
@@ -4145,6 +4241,21 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       };
     }
   };
+  const getTextLayout = {
+    name: "get_text_layout",
+    title: "Read outlined text as letters, words and lines",
+    description: 'Returns how a group of letter paths (text converted to outlines) reads: its lines, each a list of words, each a list of letter ids, in reading order \u2014 the units a command with "split": "letter" | "word" | "line" animates. Errors if the element is not a group with paths.',
+    inputSchema: object({ group: { type: "string", minLength: 1, description: "Element id of the group of letters." } }, ["group"]),
+    annotations: { title: "Read outlined text as letters, words and lines", ...READ },
+    handler: ({ group }) => {
+      const s = scene();
+      const nodes = indexMotionNodes(s.artwork.nodes);
+      if (!nodes.has(group)) throw new Error(`There is no element ${namedWithSuggestion(group, [...nodes.keys()])}.`);
+      const layout = motionTextLayout(nodes, group);
+      if (!layout) throw new Error(`"${group}" is not a group of paths; convert the text to outlines (one path a letter) and group it.`);
+      return { group, letters: layout.lines.reduce((n, l) => n + l.words.reduce((m, w) => m + w.letters.length, 0), 0), ...layout };
+    }
+  };
   const getMotionPath = {
     name: "get_motion_path",
     title: "Read where a node travels",
@@ -4562,7 +4673,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getAnimation, getShot, findElements, getMotionPath, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation];
+  const reads = [getAnimation, getShot, findElements, getTextLayout, getMotionPath, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, exportLottie, seekAnimation];
   const writes = [setArtworkSvg, importPptx, setDrivers, setClip, copyAnimation, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, moveCommand, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
   return {
     id: options.id ?? "animation",
@@ -4595,6 +4706,7 @@ Commands
 - enter (fade, pop, grow, slide, draw) and exit (fade, shrink, slide, undraw) bring things in and out.
 - 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.
+- Text: convert it to outlines (a group with a path per letter) and give a command "split": "letter", "word" or "line" (and "cascade") to animate it a unit at a time; get_text_layout shows the units.
 - Drawing a group of strokes: "order": "sequence" draws them one after another (a signature, a diagram), "sortBy": "distance" from "origin" reveals outward, "pace": "speed" keeps one speed; draw with "comet": 0.2 sends a short stroke along a path and off the end.
 - Fast motion reads better with blur: set_animation_settings { "motionBlur": { "shutter": 180 } } (stage and rendered frames only).
 - Tie properties together with set_animation_drivers: parallax layers, a wheel that turns as it rolls, a shadow that fades as something rises. Drivers add to the target's own commands.
@@ -4927,6 +5039,7 @@ export {
   MOTION_ADDITIVE_PROPERTIES,
   MOTION_BLENDS,
   MOTION_CAMERA_MS,
+  MOTION_CASCADES,
   MOTION_CLIP_TARGET,
   MOTION_COMMAND_SCHEMA,
   MOTION_COMMAND_TYPES,
@@ -4949,6 +5062,8 @@ export {
   MOTION_REPEAT_MODES,
   MOTION_SPEED_RANGE,
   MOTION_SPLIT_ORIENTATIONS,
+  MOTION_TEXT_STAGGER,
+  MOTION_TEXT_UNITS,
   MOTION_TRIGGERS,
   MotionSceneFormatError,
   activeSegment,
@@ -4988,12 +5103,14 @@ export {
   motionBeatAt,
   motionBeatTime,
   motionBlurTimes,
+  motionCascade,
   motionClipAttrs,
   motionClipLayout,
   motionCommandDuration,
   motionCommandFields,
   motionCommandRepeat,
   motionCommandRows,
+  motionCommandSlots,
   motionCommandSummary,
   motionContactSheetSvg,
   motionCueChoices,
@@ -5035,6 +5152,8 @@ export {
   motionShotCueTime,
   motionShotTimeScale,
   motionStageSvg,
+  motionTextLayout,
+  motionTextUnits,
   motionTrackKey,
   namedWithSuggestion,
   parseMotionDrivers,