pixi-effects 0.10.0 → 0.11.0

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk4WJUSDJJ_cjs = require('./chunk-4WJUSDJJ.cjs');
-var chunkS3ZI4MKS_cjs = require('./chunk-S3ZI4MKS.cjs');
+var chunkF7NCHS6Q_cjs = require('./chunk-F7NCHS6Q.cjs');
+var chunk6NWJLVCA_cjs = require('./chunk-6NWJLVCA.cjs');
 var chunkUQBGW5DO_cjs = require('./chunk-UQBGW5DO.cjs');
 var PIXI = require('pixi.js');
 var gsap = require('gsap');
@@ -296,6 +296,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") chunkUQBGW5DO_cjs.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",
@@ -368,7 +386,10 @@ async function exportFrames(movie, options = {}) {
     format: container,
     target: new mediabunny.BufferTarget()
   });
-  const canvasSource = new mediabunny.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 mediabunny.CanvasSource(blurCanvas ?? stage, {
     codec: opts.video.codec,
     bitrate: opts.video.bitrate
   });
@@ -389,7 +410,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);
@@ -398,6 +420,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();
@@ -843,16 +866,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 = chunkS3ZI4MKS_cjs.resolveAt(t.at, parentDuration);
+    const tStart = chunk6NWJLVCA_cjs.resolveAt(t.at, parentDuration);
     const tEnd = tStart + t.duration;
     const fromSeq = fromEntry.seq;
-    const fromStart = chunkS3ZI4MKS_cjs.resolveAt(fromSeq.at, parentDuration);
+    const fromStart = chunk6NWJLVCA_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 = chunkS3ZI4MKS_cjs.resolveAt(toSeq.at, parentDuration);
+    const toStart = chunk6NWJLVCA_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})`);
@@ -1192,9 +1215,9 @@ 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 = chunkS3ZI4MKS_cjs.collectPropKeys(seq.spec);
+      const keys = chunk6NWJLVCA_cjs.collectPropKeys(seq.spec);
       const carried = carriers.some((c) => {
-        const k = chunkS3ZI4MKS_cjs.collectPropKeys(c.spec);
+        const k = chunk6NWJLVCA_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"));
@@ -1215,7 +1238,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 chunk4WJUSDJJ_cjs.CompositionSequence) walk2(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
+      if (seq instanceof chunkF7NCHS6Q_cjs.CompositionSequence) walk2(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
     });
   };
   walk2(root, "", false, true);
@@ -1275,10 +1298,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 + chunkS3ZI4MKS_cjs.resolveAt(kf.at, span))).sort((a, b) => a - b).slice(0, MAX_KEYS);
+    const keys = (seq.spec.keyframes ?? []).map((kf) => round(start + chunk6NWJLVCA_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 chunk4WJUSDJJ_cjs.CompositionSequence;
+    const isComp = seq instanceof chunkF7NCHS6Q_cjs.CompositionSequence;
     if (isComp) walk(seq, start, end, depth + 1, prefix + name + "/", inner, transitions);
     entries.push({ row, inner, groupable: !isComp });
   });
@@ -1472,6 +1495,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
 PIXI.extensions.add(PIXI.CullerPlugin);
 gsap.gsap.registerPlugin(PixiPlugin.PixiPlugin);
@@ -1487,6 +1545,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;
@@ -1543,7 +1603,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();
@@ -1571,7 +1631,7 @@ var Movie = class {
     return this._audioContext;
   }
   async init(options = {}) {
-    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster"]);
+    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster", "motionBlur", "loader"]);
     this._initState = "pending";
     try {
       this.width = options.width ?? 1920;
@@ -1581,6 +1641,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.gsap.timeline({ paused: true, defaults: { ease: "none" } });
@@ -1618,7 +1679,7 @@ var Movie = class {
         height: options.composition.height ?? this.height,
         duration: options.composition.duration ?? this.duration
       } : void 0;
-      await chunkS3ZI4MKS_cjs.ensureFilterLibrary(seededComposition);
+      await chunk6NWJLVCA_cjs.ensureFilterLibrary(seededComposition);
       const userComposition = seededComposition ? expandTransitions(seededComposition) : void 0;
       const rootSeqSpec = {
         type: "composition",
@@ -1628,7 +1689,7 @@ var Movie = class {
         ...userComposition
       };
       if (userComposition) carryTransitionWindows(userComposition, rootSeqSpec);
-      const composition = new chunk4WJUSDJJ_cjs.CompositionSequence(rootSeqSpec, null, rootShape);
+      const composition = new chunkF7NCHS6Q_cjs.CompositionSequence(rootSeqSpec, null, rootShape);
       await composition.build();
       this._rootSequence = composition;
       if (composition.target) root.addChild(composition.target);
@@ -1647,7 +1708,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) {
@@ -1681,17 +1744,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();
@@ -1699,19 +1769,27 @@ var Movie = class {
     }));
   }
   async snapshot(frame = this.currentFrame, opts = {}) {
-    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.snapshot()", opts, ["scale", "type", "as"]);
+    chunkUQBGW5DO_cjs.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 = {}) {
-    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.contactSheet()", opts, ["frames", "times", "count", "columns", "cellWidth", "as"]);
+    chunkUQBGW5DO_cjs.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);
@@ -1725,9 +1803,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";
@@ -1797,9 +1876,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;
@@ -1898,7 +2014,7 @@ var Movie = class {
     return this.muted;
   }
   async render(options) {
-    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.render()", options, ["format", "video", "audio"]);
+    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.render()", options, ["format", "video", "audio", "motionBlur"]);
     try {
       return await this._quietly(() => exportFrames(this, options));
     } catch (err) {
@@ -1923,6 +2039,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));
@@ -2127,17 +2244,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 ?? chunkS3ZI4MKS_cjs.homeDistance(height, fov ?? chunkS3ZI4MKS_cjs.DEFAULT_FOV);
+  const fixedR = opts.radius ?? chunk6NWJLVCA_cjs.homeDistance(height, fov ?? chunk6NWJLVCA_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)) * chunkS3ZI4MKS_cjs.DEG;
+    const a = (start + degrees * easeFn(p)) * chunk6NWJLVCA_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 = chunkS3ZI4MKS_cjs.homeDistance(height, f);
+    const R = chunk6NWJLVCA_cjs.homeDistance(height, f);
     return { x: cx + R * Math.sin(a), z: R * Math.cos(a), fov: f };
   };
   const keyframes = [];
@@ -2164,11 +2281,107 @@ 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) {
+  chunkUQBGW5DO_cjs.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 = chunkUQBGW5DO_cjs.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 = chunk6NWJLVCA_cjs.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 ? chunk6NWJLVCA_cjs.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 * (chunk6NWJLVCA_cjs.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 KEYS = ["d", "at", "duration", "ease", "from", "to", "orient", "rotate", "frameRate"];
+var KEYS2 = ["d", "at", "duration", "ease", "from", "to", "orient", "rotate", "frameRate"];
 var MAX_STEPS = 2e3;
 function followPath(opts) {
-  chunkUQBGW5DO_cjs.warnUnknownOptions("followPath()", opts, KEYS);
+  chunkUQBGW5DO_cjs.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}`);
@@ -2180,7 +2393,7 @@ function followPath(opts) {
   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)) {
+  for (const line of chunk6NWJLVCA_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]);
@@ -2261,7 +2474,7 @@ 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);
+    const r = chunk6NWJLVCA_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]];
@@ -2323,7 +2536,7 @@ function wiggle(opts) {
         to[n] = p.around;
         return;
       }
