pixi-effects 0.8.0 → 0.10.0

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkPDBDDGG5_cjs = require('./chunk-PDBDDGG5.cjs');
-var chunkAGMNSJJH_cjs = require('./chunk-AGMNSJJH.cjs');
+var chunk4WJUSDJJ_cjs = require('./chunk-4WJUSDJJ.cjs');
+var chunkS3ZI4MKS_cjs = require('./chunk-S3ZI4MKS.cjs');
 var chunkUQBGW5DO_cjs = require('./chunk-UQBGW5DO.cjs');
 var PIXI = require('pixi.js');
 var gsap = require('gsap');
@@ -843,16 +843,16 @@ function expandTransitions(spec) {
     if (toUses > 1) {
       throw new Error(`pixi-effects: ${tag} sequence "${t.to}" is used as \`to\` in more than one transition`);
     }
-    const tStart = chunkAGMNSJJH_cjs.resolveAt(t.at, parentDuration);
+    const tStart = chunkS3ZI4MKS_cjs.resolveAt(t.at, parentDuration);
     const tEnd = tStart + t.duration;
     const fromSeq = fromEntry.seq;
-    const fromStart = chunkAGMNSJJH_cjs.resolveAt(fromSeq.at, parentDuration);
+    const fromStart = chunkS3ZI4MKS_cjs.resolveAt(fromSeq.at, parentDuration);
     const fromEnd = fromStart + (fromSeq.duration ?? parentDuration);
     if (tStart < fromStart || tEnd > fromEnd) {
       throw new Error(`pixi-effects: ${tag} window [${tStart}, ${tEnd}] is not covered by \`from\` "${t.from}" (lives [${fromStart}, ${fromEnd}], so it ends at ${fromEnd})`);
     }
     const toSeq = toEntry.seq;
-    const toStart = chunkAGMNSJJH_cjs.resolveAt(toSeq.at, parentDuration);
+    const toStart = chunkS3ZI4MKS_cjs.resolveAt(toSeq.at, parentDuration);
     const toEnd = toStart + (toSeq.duration ?? parentDuration);
     if (tStart < toStart || tEnd > toEnd) {
       throw new Error(`pixi-effects: ${tag} window [${tStart}, ${tEnd}] is not covered by \`to\` "${t.to}" (lives [${toStart}, ${toEnd}], so it starts at ${toStart})`);
@@ -1173,12 +1173,12 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
         blending.add(w.to);
       }
     }
