pixi-effects 0.9.0 → 0.11.0

package/dist/index.js

@@ -1,6 +1,6 @@
-import { CompositionSequence } from './chunk-O4AJYUPK.js';
-import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, DEG, resolveAt, collectPropKeys } from './chunk-FNKSXBKB.js';
-export { registerSequenceType } from './chunk-FNKSXBKB.js';
+import { CompositionSequence } from './chunk-3IPDNC3E.js';
+import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, random, noise, flattenSvgPath, rand, DEG, resolveAt, collectPropKeys } from './chunk-C6QHKYC5.js';
+export { noise, rand, random, registerSequenceType } from './chunk-C6QHKYC5.js';
 import { warnUnknownOptions, suggestName } from './chunk-DKGG7WD4.js';
 import * as PIXI from 'pixi.js';
 import { extensions, CullerPlugin, Application, Container, Rectangle, Culler, CanvasTextMetrics, TextStyle, Assets, ExtensionType, Filter, UniformGroup, GpuProgram, GlProgram, defaultFilterVert } from 'pixi.js';
@@ -276,6 +276,24 @@ function analyzeAudio(mix, sources, stats, movieDuration, opts = {}) {
     issues
   };
 }
+
+// src/core/motionBlur.ts
+var DEFAULTS = { samples: 8, shutter: 0.5 };
+function resolveMotionBlur(spec, where) {
+  if (spec === void 0 || spec === null || spec === false) return null;
+  const o = spec === true ? {} : typeof spec === "number" ? { samples: spec } : spec;
+  if (typeof spec === "object") warnUnknownOptions(`${where} motionBlur`, o, ["samples", "shutter"]);
+  const samples = o.samples ?? DEFAULTS.samples, shutter = o.shutter ?? DEFAULTS.shutter;
+  if (!(Number.isInteger(samples) && samples >= 2 && samples <= 64)) throw new Error(`pixi-effects: ${where}: motionBlur samples must be a whole number from 2 to 64, got ${samples}`);
+  if (!(Number.isFinite(shutter) && shutter > 0 && shutter <= 1)) throw new Error(`pixi-effects: ${where}: motionBlur shutter must be a fraction of the frame time above 0 and up to 1 (0.5 is a 180\xB0 shutter), got ${shutter}`);
+  return { samples, shutter };
+}
+function blurTimes(frame, frameRate, mb, duration) {
+  const t = frame / frameRate, width = mb.shutter / frameRate;
+  return Array.from({ length: mb.samples }, (_, k) => Math.min(Math.max(t + ((k + 0.5) / mb.samples - 0.5) * width, 0), duration));
+}
+
+// src/core/Renderer.ts
 var VIDEO_CODEC_BY_FORMAT = {
   mp4: "avc",
   mov: "avc",
@@ -348,7 +366,10 @@ async function exportFrames(movie, options = {}) {
     format: container,
     target: new BufferTarget()
   });