-      const off = (chunkS3ZI4MKS_cjs.rand(seed * 7919 + pi * 104729 + s * 31 + 1) * 2 - 1) * p.amp;
+      const off = (chunk6NWJLVCA_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 });
@@ -2332,7 +2545,7 @@ function wiggle(opts) {
 }
 
 // src/presets/animateText.ts
-var KEYS2 = ["by", "x", "y", "align", "name", "at", "duration", "in", "out", "stagger", "idle", "styleFor"];
+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" },
@@ -2344,7 +2557,7 @@ var PRESETS = {
 };
 var PRESET_NAMES = Object.keys(PRESETS);
 function animateText(text, style, options) {
-  chunkUQBGW5DO_cjs.warnUnknownOptions("animateText()", options, KEYS2);
+  chunkUQBGW5DO_cjs.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 });
@@ -2449,26 +2662,30 @@ function withFade(spec, opts) {
 
 Object.defineProperty(exports, "noise", {
   enumerable: true,
-  get: function () { return chunkS3ZI4MKS_cjs.noise; }
+  get: function () { return chunk6NWJLVCA_cjs.noise; }
 });
 Object.defineProperty(exports, "rand", {
   enumerable: true,
-  get: function () { return chunkS3ZI4MKS_cjs.rand; }
+  get: function () { return chunk6NWJLVCA_cjs.rand; }
 });
 Object.defineProperty(exports, "random", {
   enumerable: true,
-  get: function () { return chunkS3ZI4MKS_cjs.random; }
+  get: function () { return chunk6NWJLVCA_cjs.random; }
 });
 Object.defineProperty(exports, "registerSequenceType", {
   enumerable: true,
-  get: function () { return chunkS3ZI4MKS_cjs.registerSequenceType; }
+  get: function () { return chunk6NWJLVCA_cjs.registerSequenceType; }
 });
 exports.Movie = Movie;
 exports.animateText = animateText;
+exports.dismissLoader = dismissLoader;
+exports.failLoader = failLoader;
 exports.followPath = followPath;
 exports.kenBurns = kenBurns;
 exports.measureText = measureText;
 exports.orbit = orbit;
+exports.particles = particles;
+exports.resolveLoader = resolveLoader;
 exports.splitText = splitText;
 exports.stagger = stagger;
 exports.wiggle = wiggle;