-    comp.layers().forEach(({ seq, display, threeD }, i) => {
+    comp.layers().forEach(({ seq, display, threeD, carriers }, i) => {
       const t = seq.target;
       const name = seq.spec.name;
       const label = name ?? `${seq.spec.type}#${i}`;
-      const alpha = t?.alpha ?? 1;
-      const alive = threeD ? display.visible : t?.renderable ?? true;
+      const alpha = (t?.alpha ?? 1) * carriers.reduce((a, c) => a * (c.target?.alpha ?? 1), 1);
+      const alive = (threeD ? display.visible : t?.renderable ?? true) && carriers.every((c) => c.target?.renderable ?? true);
       const visible = parentVisible && alive && alpha > 0;
       let bounds = null;
       if (!insideThreeD) {
@@ -1192,10 +1192,17 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
         onCanvas = inter === 0 && area > 0 ? "none" : inter >= area - 1e-6 ? "full" : "partial";
         if (area === 0) onCanvas = "none";
       }
-      const keys = chunkAGMNSJJH_cjs.collectPropKeys(seq.spec);
-      const moving = parentMoving || (seq.spec.keyframes ?? []).length > 0 && (keys.has("x") || keys.has("y"));
-      const scale = t?.scale;
-      const zero = parentZero || !!scale && (scale.x === 0 || scale.y === 0);
+      const keys = chunkS3ZI4MKS_cjs.collectPropKeys(seq.spec);
+      const carried = carriers.some((c) => {
+        const k = chunkS3ZI4MKS_cjs.collectPropKeys(c.spec);
+        return (c.spec.keyframes ?? []).length > 0 && (k.has("x") || k.has("y") || k.has("rotation") || k.has("scale"));
+      });
+      const moving = parentMoving || carried || (seq.spec.keyframes ?? []).length > 0 && (keys.has("x") || keys.has("y"));
+      const zeroScale = (o) => {
+        const s = o?.scale;
+        return !!s && (s.x === 0 || s.y === 0);
+      };
+      const zero = parentZero || zeroScale(t) || carriers.some((c) => zeroScale(c.target));
       const info = { path: prefix + label, name, type: seq.spec.type, threeD, visible, alpha, moving, bounds, onCanvas };
       layers.push(info);
       let shown = bounds ? clip(bounds, view) : null;
@@ -1208,7 +1215,7 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
       const group = parentScene ?? (name !== void 0 && blending.has(name) ? name : void 0);
       if (group) scene.set(info, group);
       if (zero || seq.showsNothingYet) scaledToNothing.add(info);
-      if (seq instanceof chunkPDBDDGG5_cjs.CompositionSequence) walk2(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
+      if (seq instanceof chunk4WJUSDJJ_cjs.CompositionSequence) walk2(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
     });
   };
   walk2(root, "", false, true);
@@ -1268,10 +1275,10 @@ function walk(comp, parentStart, parentEnd, depth, prefix, rows, transitions) {
     const start = parentStart + (seq.at ?? 0);
     const end = Math.min(parentEnd, seq.duration !== void 0 ? start + seq.duration : parentEnd);
     const span = end - start;
-    const keys = (seq.spec.keyframes ?? []).map((kf) => round(start + chunkAGMNSJJH_cjs.resolveAt(kf.at, span))).sort((a, b) => a - b).slice(0, MAX_KEYS);
+    const keys = (seq.spec.keyframes ?? []).map((kf) => round(start + chunkS3ZI4MKS_cjs.resolveAt(kf.at, span))).sort((a, b) => a - b).slice(0, MAX_KEYS);
     const row = { path: prefix + name, name, type: seq.spec.type, depth, start: round(start), end: round(end), keys, detail: detailOf(seq) };
     const inner = [];
-    const isComp = seq instanceof chunkPDBDDGG5_cjs.CompositionSequence;
+    const isComp = seq instanceof chunk4WJUSDJJ_cjs.CompositionSequence;
     if (isComp) walk(seq, start, end, depth + 1, prefix + name + "/", inner, transitions);
     entries.push({ row, inner, groupable: !isComp });
   });
@@ -1328,7 +1335,8 @@ var COLORS = {
   audio: "#ff7aa8",
   composition: "#8ea4c8",
   three: "#ff9f68",
-  camera: "#b0b0b0"
+  camera: "#b0b0b0",
+  null: "#b0b0b0"
 };
 var esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 var num = (n) => String(Math.round(n * 100) / 100);
@@ -1449,6 +1457,21 @@ function startWhenRunning(ctx, start, gesture) {
 }
 var GESTURES = ["pointerdown", "mousedown", "touchend", "keydown"];
 
+// src/core/poster.ts
+function normalizePoster(poster, duration, frameRate) {
+  if (poster === void 0 || poster === null) return { seconds: null, frame: null };
+  if (typeof poster !== "number" || !Number.isFinite(poster)) {
+    console.warn(`pixi-effects: movie.init({ poster }): ${JSON.stringify(poster)} is not a time in seconds; ignored`);
+    return { seconds: null, frame: null };
+  }
+  let seconds = poster < 0 ? Math.max(0, duration + poster) : poster;
+  if (seconds > duration) {
+    console.warn(`pixi-effects: movie.init({ poster }): the poster time ${poster} s is past the end of the movie (${duration} s); using the last frame`);
+    seconds = duration;
+  }
+  return { seconds, frame: Math.round(seconds * frameRate) };
+}
+
 // src/core/Movie.ts
 PIXI.extensions.add(PIXI.CullerPlugin);
 gsap.gsap.registerPlugin(PixiPlugin.PixiPlugin);
@@ -1462,6 +1485,11 @@ var Movie = class {
   audioSource = null;
   gainNode = null;
   _cancelAudioStart = null;
+  /** The poster time in seconds (`movie.init({ poster })`), or null. */
+  poster = null;
+  _posterFrame = null;
+  /** The canvas shows the poster picture while the playhead is still at frame 0 (like `<video poster>`): the first seek or play replaces it. */
+  _atPoster = false;
   /** > 0 while the movie moves its own playhead (playback, render, snapshot, contactSheet): those are not the seeks `seeking` / `seeked` report. */
   _quiet = 0;
   _volume = 1;
@@ -1505,6 +1533,36 @@ var Movie = class {
   get isReady() {
     return this._initState === "ready";
   }
+  /** The poster time as a frame number, or null. */
+  get posterFrame() {
+    return this._posterFrame;
+  }
+  /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */
+  async _showPoster() {
+    if (this._posterFrame === null || !this.timeline) return;
+    const back = this.currentFrame;
+    this.currentFrame = this._posterFrame;
+    try {
+      this.timeline.time(this._posterFrame / this.frameRate);
+      await this._awaitVideoFrames();
+      this._updateSpace();
+      this._renderNow();
+    } finally {
+      this.currentFrame = back;
+    }
+    this._atPoster = true;
+  }
+  async posterImage(opts = {}) {
+    this._requireReady("posterImage");
+    const back = this.currentFrame, wasAtPoster = this._atPoster;
+    try {
+      return await this.snapshot(this._posterFrame ?? 0, opts);
+    } finally {
+      this.currentFrame = back;
+      if (wasAtPoster) await this._showPoster();
+      else await this._quietly(() => this.gotoFrame(back, true));
+    }
+  }
   _ensureAudioContext() {
     if (!this._audioContext) {
       const Ctx = window.AudioContext ?? window.webkitAudioContext;
@@ -1513,7 +1571,7 @@ var Movie = class {
     return this._audioContext;
   }
   async init(options = {}) {
-    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition"]);
+    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster"]);
     this._initState = "pending";
     try {
       this.width = options.width ?? 1920;
@@ -1521,6 +1579,9 @@ var Movie = class {
       this.duration = options.duration ?? 10;
       this.frameRate = options.frameRate ?? 30;
       this.totalFrames = Math.round(this.duration * this.frameRate);
+      const poster = normalizePoster(options.poster, this.duration, this.frameRate);
+      this.poster = poster.seconds;
+      this._posterFrame = poster.frame;
       this.background = options.background ?? "#000000";
       this.timeline = gsap.gsap.timeline({ paused: true, defaults: { ease: "none" } });
       this.timeline.add(gsap.gsap.to({}, { duration: this.duration }));
@@ -1557,7 +1618,7 @@ var Movie = class {
         height: options.composition.height ?? this.height,
         duration: options.composition.duration ?? this.duration
       } : void 0;
-      await chunkAGMNSJJH_cjs.ensureFilterLibrary(seededComposition);
+      await chunkS3ZI4MKS_cjs.ensureFilterLibrary(seededComposition);
       const userComposition = seededComposition ? expandTransitions(seededComposition) : void 0;
       const rootSeqSpec = {
         type: "composition",
@@ -1567,7 +1628,7 @@ var Movie = class {
         ...userComposition
       };
       if (userComposition) carryTransitionWindows(userComposition, rootSeqSpec);
-      const composition = new chunkPDBDDGG5_cjs.CompositionSequence(rootSeqSpec, null, rootShape);
+      const composition = new chunk4WJUSDJJ_cjs.CompositionSequence(rootSeqSpec, null, rootShape);
       await composition.build();
       this._rootSequence = composition;
       if (composition.target) root.addChild(composition.target);
@@ -1584,6 +1645,7 @@ var Movie = class {
       this._updateSpace();
       this._renderNow();
       this._initState = "ready";
+      if (this._posterFrame !== null) await this._showPoster();
       this.emit("ready");
     } catch (err) {
       try {
@@ -1597,7 +1659,7 @@ var Movie = class {
   }
   async gotoFrame(frame, force = false) {
     if (this._initState !== "ready") return;
-    if (!force && this.currentFrame === frame) return;
+    if (!force && !this._atPoster && this.currentFrame === frame) return;
     if (this._quiet > 0) return this._goto(frame);
     const target = Math.max(0, Math.min(frame, this.totalFrames));
     this.emit("seeking", { frame: target, totalFrames: this.totalFrames });
@@ -1617,6 +1679,7 @@ var Movie = class {
     this.emit("error", { where, message: error instanceof Error ? error.message : String(error), error });
   }
   async _goto(frame) {
+    this._atPoster = false;
     this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
     this.timeline.time(this.currentFrame / this.frameRate);
     await this._awaitVideoFrames();
@@ -1658,7 +1721,7 @@ var Movie = class {
     const g = sheet.getContext("2d");
     g.fillStyle = "#10131c";
     g.fillRect(0, 0, L.width, L.height);
-    const back = this.currentFrame;
+    const back = this.currentFrame, wasAtPoster = this._atPoster;
     try {
       for (let i = 0; i < frames.length; i++) {
         const f = frames[i];
@@ -1671,7 +1734,8 @@ var Movie = class {
         g.fillText(`frame ${f}  \xB7  ${(f / this.frameRate).toFixed(2)}s`, x + 8, y + LABEL_H / 2);
       }
     } finally {
-      await this._quietly(() => this.gotoFrame(back, true));
+      if (wasAtPoster) await this._showPoster();
+      else await this._quietly(() => this.gotoFrame(back, true));
     }
     return encodeCanvas(sheet, "image/png", opts.as ?? "blob");
   }
@@ -2063,17 +2127,17 @@ function orbit(opts) {
     throw new Error("pixi-effects: orbit() cannot combine `radius` with `dollyZoom` \u2014 the radius follows the animated fov");
   }
   const [cx, cy] = opts.center ?? [width / 2, height / 2];
-  const fixedR = opts.radius ?? chunkAGMNSJJH_cjs.homeDistance(height, fov ?? chunkAGMNSJJH_cjs.DEFAULT_FOV);
+  const fixedR = opts.radius ?? chunkS3ZI4MKS_cjs.homeDistance(height, fov ?? chunkS3ZI4MKS_cjs.DEFAULT_FOV);
   const start = opts.start ?? -degrees / 2;
   const steps = Math.max(1, Math.round(duration * stepsPerSecond));
   const easeFn = parseEase(ease);
   const dollyEase = dolly ? parseEase(dolly.ease ?? ease) : null;
   const pos = (i) => {
     const p = i / steps;
-    const a = (start + degrees * easeFn(p)) * chunkAGMNSJJH_cjs.DEG;
+    const a = (start + degrees * easeFn(p)) * chunkS3ZI4MKS_cjs.DEG;
     if (!dolly) return { x: cx + fixedR * Math.sin(a), z: fixedR * Math.cos(a) };
     const f = dolly.from + (dolly.to - dolly.from) * dollyEase(p);
-    const R = chunkAGMNSJJH_cjs.homeDistance(height, f);
+    const R = chunkS3ZI4MKS_cjs.homeDistance(height, f);
     return { x: cx + R * Math.sin(a), z: R * Math.cos(a), fov: f };
   };
   const keyframes = [];
@@ -2100,6 +2164,269 @@ function orbit(opts) {
   return spec;
 }
 
+// src/presets/followPath.ts
+var KEYS = ["d", "at", "duration", "ease", "from", "to", "orient", "rotate", "frameRate"];
+var MAX_STEPS = 2e3;
+function followPath(opts) {
+  chunkUQBGW5DO_cjs.warnUnknownOptions("followPath()", opts, KEYS);
+  const { d, at = 0, duration, ease = "none", from = 0, to = 1, orient = false, rotate = 0, frameRate = 30 } = opts;
+  if (typeof d !== "string" || d.trim() === "") throw new Error('followPath(): d must be SVG path data, e.g. "M 100 600 C 300 100 900 100 1180 600"');
+  if (!(Number.isFinite(duration) && duration > 0)) throw new Error(`followPath(): duration must be a positive number of seconds, got ${duration}`);
+  if (!(Number.isFinite(frameRate) && frameRate > 0)) throw new Error(`followPath(): frameRate must be a positive number (samples per second), got ${frameRate}`);
+  for (const [n, v] of [["from", from], ["to", to]]) {
+    if (!(Number.isFinite(v) && v >= 0 && v <= 1)) throw new Error(`followPath(): ${n} must be a fraction of the path between 0 and 1, got ${v}`);
+  }
+  const steps = Math.max(1, Math.round(duration * frameRate));
+  if (steps > MAX_STEPS) throw new Error(`followPath(): ${steps} samples is too many (max ${MAX_STEPS}); lower frameRate or duration`);
+  const segments = [];
+  let total = 0;
+  for (const line of chunkS3ZI4MKS_cjs.flattenSvgPath(d)) {
+    const p = line.closed ? [...line.pts, line.pts[0], line.pts[1]] : line.pts;
+    for (let i = 2; i < p.length; i += 2) {
+      const len = Math.hypot(p[i] - p[i - 2], p[i + 1] - p[i - 1]);
+      if (len === 0) continue;
+      segments.push({ x0: p[i - 2], y0: p[i - 1], x1: p[i], y1: p[i + 1], start: total, len });
+      total += len;
+    }
+  }
+  if (!(total > 0)) throw new Error(`followPath(): the path "${d}" has no length (it needs at least two different points)`);
+  const find = (s) => {
+    let lo = 0, hi = segments.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi >> 1;
+      if (segments[mid].start + segments[mid].len < s) lo = mid + 1;
+      else hi = mid;
+    }
+    return segments[lo];
+  };
+  const at_ = (fraction) => {
+    const s = Math.min(Math.max(fraction, 0), 1) * total;
+    const g = find(s);
+    const t = Math.min(Math.max((s - g.start) / g.len, 0), 1);
+    return { x: g.x0 + (g.x1 - g.x0) * t, y: g.y0 + (g.y1 - g.y0) * t, heading: Math.atan2(g.y1 - g.y0, g.x1 - g.x0) * 180 / Math.PI };
+  };
+  const shape = parseEase(ease);
+  const round2 = (v) => Math.round(v * 1e6) / 1e6;
+  let turn = 0;
+  const sample = (k) => {
+    const p = from + (to - from) * shape(k / steps);
+    const pt = at_(p);
+    const out2 = { x: round2(pt.x), y: round2(pt.y) };
+    if (orient) {
+      let h = pt.heading + rotate;
+      if (k === 0) turn = h;
+      else {
+        let delta = h - turn;
+        delta -= 360 * Math.round(delta / 360);
+        turn += delta;
+      }
+      out2.rotation = round2(turn);
+    }
+    return out2;
+  };
+  const out = [{ at, set: sample(0) }];
+  const step = duration / steps;
+  for (let k = 1; k <= steps; k++) out.push({ at: round2(at + (k - 1) * step), to: sample(k), duration: round2(step), ease: "none" });
+  return out;
+}
+
+// src/presets/stagger.ts
+var STAGGER_KEYS = ["each", "amount", "from", "grid", "ease", "seed"];
+var FROM_NAMES = ["start", "end", "center", "edges", "random"];
+function stagger(items, options = {}) {
+  const isCount = typeof items === "number";
+  const n = isCount ? items : items.length;
+  if (!Number.isInteger(n) || n < 0) throw new Error(`stagger(): count must be a whole number of items, got ${n}`);
+  chunkUQBGW5DO_cjs.warnUnknownOptions("stagger()", options, STAGGER_KEYS);
+  const { each, amount, from = "start", grid, ease = "none", seed = 0 } = options;
+  if (each !== void 0 && amount !== void 0) throw new Error("stagger(): give `each` (seconds between neighbours) or `amount` (seconds in total), not both");
+  if (each !== void 0 && !(Number.isFinite(each) && each >= 0)) throw new Error(`stagger(): each must be a number of seconds >= 0, got ${each}`);
+  if (amount !== void 0 && !(Number.isFinite(amount) && amount >= 0)) throw new Error(`stagger(): amount must be a number of seconds >= 0, got ${amount}`);
+  if (typeof from === "string" && !FROM_NAMES.includes(from)) {
+    throw new Error(`stagger(): from "${from}" is not one of ${FROM_NAMES.map((f) => `"${f}"`).join(", ")} or an item index`);
+  }
+  if (typeof from === "number" && !(Number.isInteger(from) && from >= 0 && from < Math.max(n, 1))) throw new Error(`stagger(): from ${from} is not an index of the ${n} items`);
+  if (grid && !(Array.isArray(grid) && grid.length === 2 && grid.every((g) => Number.isInteger(g) && g > 0) && grid[0] * grid[1] >= n)) {
+    throw new Error(`stagger(): grid must be [columns, rows] and hold all ${n} items, got ${JSON.stringify(grid)}`);
+  }
+  const dist = distances(n, from, grid, seed);
+  const max = dist.reduce((m, d) => Math.max(m, d), 0);
+  const total = amount !== void 0 ? amount : (each ?? 0.1) * max;
+  const shape = parseEase(ease);
+  const delays = dist.map((d) => max === 0 ? 0 : Math.round(total * shape(d / max) * 1e6) / 1e6);
+  if (isCount) return delays;
+  return items.map((layer, i) => ({ ...layer, at: Math.round(((layer.at ?? 0) + delays[i]) * 1e6) / 1e6 }));
+}
+function distances(n, from, grid, seed) {
+  if (n === 0) return [];
+  if (from === "random") {
+    const order = Array.from({ length: n }, (_, i) => i);
+    const r = chunkS3ZI4MKS_cjs.random(seed);
+    for (let i = n - 1; i > 0; i--) {
+      const j = Math.floor(r() * (i + 1));
+      [order[i], order[j]] = [order[j], order[i]];
+    }
+    return order;
+  }
+  if (!grid) {
+    const mid = (n - 1) / 2;
+    return Array.from({ length: n }, (_, i) => {
+      switch (from) {
+        case "start":
+          return i;
+        case "end":
+          return n - 1 - i;
+        case "center":
+          return Math.abs(i - mid);
+        case "edges":
+          return mid - Math.abs(i - mid);
+        default:
+          return Math.abs(i - from);
+      }
+    });
+  }
+  const [cols, rows] = grid;
+  const at = (i) => ({ x: i % cols, y: Math.floor(i / cols) });
+  const origin = from === "start" ? { x: 0, y: 0 } : from === "end" ? { x: cols - 1, y: rows - 1 } : from === "center" || from === "edges" ? { x: (cols - 1) / 2, y: (rows - 1) / 2 } : at(from);
+  const d = Array.from({ length: n }, (_, i) => Math.hypot(at(i).x - origin.x, at(i).y - origin.y));
+  if (from !== "edges") return d;
+  const far = Math.max(...d);
+  return d.map((v) => far - v);
+}
+
+// src/presets/wiggle.ts
+var WIGGLE_KEYS = ["at", "duration", "freq", "seed", "ease", "props"];
+var MAX_STEPS2 = 2e3;
+function wiggle(opts) {
+  chunkUQBGW5DO_cjs.warnUnknownOptions("wiggle()", opts, WIGGLE_KEYS);
+  const { at = 0, duration, freq = 3, seed = 0, ease = "sine.inOut", props } = opts;
+  if (!(Number.isFinite(duration) && duration > 0)) throw new Error(`wiggle(): duration must be a positive number of seconds, got ${duration}`);
+  if (!(Number.isFinite(freq) && freq > 0)) throw new Error(`wiggle(): freq must be a positive number (steps per second), got ${freq}`);
+  const names = Object.keys(props ?? {});
+  if (names.length === 0) throw new Error("wiggle(): props is empty; name at least one property, e.g. props: { x: { around: 100, amp: 8 } }");
+  for (const n of names) {
+    const p = props[n];
+    if (!Number.isFinite(p.amp)) throw new Error(`wiggle(): props.${n}.amp must be a number, got ${p.amp}`);
+    if (p.around === void 0 || p.around === null || p.around === "") throw new Error(`wiggle(): props.${n}.around is missing`);
+  }
+  const steps = Math.ceil(duration * freq - 1e-9);
+  if (steps > MAX_STEPS2) throw new Error(`wiggle(): ${steps} steps is too many (max ${MAX_STEPS2}); lower freq or duration`);
+  const set = {};
+  for (const n of names) set[n] = props[n].around;
+  const out = [{ at, set }];
+  const stepLen = duration / steps;
+  for (let s = 0; s < steps; s++) {
+    const to = {};
+    names.forEach((n, pi) => {
+      const p = props[n];
+      if (s === steps - 1) {
+        to[n] = p.around;
+        return;
+      }
+      const off = (chunkS3ZI4MKS_cjs.rand(seed * 7919 + pi * 104729 + s * 31 + 1) * 2 - 1) * p.amp;
+      to[n] = typeof p.around === "number" ? p.around + off : `(${p.around}) ${off < 0 ? "-" : "+"} ${Math.abs(off)}`;
+    });
+    out.push({ at: at + s * stepLen, to, duration: stepLen, ease });
+  }
+  return out;
+}
+
+// src/presets/animateText.ts
+var KEYS2 = ["by", "x", "y", "align", "name", "at", "duration", "in", "out", "stagger", "idle", "styleFor"];
+var PRESETS = {
+  rise: { from: { y: 40, alpha: 0 }, duration: 0.5, ease: "back.out(2)" },
+  drop: { from: { y: -50, alpha: 0 }, duration: 0.7, ease: "bounce.out" },
+  fade: { from: { alpha: 0 }, duration: 0.5, ease: "power1.out" },
+  pop: { from: { scale: 0, alpha: 0 }, duration: 0.45, ease: "back.out(2.4)" },
+  zoom: { from: { scale: 2.5, alpha: 0 }, duration: 0.6, ease: "power3.out" },
+  slide: { from: { x: -60, alpha: 0 }, duration: 0.5, ease: "power3.out" },
+  spin: { from: { rotation: -90, scale: 0, alpha: 0 }, duration: 0.6, ease: "back.out(1.7)" }
+};
+var PRESET_NAMES = Object.keys(PRESETS);
+function animateText(text, style, options) {
+  chunkUQBGW5DO_cjs.warnUnknownOptions("animateText()", options, KEYS2);
+  const { by = "chars", x = 0, y = 0, align = "left", name = "text", at = 0, duration, idle, styleFor } = options;
+  if (!(Number.isFinite(duration) && duration > 0)) throw new Error(`animateText(): duration must be a positive number of seconds (how long until the last piece is gone), got ${duration}`);
+  const pieces = splitText(text, style, { by, x, y, align });
+  if (pieces.length === 0) return [];
+  const lineHeight = measureText("M", style).height;
+  const inTween = options.in === false ? null : resolveTween(options.in ?? "rise", "in");
+  const outTween = options.out === void 0 || options.out === false ? null : resolveTween(options.out, "out");
+  const delays = stagger(pieces.length, options.stagger ?? { each: 0.04 });
+  const wave = Math.max(...delays);
+  const need = (inTween?.duration ?? 0) + (outTween?.duration ?? 0) + wave;
+  if (duration < need - 1e-9) {
+    throw new Error(`animateText(): duration ${duration} is too short for this wave: the entrance${outTween ? ", the exit" : ""} and the stagger need at least ${+need.toFixed(3)} s`);
+  }
+  const end = at + duration;
+  return pieces.map((p, i) => {
+    const cx = p.x + p.width / 2, cy = p.y + lineHeight / 2;
+    const rest = { x: cx, y: cy, alpha: 1, scale: 1, scaleX: 1, scaleY: 1, rotation: 0 };
+    const start = at + delays[i];
+    const len = end - start;
+    const keyframes = [];
+    const place = (key, v) => key === "x" || key === "y" ? rest[key] + v : v;
+    if (inTween) {
+      keyframes.push({
+        at: 0,
+        duration: inTween.duration,
+        ease: inTween.ease,
+        from: Object.fromEntries(Object.entries(inTween.from).map(([k, v]) => [k, place(k, v)])),
+        to: Object.fromEntries(Object.keys(inTween.from).map((k) => [k, inTween.to[k] ?? rest[k]]))
+      });
+    }
+    let idleEnd = len;
+    if (outTween) {
+      const begin = outTween.duration + (wave - delays[i]);
+      idleEnd = len - begin;
+      keyframes.push({
+        at: -begin,
+        duration: outTween.duration,
+        ease: outTween.ease,
+        from: Object.fromEntries(Object.keys(outTween.from).map((k) => [k, outTween.to[k] ?? rest[k]])),
+        to: Object.fromEntries(Object.entries(outTween.from).map(([k, v]) => [k, place(k, v)]))
+      });
+    }
+    if (idle) {
+      const props = {};
+      for (const k of ["x", "y", "rotation", "scale"]) if (idle[k] !== void 0) props[k] = { around: rest[k], amp: idle[k] };
+      const freq = idle.freq ?? 1;
+      const from = inTween?.duration ?? 0;
+      if (Object.keys(props).length > 0 && idleEnd - from >= 1 / freq) {
+        keyframes.push(...wiggle({ at: from, duration: idleEnd - from, freq, seed: (idle.seed ?? 0) * 1e3 + i, props }));
+      }
+    }
+    return {
+      type: "text",
+      name: `${name}-${i}`,
+      text: p.text,
+      style: styleFor ? { ...style, ...styleFor(p) } : style,
+      at: start,
+      duration: len,
+      initial: { x: cx, y: cy, anchorX: 0.5, anchorY: 0.5 },
+      keyframes
+    };
+  });
+}
+function resolveTween(spec, which) {
+  const t = typeof spec === "string" ? { preset: spec } : spec;
+  if (t.preset !== void 0 && !(t.preset in PRESETS)) {
+    const guess = chunkUQBGW5DO_cjs.suggestName(String(t.preset), PRESET_NAMES);
+    throw new Error(`animateText(): ${which} "${t.preset}" is not a preset${guess ? `; did you mean "${guess}"?` : ""} (presets: ${PRESET_NAMES.map((n) => `"${n}"`).join(", ")})`);
+  }
+  const base = t.preset ? PRESETS[t.preset] : void 0;
+  const from = { ...base?.from ?? {}, ...t.from ?? {} };
+  const to = t.to ?? {};
+  const known = /* @__PURE__ */ new Set(["x", "y", "alpha", "scale", "scaleX", "scaleY", "rotation"]);
+  for (const k of Object.keys(from)) {
+    if (!known.has(k) && to[k] === void 0) throw new Error(`animateText(): ${which}.from has "${k}", which has no resting value; give ${which}.to: { ${k}: \u2026 }`);
+  }
+  if (Object.keys(from).length === 0) throw new Error(`animateText(): ${which} needs a preset or a from`);
+  let ease = t.ease ?? base?.ease ?? "power2.out";
+  if (which === "out" && t.ease === void 0) ease = ease.replace(".out", ".in");
+  return { from, to: { ...to }, duration: t.duration ?? base?.duration ?? 0.5, ease };
+}
+
 // src/transforms/withFade.ts
 function withFade(spec, opts) {
   chunkUQBGW5DO_cjs.warnUnknownOptions("withFade()", opts, ["in", "out"]);
@@ -2120,15 +2447,31 @@ function withFade(spec, opts) {
   return spec;
 }
 
+Object.defineProperty(exports, "noise", {
+  enumerable: true,
+  get: function () { return chunkS3ZI4MKS_cjs.noise; }
+});
+Object.defineProperty(exports, "rand", {
+  enumerable: true,
+  get: function () { return chunkS3ZI4MKS_cjs.rand; }
+});
+Object.defineProperty(exports, "random", {
+  enumerable: true,
+  get: function () { return chunkS3ZI4MKS_cjs.random; }
+});
 Object.defineProperty(exports, "registerSequenceType", {
   enumerable: true,
-  get: function () { return chunkAGMNSJJH_cjs.registerSequenceType; }
+  get: function () { return chunkS3ZI4MKS_cjs.registerSequenceType; }
 });
 exports.Movie = Movie;
+exports.animateText = animateText;
+exports.followPath = followPath;
 exports.kenBurns = kenBurns;
 exports.measureText = measureText;
 exports.orbit = orbit;
 exports.splitText = splitText;
+exports.stagger = stagger;
+exports.wiggle = wiggle;
 exports.withFade = withFade;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map