-  const canvasSource = new CanvasSource(movie.app.canvas, {
+  const mb = options.motionBlur !== void 0 ? resolveMotionBlur(options.motionBlur, "movie.render()") : movie.motionBlur ?? null;
+  const stage = movie.app.canvas;
+  const blurCanvas = mb ? Object.assign(document.createElement("canvas"), { width: stage.width, height: stage.height }) : null;
+  const canvasSource = new CanvasSource(blurCanvas ?? stage, {
     codec: opts.video.codec,
     bitrate: opts.video.bitrate
   });
@@ -369,7 +390,8 @@ async function exportFrames(movie, options = {}) {
   const keyframeIntervalFrames = Math.max(1, Math.round(2 * movie.frameRate));
   try {
     for (let frame = 0; frame <= movie.totalFrames; frame++) {
-      await movie.gotoFrame(frame, true);
+      if (mb && blurCanvas) await movie._exposeFrame(frame, mb, blurCanvas, false);
+      else await movie.gotoFrame(frame, true);
       const isKey = frame === 0 || frame % keyframeIntervalFrames === 0;
       const addOpts = isKey ? { keyFrame: true } : void 0;
       await canvasSource.add(frame / movie.frameRate, 1 / movie.frameRate, addOpts);
@@ -378,6 +400,7 @@ async function exportFrames(movie, options = {}) {
     }
     await canvasSource.close();
     await output.finalize();
+    if (mb) await movie.gotoFrame(movie.totalFrames, true);
     return new Blob([output.target.buffer], { type: output.format.mimeType });
   } finally {
     movie.app.ticker.start();
@@ -1153,12 +1176,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) {
@@ -1173,9 +1196,16 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
         if (area === 0) onCanvas = "none";
       }
       const keys = 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 carried = carriers.some((c) => {
+        const k = 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;
@@ -1308,7 +1338,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);
@@ -1444,6 +1475,41 @@ function normalizePoster(poster, duration, frameRate) {
   return { seconds, frame: Math.round(seconds * frameRate) };
 }
 
+// src/core/loader.ts
+var FADE_FALLBACK_MS = 900;
+function resolveLoader(option, canvas) {
+  if (option === false) return null;
+  if (option instanceof HTMLElement) return option;
+  if (typeof option === "string") return document.querySelector(option);
+  let box = canvas?.parentElement ?? null;
+  for (let level = 0; box && level < 4; level++, box = box.parentElement) {
+    if (level > 0 && (box === document.body || box === document.documentElement)) break;
+    const found = box.querySelector(".pe-loader");
+    if (found) return found;
+  }
+  return null;
+}
+function dismissLoader(loader) {
+  if (!loader || loader.classList.contains("pe-loader--done")) return;
+  loader.classList.add("pe-loader--done");
+  loader.setAttribute("aria-hidden", "true");
+  let removed = false;
+  const remove = () => {
+    if (!removed) {
+      removed = true;
+      loader.remove();
+    }
+  };
+  loader.addEventListener("transitionend", remove, { once: true });
+  setTimeout(remove, FADE_FALLBACK_MS);
+}
+function failLoader(loader, message) {
+  if (!loader) return;
+  loader.setAttribute("data-state", "error");
+  if (loader.hasAttribute("data-label")) loader.setAttribute("data-label", message);
+  loader.setAttribute("aria-busy", "false");
+}
+
 // src/core/Movie.ts
 extensions.add(CullerPlugin);
 gsap.registerPlugin(PixiPlugin);
@@ -1459,6 +1525,8 @@ var Movie = class {
   _cancelAudioStart = null;
   /** The poster time in seconds (`movie.init({ poster })`), or null. */
   poster = null;
+  /** The motion blur `render()`, `snapshot()` and `contactSheet()` apply unless told otherwise (`movie.init({ motionBlur })`), or null. */
+  motionBlur = 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;
@@ -1515,7 +1583,7 @@ var Movie = class {
     const back = this.currentFrame;
     this.currentFrame = this._posterFrame;
     try {
-      this.timeline.time(this._posterFrame / this.frameRate);
+      this.timeline.time(this._timeOf(this._posterFrame));
       await this._awaitVideoFrames();
       this._updateSpace();
       this._renderNow();
@@ -1543,7 +1611,7 @@ var Movie = class {
     return this._audioContext;
   }
   async init(options = {}) {
-    warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster"]);
+    warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster", "motionBlur", "loader"]);
     this._initState = "pending";
     try {
       this.width = options.width ?? 1920;
@@ -1553,6 +1621,7 @@ var Movie = class {
       this.totalFrames = Math.round(this.duration * this.frameRate);
       const poster = normalizePoster(options.poster, this.duration, this.frameRate);
       this.poster = poster.seconds;
+      this.motionBlur = resolveMotionBlur(options.motionBlur, "movie.init()");
       this._posterFrame = poster.frame;
       this.background = options.background ?? "#000000";
       this.timeline = gsap.timeline({ paused: true, defaults: { ease: "none" } });
@@ -1619,7 +1688,9 @@ var Movie = class {
       this._initState = "ready";
       if (this._posterFrame !== null) await this._showPoster();
       this.emit("ready");
+      dismissLoader(resolveLoader(options.loader, options.canvas ?? this.app?.canvas ?? null));
     } catch (err) {
+      failLoader(resolveLoader(options.loader, options.canvas ?? null), "COULD NOT LOAD");
       try {
         await this.destroy();
       } catch (cleanupErr) {
@@ -1653,17 +1724,24 @@ var Movie = class {
   async _goto(frame) {
     this._atPoster = false;
     this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
-    this.timeline.time(this.currentFrame / this.frameRate);
+    this.timeline.time(this._timeOf(this.currentFrame));
     await this._awaitVideoFrames();
     this._updateSpace();
     this._renderNow();
     this.emit("frame", { frame: this.currentFrame, totalFrames: this.totalFrames });
   }
-  async _awaitVideoFrames() {
+  /**
+   * The moment frame `frame` shows. The very last frame (`totalFrames`) is at the end of the movie, where every layer's lifespan
+   * has just closed: it is drawn a hair before, so a layer that lasts to the end is still on screen in the final frame
+   * (it used to be an empty one, the last frame of every export).
+   */
+  _timeOf(frame) {
+    return Math.min(frame / this.frameRate, Math.max(0, this.duration - END_MARGIN));
+  }
+  async _awaitVideoFrames(t = this._timeOf(this.currentFrame)) {
     if (!this._rootSequence) return;
     const collected = [];
     collectVideoSequences(this._rootSequence, collected);
-    const t = this.currentFrame / this.frameRate;
     await Promise.all(collected.map((v) => {
       const local = t - (v.absoluteStart ?? v.at);
       if (local < 0 || local > (v.duration ?? 0)) return Promise.resolve();
@@ -1671,19 +1749,27 @@ var Movie = class {
     }));
   }
   async snapshot(frame = this.currentFrame, opts = {}) {
-    warnUnknownOptions("movie.snapshot()", opts, ["scale", "type", "as"]);
+    warnUnknownOptions("movie.snapshot()", opts, ["scale", "type", "as", "motionBlur"]);
     this._requireReady("snapshot");
-    await this._quietly(() => this.gotoFrame(clampFrame(frame, this.totalFrames), true));
+    const mb = this._blurFor(opts.motionBlur, "movie.snapshot()");
+    const f = clampFrame(frame, this.totalFrames);
+    let source = this.app.canvas;
+    if (mb) {
+      source = this._blurCanvas();
+      await this._quietly(() => this._exposeFrame(f, mb, source, true));
+    } else await this._quietly(() => this.gotoFrame(f, true));
     const scale = opts.scale ?? 1;
     const out = document.createElement("canvas");
     out.width = Math.max(1, Math.round(this.width * scale));
     out.height = Math.max(1, Math.round(this.height * scale));
-    out.getContext("2d").drawImage(this.app.canvas, 0, 0, out.width, out.height);
+    out.getContext("2d").drawImage(source, 0, 0, out.width, out.height);
     return encodeCanvas(out, opts.type ?? "image/png", opts.as ?? "blob");
   }
   async contactSheet(opts = {}) {
-    warnUnknownOptions("movie.contactSheet()", opts, ["frames", "times", "count", "columns", "cellWidth", "as"]);
+    warnUnknownOptions("movie.contactSheet()", opts, ["frames", "times", "count", "columns", "cellWidth", "as", "motionBlur"]);
     this._requireReady("contactSheet");
+    const mb = this._blurFor(opts.motionBlur, "movie.contactSheet()");
+    const blurred = mb ? this._blurCanvas() : null;
     const frames = (opts.frames ?? opts.times?.map((t) => Math.round(t * this.frameRate)) ?? pickFrames(this.totalFrames, opts.count ?? 6)).map((f) => clampFrame(f, this.totalFrames));
     const LABEL_H = 26;
     const L = sheetLayout(frames.length, opts.columns ?? 3, opts.cellWidth ?? 480, this.width, this.height, LABEL_H);
@@ -1697,9 +1783,10 @@ var Movie = class {
     try {
       for (let i = 0; i < frames.length; i++) {
         const f = frames[i];
-        await this._quietly(() => this.gotoFrame(f, true));
+        if (mb && blurred) await this._quietly(() => this._exposeFrame(f, mb, blurred, true));
+        else await this._quietly(() => this.gotoFrame(f, true));
         const { x, y } = L.positions[i];
-        g.drawImage(this.app.canvas, x, y + LABEL_H, L.cellW, L.cellH);
+        g.drawImage(blurred ?? this.app.canvas, x, y + LABEL_H, L.cellW, L.cellH);
         g.fillStyle = "#e8ecf8";
         g.font = "600 15px system-ui, sans-serif";
         g.textBaseline = "middle";
@@ -1769,9 +1856,46 @@ var Movie = class {
     }
   }
   /** Projects every `threeD` layer for the current frame (see src/space). */
-  _updateSpace() {
+  _updateSpace(t = this._timeOf(this.currentFrame)) {
     if (!this._rootSequence || !this.app) return;
-    this._rootSequence.updateSpace(this.currentFrame / this.frameRate, this.app.renderer);
+    this._rootSequence.updateSpace(t, this.app.renderer);
+  }
+  /** The motion blur an operation uses: its own option when given (`false` is off), otherwise the movie's. */
+  _blurFor(option, where) {
+    return option === void 0 ? this.motionBlur : resolveMotionBlur(option, where);
+  }
+  /**
+   * @internal Draw `frame` with motion blur into `target` (a canvas the size of the stage): the average of `mb.samples` renders at moments
+   * spread over the shutter interval around the frame time. With `settle` the playhead and the stage are left exactly on the frame.
+   */
+  async _exposeFrame(frame, mb, target, settle) {
+    const g = target.getContext("2d");
+    const stage = this.app.canvas;
+    this._atPoster = false;
+    const times = blurTimes(frame, this.frameRate, mb, Math.max(0, this.duration - END_MARGIN));
+    for (let k = 0; k < times.length; k++) {
+      const t = times[k];
+      this.timeline.time(t);
+      await this._awaitVideoFrames(t);
+      this._updateSpace(t);
+      this._renderNow();
+      if (k === 0) g.clearRect(0, 0, target.width, target.height);
+      g.globalAlpha = 1 / (k + 1);
+      g.drawImage(stage, 0, 0, target.width, target.height);
+    }
+    g.globalAlpha = 1;
+    if (settle) await this._goto(frame);
+    else {
+      this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
+      this.emit("frame", { frame: this.currentFrame, totalFrames: this.totalFrames });
+    }
+  }
+  _blurCanvas() {
+    const stage = this.app.canvas;
+    const c = document.createElement("canvas");
+    c.width = stage.width;
+    c.height = stage.height;
+    return c;
   }
   play() {
     if (this._initState !== "ready") return;
@@ -1870,7 +1994,7 @@ var Movie = class {
     return this.muted;
   }
   async render(options) {
-    warnUnknownOptions("movie.render()", options, ["format", "video", "audio"]);
+    warnUnknownOptions("movie.render()", options, ["format", "video", "audio", "motionBlur"]);
     try {
       return await this._quietly(() => exportFrames(this, options));
     } catch (err) {
@@ -1895,6 +2019,7 @@ var Movie = class {
     this._initState = "destroyed";
   }
 };
+var END_MARGIN = 1e-4;
 var clampFrame = (f, last) => Math.max(0, Math.min(Math.round(f), last));
 function encodeCanvas(canvas, type, as) {
   if (as === "dataURL") return Promise.resolve(canvas.toDataURL(type));
@@ -2136,6 +2261,365 @@ function orbit(opts) {
   return spec;
 }
 
+// src/presets/particles.ts
+var KEYS = ["count", "at", "emit", "life", "area", "angle", "speed", "gravity", "wind", "drag", "sway", "size", "scale", "fade", "colors", "shape", "spin", "seed", "name", "blendMode", "template", "sampleRate"];
+var SHAPES = ["circle", "rect", "star"];
+var MAX_KEYFRAMES = 3e4;
+function particles(opts) {
+  warnUnknownOptions("particles()", opts, KEYS);
+  const { count, at = 0, emit = 0, gravity = 0, wind = 0, drag = 0, sway, fade, colors = ["#ffffff"], shape = "circle", seed = 0, name = "particle", template, sampleRate = 20 } = opts;
+  if (!(Number.isInteger(count) && count > 0)) throw new Error(`particles(): count must be a whole number of particles (at least 1), got ${count}`);
+  const life = range("life", opts.life, 1e-6);
+  if (!opts.area || !Number.isFinite(opts.area.x) || !Number.isFinite(opts.area.y)) throw new Error("particles(): area is required: { x, y } (the centre) and optionally width / height to spread over");
+  if (!(Number.isFinite(emit) && emit >= 0)) throw new Error(`particles(): emit must be a number of seconds >= 0, got ${emit}`);
+  if (!(Number.isFinite(sampleRate) && sampleRate > 0)) throw new Error(`particles(): sampleRate must be a positive number (samples per second), got ${sampleRate}`);
+  if (!SHAPES.includes(shape)) {
+    const g = suggestName(String(shape), SHAPES);
+    throw new Error(`particles(): shape "${shape}" is not one of ${SHAPES.map((s) => `"${s}"`).join(", ")}${g ? `; did you mean "${g}"?` : ""}`);
+  }
+  const angle = range("angle", opts.angle ?? [0, 360], -Infinity);
+  const speed = range("speed", opts.speed ?? [100, 300], 0);
+  const size = range("size", opts.size ?? [3, 6], 0);
+  const spin = opts.spin === void 0 ? null : range("spin", opts.spin, -Infinity);
+  const curved = gravity !== 0 || wind !== 0 || drag !== 0 || !!sway;
+  const worst = curved ? Math.max(1, Math.ceil(life[1] * sampleRate)) : 1;
+  if (count * worst > MAX_KEYFRAMES) {
+    throw new Error(`particles(): too many keyframes (${count} particles \xD7 up to ${worst} samples each): lower count or life, or lower sampleRate (now ${sampleRate})`);
+  }
+  const round2 = (v) => Math.round(v * 1e6) / 1e6;
+  const out = [];
+  for (let i = 0; i < count; i++) {
+    const r = random(seed * 1000003 + i * 7919 + 17);
+    const pick = ([a2, b]) => a2 + r() * (b - a2);
+    const born = at + r() * emit;
+    const lifetime = pick(life);
+    const ax = (r() - 0.5) * (opts.area.width ?? 0), ay = (r() - 0.5) * (opts.area.height ?? 0);
+    const x0 = opts.area.x + ax, y0 = opts.area.y + ay;
+    const a = pick(angle) * Math.PI / 180, v = pick(speed);
+    const vx = v * Math.cos(a), vy = v * Math.sin(a);
+    const s = pick(size);
+    const color = colors[Math.min(colors.length - 1, Math.floor(r() * colors.length))];
+    const turn = spin ? pick(spin) : 0;
+    const startAngle = spin ? r() * 360 : 0;
+    const swayAmp = sway?.amp ?? 0, swayFreq = sway?.freq ?? 1;
+    const n0 = sway ? noise(0, seed * 1000003 + i) : 0;
+    const at_ = (t) => {
+      const axis = (p0, v0, acc) => {
+        if (drag > 0) {
+          const vInf = acc / drag;
+          return p0 + vInf * t + (v0 - vInf) * (1 - Math.exp(-drag * t)) / drag;
+        }
+        return p0 + v0 * t + 0.5 * acc * t * t;
+      };
+      const sw = sway ? swayAmp * (noise(t * swayFreq, seed * 1000003 + i) - n0) : 0;
+      return { x: axis(x0, vx, wind) + sw, y: axis(y0, vy, gravity) };
+    };
+    const kfs = [];
+    const steps = curved ? Math.max(1, Math.ceil(lifetime * sampleRate)) : 1;
+    const step = lifetime / steps;
+    for (let k = 1; k <= steps; k++) {
+      const p = at_(k * step);
+      kfs.push({ at: round2((k - 1) * step), to: { x: round2(p.x), y: round2(p.y) }, duration: round2(step), ease: "none" });
+    }
+    if (opts.scale) kfs.push({ at: 0, to: { scale: opts.scale[1] }, duration: round2(lifetime), ease: "none" });
+    if (turn !== 0) kfs.push({ at: 0, to: { rotation: round2(startAngle + turn * lifetime) }, duration: round2(lifetime), ease: "none" });
+    if (fade?.in) kfs.push({ at: 0, to: { alpha: 1 }, duration: fade.in, ease: "none" });
+    if (fade?.out) kfs.push({ at: -fade.out, from: { alpha: 1 }, to: { alpha: 0 }, duration: fade.out, ease: "none" });
+    const initial = { x: round2(x0), y: round2(y0) };
+    if (opts.scale) initial.scale = opts.scale[0];
+    if (fade?.in) initial.alpha = 0;
+    if (spin) initial.rotation = round2(startAngle);
+    const common = { name: `${name}-${i}`, at: round2(born), duration: round2(lifetime), ...opts.blendMode ? { blendMode: opts.blendMode } : {} };
+    if (template) {
+      const t = template;
+      out.push({ ...t, ...common, initial: { ...t.initial, ...initial }, keyframes: [...t.keyframes ?? [], ...kfs] });
+      continue;
+    }
+    const style = { ...initial, fillColor: color };
+    if (shape === "circle") out.push({ type: "shape", shape: "circle", radius: round2(s), ...common, initial: style, keyframes: kfs });
+    else if (shape === "rect") out.push({ type: "shape", shape: "rect", width: round2(s * 2), height: round2(s * 2), ...common, initial: style, keyframes: kfs });
+    else {
+      const points = [];
+      for (let p = 0; p < 10; p++) {
+        const rad = p % 2 === 0 ? s : s * 0.45, ang = -Math.PI / 2 + p * Math.PI / 5;
+        points.push([round2(rad * Math.cos(ang)), round2(rad * Math.sin(ang))]);
+      }
+      out.push({ type: "shape", shape: "polygon", points, ...common, initial: style, keyframes: kfs });
+    }
+  }
+  return out;
+}
+function range(name, v, min) {
+  const [a, b] = typeof v === "number" ? [v, v] : v;
+  if (!(Number.isFinite(a) && Number.isFinite(b)) || a > b || a < min || min > 0 && a <= 0) {
+    throw new Error(`particles(): ${name} must be a number or [min, max] with min <= max${min > -Infinity ? ` and min >= ${min}` : ""}, got ${JSON.stringify(v)}`);
+  }
+  return [a, b];
+}
+
+// src/presets/followPath.ts
+var KEYS2 = ["d", "at", "duration", "ease", "from", "to", "orient", "rotate", "frameRate"];
+var MAX_STEPS = 2e3;
+function followPath(opts) {
+  warnUnknownOptions("followPath()", opts, KEYS2);
+  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 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}`);
+  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 = 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) {
+  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 = (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 KEYS3 = ["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) {
+  warnUnknownOptions("animateText()", options, KEYS3);
+  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 = 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) {
   warnUnknownOptions("withFade()", opts, ["in", "out"]);
@@ -2156,6 +2640,6 @@ function withFade(spec, opts) {
   return spec;
 }
 
-export { Movie, kenBurns, measureText, orbit, splitText, withFade };
+export { Movie, animateText, dismissLoader, failLoader, followPath, kenBurns, measureText, orbit, particles, resolveLoader, splitText, stagger, wiggle, withFade };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map