pixi-effects 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +6 -6
  3. package/ai/SKILL.md +3 -3
  4. package/ai/reference/cheatsheet.md +5 -2
  5. package/ai/reference/pitfalls.md +2 -2
  6. package/ai/reference/recipes.md +19 -10
  7. package/ai/template.html +11 -8
  8. package/ai/tools/render.mjs +14 -5
  9. package/dist/Composition-7TEKHZNQ.cjs +14 -0
  10. package/dist/{Composition-EKVTUYCI.cjs.map → Composition-7TEKHZNQ.cjs.map} +1 -1
  11. package/dist/Composition-HIISJAX2.js +5 -0
  12. package/dist/{Composition-NJCOMGD7.js.map → Composition-HIISJAX2.js.map} +1 -1
  13. package/dist/Controller.d.cts +1 -1
  14. package/dist/Controller.d.ts +1 -1
  15. package/dist/{Movie-w3GliuP3.d.cts → Movie-DSSNOF3T.d.cts} +60 -1
  16. package/dist/{Movie-puD9oZPg.d.ts → Movie-nzmWsxWX.d.ts} +60 -1
  17. package/dist/{chunk-WDGAVOMS.js → chunk-3IPDNC3E.js} +8 -5
  18. package/dist/chunk-3IPDNC3E.js.map +1 -0
  19. package/dist/{chunk-S3ZI4MKS.cjs → chunk-6NWJLVCA.cjs} +3 -3
  20. package/dist/{chunk-S3ZI4MKS.cjs.map → chunk-6NWJLVCA.cjs.map} +1 -1
  21. package/dist/{chunk-JAMNDBXW.js → chunk-C6QHKYC5.js} +3 -3
  22. package/dist/{chunk-JAMNDBXW.js.map → chunk-C6QHKYC5.js.map} +1 -1
  23. package/dist/{chunk-4WJUSDJJ.cjs → chunk-F7NCHS6Q.cjs} +31 -28
  24. package/dist/chunk-F7NCHS6Q.cjs.map +1 -0
  25. package/dist/index.cjs +259 -42
  26. package/dist/index.cjs.map +1 -1
  27. package/dist/index.d.cts +74 -2
  28. package/dist/index.d.ts +74 -2
  29. package/dist/index.js +237 -24
  30. package/dist/index.js.map +1 -1
  31. package/dist/loader.css +110 -0
  32. package/dist/three.cjs +5 -5
  33. package/dist/three.js +1 -1
  34. package/docs/api.md +15 -1
  35. package/docs/dsl.md +29 -0
  36. package/llms-full.txt +73 -18
  37. package/package.json +5 -2
  38. package/dist/Composition-EKVTUYCI.cjs +0 -14
  39. package/dist/Composition-NJCOMGD7.js +0 -5
  40. package/dist/chunk-4WJUSDJJ.cjs.map +0 -1
  41. package/dist/chunk-WDGAVOMS.js.map +0 -1
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, M as Movie, d as MovieErrorEvent, e as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, f as SoundMeasure, T as TimelineData, g as TimelineHtmlOptions, h as TimelineRow, i as TimelineSvgOptions, j as TimelineTransition, V as VolumeEvent } from './Movie-w3GliuP3.cjs';
1
+ export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, d as LoaderOption, M as MotionBlurOptions, e as MotionBlurSpec, f as Movie, g as MovieErrorEvent, h as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, i as SoundMeasure, T as TimelineData, j as TimelineHtmlOptions, k as TimelineRow, l as TimelineSvgOptions, m as TimelineTransition, V as VolumeEvent, n as dismissLoader, o as failLoader, r as resolveLoader } from './Movie-DSSNOF3T.cjs';
2
2
  import { S as Sequence } from './Base-CwUxTfja.cjs';
3
3
  import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, K as Keyframe, T as TextSequenceSpec, b as SequenceCommon } from './types-BXu28nJj.cjs';
4
4
  export { A as ArcShapeSpec, c as AssetSpec, d as AudioAssetSpec, e as AudioSequenceSpec, f as AudioSfxSpec, g as ChromaKeyFilterSpec, h as CircleShapeSpec, i as CompositionSequenceSpec, j as CompositionSpec, k as CrossfadeTransition, l as CustomFilterSpec, D as DipTransition, m as DissolveTransition, E as EllipseShapeSpec, n as Expr, F as FilterSpec, G as GradientSpec, o as IrisTransition, L as LineShapeSpec, N as NullSequenceSpec, P as PathShapeSpec, p as PolygonShapeSpec, q as PropValue, r as Props, R as RectShapeSpec, s as SfxKnobs, t as SfxOptions, u as SfxPreset, v as SfxVoice, w as ShapeSequenceSpec, x as SlideTransition, y as TransitionCommon, z as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-BXu28nJj.cjs';
@@ -162,6 +162,78 @@ interface OrbitOptions {
162
162
  */
163
163
  declare function orbit(opts: OrbitOptions): CameraSequenceSpec;
164
164
 
165
+ type Range = number | [number, number];
166
+ interface ParticlesOptions {
167
+ /** How many particles. Required. */
168
+ count: number;
169
+ /** When the first one can be born, in composition seconds. Default 0. */
170
+ at?: number;
171
+ /** Births are spread over this many seconds (0, the default, is a burst: all at once). */
172
+ emit?: number;
173
+ /** How long each lives, in seconds: a number or `[min, max]`. Required. */
174
+ life: Range;
175
+ /** Where they start: the centre `x`, `y`, and optionally a `width` / `height` to spread over (snow: `{ x: 640, y: -20, width: 1280 }`). Required. */
176
+ area: {
177
+ x: number;
178
+ y: number;
179
+ width?: number;
180
+ height?: number;
181
+ };
182
+ /** Direction of the launch, degrees: 0 is right, 90 down, −90 up. A number or `[min, max]`. Default `[0, 360]`. */
183
+ angle?: Range;
184
+ /** Launch speed in px per second. Default `[100, 300]`. */
185
+ speed?: Range;
186
+ /** Acceleration down, px/s² (negative floats up). Default 0. */
187
+ gravity?: number;
188
+ /** Acceleration sideways, px/s². Default 0. */
189
+ wind?: number;
190
+ /** Air drag per second: they slow toward a terminal speed. Default 0. */
191
+ drag?: number;
192
+ /** A smooth side-to-side wobble: up to about ±`amp` px, `freq` wobbles per second (default 1). Snow, leaves, embers. */
193
+ sway?: {
194
+ amp: number;
195
+ freq?: number;
196
+ };
197
+ /** Radius in px (a square's half-side): a number or `[min, max]`. Default `[3, 6]`. */
198
+ size?: Range;
199
+ /** Scale over the life, `[start, end]` (`[1, 0]` shrinks away). Default none. */
200
+ scale?: [number, number];
201
+ /** Alpha ramps in seconds: `in` from transparent at birth, `out` back to transparent at the end of the life. */
202
+ fade?: {
203
+ in?: number;
204
+ out?: number;
205
+ };
206
+ /** Fill colours, picked at random for each particle. Default white. */
207
+ colors?: string[];
208
+ /** `'circle'` (default), `'rect'` (a square) or `'star'`. */
209
+ shape?: 'circle' | 'rect' | 'star';
210
+ /** Turning speed in degrees per second (a number or `[min, max]`; they also start at a random angle). Default none. */
211
+ spin?: Range;
212
+ /** Another seed is another burst. Default 0. */
213
+ seed?: number;
214
+ /** Layers are named `<name>-0`, `<name>-1`, … (default `'particle'`). */
215
+ name?: string;
216
+ /** `'add'` makes overlapping particles glow. */
217
+ blendMode?: string;
218
+ /** Use this layer (any type: an image, a text) for every particle instead of a shape; its keyframes are kept. */
219
+ template?: SequenceSpec;
220
+ /** Samples per second of a curved path (gravity, wind, drag, sway): straight steps between them. Default 20. */
221
+ sampleRate?: number;
222
+ }
223
+ /**
224
+ * Particles as plain layers: a burst, a fountain, snow, confetti, sparks. Each one is a layer with its own seeded start,
225
+ * velocity, size, colour and life, and a path baked into keyframes (so playback, seeking and export agree), living only
226
+ * while it is alive. Spread the result into `sequences`.
227
+ *
228
+ * ```js
229
+ * ...particles({ count: 80, at: 2, life: [0.8, 1.6], area: { x: 640, y: 400 }, speed: [150, 450], gravity: 500,
230
+ * size: [3, 7], colors: ['#ffd166', '#ff6b9d', '#4cc9f0'], fade: { out: 0.4 }, blendMode: 'add' })
231
+ * ```
232
+ *
233
+ * A particle with no gravity, wind, drag or sway is one straight tween; a curved path is sampled `sampleRate` times a second.
234
+ */
235
+ declare function particles(opts: ParticlesOptions): SequenceSpec[];
236
+
165
237
  interface FollowPathOptions {
166
238
  /** The route, as SVG path data in the same canvas coordinates the layer's `x` / `y` use. Several sub-paths are walked in order. */
167
239
  d: string;
@@ -422,4 +494,4 @@ interface WithFadeOptions {
422
494
  */
423
495
  declare function withFade<T extends SequenceCommon>(spec: T, opts: WithFadeOptions): T;
424
496
 
425
- export { type AnimateTextOptions, type AnimateTextTween, CameraSequenceSpec, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, type OrbitOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, followPath, kenBurns, measureText, noise, orbit, rand, random, registerSequenceType, splitText, stagger, wiggle, withFade };
497
+ export { type AnimateTextOptions, type AnimateTextTween, CameraSequenceSpec, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, type OrbitOptions, type ParticlesOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, followPath, kenBurns, measureText, noise, orbit, particles, rand, random, registerSequenceType, splitText, stagger, wiggle, withFade };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, M as Movie, d as MovieErrorEvent, e as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, f as SoundMeasure, T as TimelineData, g as TimelineHtmlOptions, h as TimelineRow, i as TimelineSvgOptions, j as TimelineTransition, V as VolumeEvent } from './Movie-puD9oZPg.js';
1
+ export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, d as LoaderOption, M as MotionBlurOptions, e as MotionBlurSpec, f as Movie, g as MovieErrorEvent, h as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, i as SoundMeasure, T as TimelineData, j as TimelineHtmlOptions, k as TimelineRow, l as TimelineSvgOptions, m as TimelineTransition, V as VolumeEvent, n as dismissLoader, o as failLoader, r as resolveLoader } from './Movie-nzmWsxWX.js';
2
2
  import { S as Sequence } from './Base-CyvSLoCP.js';
3
3
  import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, K as Keyframe, T as TextSequenceSpec, b as SequenceCommon } from './types-BXu28nJj.js';
4
4
  export { A as ArcShapeSpec, c as AssetSpec, d as AudioAssetSpec, e as AudioSequenceSpec, f as AudioSfxSpec, g as ChromaKeyFilterSpec, h as CircleShapeSpec, i as CompositionSequenceSpec, j as CompositionSpec, k as CrossfadeTransition, l as CustomFilterSpec, D as DipTransition, m as DissolveTransition, E as EllipseShapeSpec, n as Expr, F as FilterSpec, G as GradientSpec, o as IrisTransition, L as LineShapeSpec, N as NullSequenceSpec, P as PathShapeSpec, p as PolygonShapeSpec, q as PropValue, r as Props, R as RectShapeSpec, s as SfxKnobs, t as SfxOptions, u as SfxPreset, v as SfxVoice, w as ShapeSequenceSpec, x as SlideTransition, y as TransitionCommon, z as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-BXu28nJj.js';
@@ -162,6 +162,78 @@ interface OrbitOptions {
162
162
  */
163
163
  declare function orbit(opts: OrbitOptions): CameraSequenceSpec;
164
164
 
165
+ type Range = number | [number, number];
166
+ interface ParticlesOptions {
167
+ /** How many particles. Required. */
168
+ count: number;
169
+ /** When the first one can be born, in composition seconds. Default 0. */
170
+ at?: number;
171
+ /** Births are spread over this many seconds (0, the default, is a burst: all at once). */
172
+ emit?: number;
173
+ /** How long each lives, in seconds: a number or `[min, max]`. Required. */
174
+ life: Range;
175
+ /** Where they start: the centre `x`, `y`, and optionally a `width` / `height` to spread over (snow: `{ x: 640, y: -20, width: 1280 }`). Required. */
176
+ area: {
177
+ x: number;
178
+ y: number;
179
+ width?: number;
180
+ height?: number;
181
+ };
182
+ /** Direction of the launch, degrees: 0 is right, 90 down, −90 up. A number or `[min, max]`. Default `[0, 360]`. */
183
+ angle?: Range;
184
+ /** Launch speed in px per second. Default `[100, 300]`. */
185
+ speed?: Range;
186
+ /** Acceleration down, px/s² (negative floats up). Default 0. */
187
+ gravity?: number;
188
+ /** Acceleration sideways, px/s². Default 0. */
189
+ wind?: number;
190
+ /** Air drag per second: they slow toward a terminal speed. Default 0. */
191
+ drag?: number;
192
+ /** A smooth side-to-side wobble: up to about ±`amp` px, `freq` wobbles per second (default 1). Snow, leaves, embers. */
193
+ sway?: {
194
+ amp: number;
195
+ freq?: number;
196
+ };
197
+ /** Radius in px (a square's half-side): a number or `[min, max]`. Default `[3, 6]`. */
198
+ size?: Range;
199
+ /** Scale over the life, `[start, end]` (`[1, 0]` shrinks away). Default none. */
200
+ scale?: [number, number];
201
+ /** Alpha ramps in seconds: `in` from transparent at birth, `out` back to transparent at the end of the life. */
202
+ fade?: {
203
+ in?: number;
204
+ out?: number;
205
+ };
206
+ /** Fill colours, picked at random for each particle. Default white. */
207
+ colors?: string[];
208
+ /** `'circle'` (default), `'rect'` (a square) or `'star'`. */
209
+ shape?: 'circle' | 'rect' | 'star';
210
+ /** Turning speed in degrees per second (a number or `[min, max]`; they also start at a random angle). Default none. */
211
+ spin?: Range;
212
+ /** Another seed is another burst. Default 0. */
213
+ seed?: number;
214
+ /** Layers are named `<name>-0`, `<name>-1`, … (default `'particle'`). */
215
+ name?: string;
216
+ /** `'add'` makes overlapping particles glow. */
217
+ blendMode?: string;
218
+ /** Use this layer (any type: an image, a text) for every particle instead of a shape; its keyframes are kept. */
219
+ template?: SequenceSpec;
220
+ /** Samples per second of a curved path (gravity, wind, drag, sway): straight steps between them. Default 20. */
221
+ sampleRate?: number;
222
+ }
223
+ /**
224
+ * Particles as plain layers: a burst, a fountain, snow, confetti, sparks. Each one is a layer with its own seeded start,
225
+ * velocity, size, colour and life, and a path baked into keyframes (so playback, seeking and export agree), living only
226
+ * while it is alive. Spread the result into `sequences`.
227
+ *
228
+ * ```js
229
+ * ...particles({ count: 80, at: 2, life: [0.8, 1.6], area: { x: 640, y: 400 }, speed: [150, 450], gravity: 500,
230
+ * size: [3, 7], colors: ['#ffd166', '#ff6b9d', '#4cc9f0'], fade: { out: 0.4 }, blendMode: 'add' })
231
+ * ```
232
+ *
233
+ * A particle with no gravity, wind, drag or sway is one straight tween; a curved path is sampled `sampleRate` times a second.
234
+ */
235
+ declare function particles(opts: ParticlesOptions): SequenceSpec[];
236
+
165
237
  interface FollowPathOptions {
166
238
  /** The route, as SVG path data in the same canvas coordinates the layer's `x` / `y` use. Several sub-paths are walked in order. */
167
239
  d: string;
@@ -422,4 +494,4 @@ interface WithFadeOptions {
422
494
  */
423
495
  declare function withFade<T extends SequenceCommon>(spec: T, opts: WithFadeOptions): T;
424
496
 
425
- export { type AnimateTextOptions, type AnimateTextTween, CameraSequenceSpec, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, type OrbitOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, followPath, kenBurns, measureText, noise, orbit, rand, random, registerSequenceType, splitText, stagger, wiggle, withFade };
497
+ export { type AnimateTextOptions, type AnimateTextTween, CameraSequenceSpec, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, type OrbitOptions, type ParticlesOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, followPath, kenBurns, measureText, noise, orbit, particles, rand, random, registerSequenceType, splitText, stagger, wiggle, withFade };
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
- import { CompositionSequence } from './chunk-WDGAVOMS.js';
2
- import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, flattenSvgPath, random, rand, DEG, resolveAt, collectPropKeys } from './chunk-JAMNDBXW.js';
3
- export { noise, rand, random, registerSequenceType } from './chunk-JAMNDBXW.js';
1
+ import { CompositionSequence } from './chunk-3IPDNC3E.js';
2
+ import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, random, noise, flattenSvgPath, rand, DEG, resolveAt, collectPropKeys } from './chunk-C6QHKYC5.js';
3
+ export { noise, rand, random, registerSequenceType } from './chunk-C6QHKYC5.js';
4
4
  import { warnUnknownOptions, suggestName } from './chunk-DKGG7WD4.js';
5
5
  import * as PIXI from 'pixi.js';
6
6
  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 = {}) {
276
276
  issues
277
277
  };
278
278
  }
279
+
280
+ // src/core/motionBlur.ts
281
+ var DEFAULTS = { samples: 8, shutter: 0.5 };
282
+ function resolveMotionBlur(spec, where) {
283
+ if (spec === void 0 || spec === null || spec === false) return null;
284
+ const o = spec === true ? {} : typeof spec === "number" ? { samples: spec } : spec;
285
+ if (typeof spec === "object") warnUnknownOptions(`${where} motionBlur`, o, ["samples", "shutter"]);
286
+ const samples = o.samples ?? DEFAULTS.samples, shutter = o.shutter ?? DEFAULTS.shutter;
287
+ 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}`);
288
+ 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}`);
289
+ return { samples, shutter };
290
+ }
291
+ function blurTimes(frame, frameRate, mb, duration) {
292
+ const t = frame / frameRate, width = mb.shutter / frameRate;
293
+ return Array.from({ length: mb.samples }, (_, k) => Math.min(Math.max(t + ((k + 0.5) / mb.samples - 0.5) * width, 0), duration));
294
+ }
295
+
296
+ // src/core/Renderer.ts
279
297
  var VIDEO_CODEC_BY_FORMAT = {
280
298
  mp4: "avc",
281
299
  mov: "avc",
@@ -348,7 +366,10 @@ async function exportFrames(movie, options = {}) {
348
366
  format: container,
349
367
  target: new BufferTarget()
350
368
  });
351
- const canvasSource = new CanvasSource(movie.app.canvas, {
369
+ const mb = options.motionBlur !== void 0 ? resolveMotionBlur(options.motionBlur, "movie.render()") : movie.motionBlur ?? null;
370
+ const stage = movie.app.canvas;
371
+ const blurCanvas = mb ? Object.assign(document.createElement("canvas"), { width: stage.width, height: stage.height }) : null;
372
+ const canvasSource = new CanvasSource(blurCanvas ?? stage, {
352
373
  codec: opts.video.codec,
353
374
  bitrate: opts.video.bitrate
354
375
  });
@@ -369,7 +390,8 @@ async function exportFrames(movie, options = {}) {
369
390
  const keyframeIntervalFrames = Math.max(1, Math.round(2 * movie.frameRate));
370
391
  try {
371
392
  for (let frame = 0; frame <= movie.totalFrames; frame++) {
372
- await movie.gotoFrame(frame, true);
393
+ if (mb && blurCanvas) await movie._exposeFrame(frame, mb, blurCanvas, false);
394
+ else await movie.gotoFrame(frame, true);
373
395
  const isKey = frame === 0 || frame % keyframeIntervalFrames === 0;
374
396
  const addOpts = isKey ? { keyFrame: true } : void 0;
375
397
  await canvasSource.add(frame / movie.frameRate, 1 / movie.frameRate, addOpts);
@@ -378,6 +400,7 @@ async function exportFrames(movie, options = {}) {
378
400
  }
379
401
  await canvasSource.close();
380
402
  await output.finalize();
403
+ if (mb) await movie.gotoFrame(movie.totalFrames, true);
381
404
  return new Blob([output.target.buffer], { type: output.format.mimeType });
382
405
  } finally {
383
406
  movie.app.ticker.start();
@@ -1452,6 +1475,41 @@ function normalizePoster(poster, duration, frameRate) {
1452
1475
  return { seconds, frame: Math.round(seconds * frameRate) };
1453
1476
  }
1454
1477
 
1478
+ // src/core/loader.ts
1479
+ var FADE_FALLBACK_MS = 900;
1480
+ function resolveLoader(option, canvas) {
1481
+ if (option === false) return null;
1482
+ if (option instanceof HTMLElement) return option;
1483
+ if (typeof option === "string") return document.querySelector(option);
1484
+ let box = canvas?.parentElement ?? null;
1485
+ for (let level = 0; box && level < 4; level++, box = box.parentElement) {
1486
+ if (level > 0 && (box === document.body || box === document.documentElement)) break;
1487
+ const found = box.querySelector(".pe-loader");
1488
+ if (found) return found;
1489
+ }
1490
+ return null;
1491
+ }
1492
+ function dismissLoader(loader) {
1493
+ if (!loader || loader.classList.contains("pe-loader--done")) return;
1494
+ loader.classList.add("pe-loader--done");
1495
+ loader.setAttribute("aria-hidden", "true");
1496
+ let removed = false;
1497
+ const remove = () => {
1498
+ if (!removed) {
1499
+ removed = true;
1500
+ loader.remove();
1501
+ }
1502
+ };
1503
+ loader.addEventListener("transitionend", remove, { once: true });
1504
+ setTimeout(remove, FADE_FALLBACK_MS);
1505
+ }
1506
+ function failLoader(loader, message) {
1507
+ if (!loader) return;
1508
+ loader.setAttribute("data-state", "error");
1509
+ if (loader.hasAttribute("data-label")) loader.setAttribute("data-label", message);
1510
+ loader.setAttribute("aria-busy", "false");
1511
+ }
1512
+
1455
1513
  // src/core/Movie.ts
1456
1514
  extensions.add(CullerPlugin);
1457
1515
  gsap.registerPlugin(PixiPlugin);
@@ -1467,6 +1525,8 @@ var Movie = class {
1467
1525
  _cancelAudioStart = null;
1468
1526
  /** The poster time in seconds (`movie.init({ poster })`), or null. */
1469
1527
  poster = null;
1528
+ /** The motion blur `render()`, `snapshot()` and `contactSheet()` apply unless told otherwise (`movie.init({ motionBlur })`), or null. */
1529
+ motionBlur = null;
1470
1530
  _posterFrame = null;
1471
1531
  /** The canvas shows the poster picture while the playhead is still at frame 0 (like `<video poster>`): the first seek or play replaces it. */
1472
1532
  _atPoster = false;
@@ -1523,7 +1583,7 @@ var Movie = class {
1523
1583
  const back = this.currentFrame;
1524
1584
  this.currentFrame = this._posterFrame;
1525
1585
  try {
1526
- this.timeline.time(this._posterFrame / this.frameRate);
1586
+ this.timeline.time(this._timeOf(this._posterFrame));
1527
1587
  await this._awaitVideoFrames();
1528
1588
  this._updateSpace();
1529
1589
  this._renderNow();
@@ -1551,7 +1611,7 @@ var Movie = class {
1551
1611
  return this._audioContext;
1552
1612
  }
1553
1613
  async init(options = {}) {
1554
- warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster"]);
1614
+ warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster", "motionBlur", "loader"]);
1555
1615
  this._initState = "pending";
1556
1616
  try {
1557
1617
  this.width = options.width ?? 1920;
@@ -1561,6 +1621,7 @@ var Movie = class {
1561
1621
  this.totalFrames = Math.round(this.duration * this.frameRate);
1562
1622
  const poster = normalizePoster(options.poster, this.duration, this.frameRate);
1563
1623
  this.poster = poster.seconds;
1624
+ this.motionBlur = resolveMotionBlur(options.motionBlur, "movie.init()");
1564
1625
  this._posterFrame = poster.frame;
1565
1626
  this.background = options.background ?? "#000000";
1566
1627
  this.timeline = gsap.timeline({ paused: true, defaults: { ease: "none" } });
@@ -1627,7 +1688,9 @@ var Movie = class {
1627
1688
  this._initState = "ready";
1628
1689
  if (this._posterFrame !== null) await this._showPoster();
1629
1690
  this.emit("ready");
1691
+ dismissLoader(resolveLoader(options.loader, options.canvas ?? this.app?.canvas ?? null));
1630
1692
  } catch (err) {
1693
+ failLoader(resolveLoader(options.loader, options.canvas ?? null), "COULD NOT LOAD");
1631
1694
  try {
1632
1695
  await this.destroy();
1633
1696
  } catch (cleanupErr) {
@@ -1661,17 +1724,24 @@ var Movie = class {
1661
1724
  async _goto(frame) {
1662
1725
  this._atPoster = false;
1663
1726
  this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
1664
- this.timeline.time(this.currentFrame / this.frameRate);
1727
+ this.timeline.time(this._timeOf(this.currentFrame));
1665
1728
  await this._awaitVideoFrames();
1666
1729
  this._updateSpace();
1667
1730
  this._renderNow();
1668
1731
  this.emit("frame", { frame: this.currentFrame, totalFrames: this.totalFrames });
1669
1732
  }
1670
- async _awaitVideoFrames() {
1733
+ /**
1734
+ * The moment frame `frame` shows. The very last frame (`totalFrames`) is at the end of the movie, where every layer's lifespan
1735
+ * 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
1736
+ * (it used to be an empty one, the last frame of every export).
1737
+ */
1738
+ _timeOf(frame) {
1739
+ return Math.min(frame / this.frameRate, Math.max(0, this.duration - END_MARGIN));
1740
+ }
1741
+ async _awaitVideoFrames(t = this._timeOf(this.currentFrame)) {
1671
1742
  if (!this._rootSequence) return;
1672
1743
  const collected = [];
1673
1744
  collectVideoSequences(this._rootSequence, collected);
1674
- const t = this.currentFrame / this.frameRate;
1675
1745
  await Promise.all(collected.map((v) => {
1676
1746
  const local = t - (v.absoluteStart ?? v.at);
1677
1747
  if (local < 0 || local > (v.duration ?? 0)) return Promise.resolve();
@@ -1679,19 +1749,27 @@ var Movie = class {
1679
1749
  }));
1680
1750
  }
1681
1751
  async snapshot(frame = this.currentFrame, opts = {}) {
1682
- warnUnknownOptions("movie.snapshot()", opts, ["scale", "type", "as"]);
1752
+ warnUnknownOptions("movie.snapshot()", opts, ["scale", "type", "as", "motionBlur"]);
1683
1753
  this._requireReady("snapshot");
1684
- await this._quietly(() => this.gotoFrame(clampFrame(frame, this.totalFrames), true));
1754
+ const mb = this._blurFor(opts.motionBlur, "movie.snapshot()");
1755
+ const f = clampFrame(frame, this.totalFrames);
1756
+ let source = this.app.canvas;
1757
+ if (mb) {
1758
+ source = this._blurCanvas();
1759
+ await this._quietly(() => this._exposeFrame(f, mb, source, true));
1760
+ } else await this._quietly(() => this.gotoFrame(f, true));
1685
1761
  const scale = opts.scale ?? 1;
1686
1762
  const out = document.createElement("canvas");
1687
1763
  out.width = Math.max(1, Math.round(this.width * scale));
1688
1764
  out.height = Math.max(1, Math.round(this.height * scale));
1689
- out.getContext("2d").drawImage(this.app.canvas, 0, 0, out.width, out.height);
1765
+ out.getContext("2d").drawImage(source, 0, 0, out.width, out.height);
1690
1766
  return encodeCanvas(out, opts.type ?? "image/png", opts.as ?? "blob");
1691
1767
  }
1692
1768
  async contactSheet(opts = {}) {
1693
- warnUnknownOptions("movie.contactSheet()", opts, ["frames", "times", "count", "columns", "cellWidth", "as"]);
1769
+ warnUnknownOptions("movie.contactSheet()", opts, ["frames", "times", "count", "columns", "cellWidth", "as", "motionBlur"]);
1694
1770
  this._requireReady("contactSheet");
1771
+ const mb = this._blurFor(opts.motionBlur, "movie.contactSheet()");
1772
+ const blurred = mb ? this._blurCanvas() : null;
1695
1773
  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));
1696
1774
  const LABEL_H = 26;
1697
1775
  const L = sheetLayout(frames.length, opts.columns ?? 3, opts.cellWidth ?? 480, this.width, this.height, LABEL_H);
@@ -1705,9 +1783,10 @@ var Movie = class {
1705
1783
  try {
1706
1784
  for (let i = 0; i < frames.length; i++) {
1707
1785
  const f = frames[i];
1708
- await this._quietly(() => this.gotoFrame(f, true));
1786
+ if (mb && blurred) await this._quietly(() => this._exposeFrame(f, mb, blurred, true));
1787
+ else await this._quietly(() => this.gotoFrame(f, true));
1709
1788
  const { x, y } = L.positions[i];
1710
- g.drawImage(this.app.canvas, x, y + LABEL_H, L.cellW, L.cellH);
1789
+ g.drawImage(blurred ?? this.app.canvas, x, y + LABEL_H, L.cellW, L.cellH);
1711
1790
  g.fillStyle = "#e8ecf8";
1712
1791
  g.font = "600 15px system-ui, sans-serif";
1713
1792
  g.textBaseline = "middle";
@@ -1777,9 +1856,46 @@ var Movie = class {
1777
1856
  }
1778
1857
  }
1779
1858
  /** Projects every `threeD` layer for the current frame (see src/space). */
1780
- _updateSpace() {
1859
+ _updateSpace(t = this._timeOf(this.currentFrame)) {
1781
1860
  if (!this._rootSequence || !this.app) return;
1782
- this._rootSequence.updateSpace(this.currentFrame / this.frameRate, this.app.renderer);
1861
+ this._rootSequence.updateSpace(t, this.app.renderer);
1862
+ }
1863
+ /** The motion blur an operation uses: its own option when given (`false` is off), otherwise the movie's. */
1864
+ _blurFor(option, where) {
1865
+ return option === void 0 ? this.motionBlur : resolveMotionBlur(option, where);
1866
+ }
1867
+ /**
1868
+ * @internal Draw `frame` with motion blur into `target` (a canvas the size of the stage): the average of `mb.samples` renders at moments
1869
+ * spread over the shutter interval around the frame time. With `settle` the playhead and the stage are left exactly on the frame.
1870
+ */
1871
+ async _exposeFrame(frame, mb, target, settle) {
1872
+ const g = target.getContext("2d");
1873
+ const stage = this.app.canvas;
1874
+ this._atPoster = false;
1875
+ const times = blurTimes(frame, this.frameRate, mb, Math.max(0, this.duration - END_MARGIN));
1876
+ for (let k = 0; k < times.length; k++) {
1877
+ const t = times[k];
1878
+ this.timeline.time(t);
1879
+ await this._awaitVideoFrames(t);
1880
+ this._updateSpace(t);
1881
+ this._renderNow();
1882
+ if (k === 0) g.clearRect(0, 0, target.width, target.height);
1883
+ g.globalAlpha = 1 / (k + 1);
1884
+ g.drawImage(stage, 0, 0, target.width, target.height);
1885
+ }
1886
+ g.globalAlpha = 1;
1887
+ if (settle) await this._goto(frame);
1888
+ else {
1889
+ this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
1890
+ this.emit("frame", { frame: this.currentFrame, totalFrames: this.totalFrames });
1891
+ }
1892
+ }
1893
+ _blurCanvas() {
1894
+ const stage = this.app.canvas;
1895
+ const c = document.createElement("canvas");
1896
+ c.width = stage.width;
1897
+ c.height = stage.height;
1898
+ return c;
1783
1899
  }
1784
1900
  play() {
1785
1901
  if (this._initState !== "ready") return;
@@ -1878,7 +1994,7 @@ var Movie = class {
1878
1994
  return this.muted;
1879
1995
  }
1880
1996
  async render(options) {
1881
- warnUnknownOptions("movie.render()", options, ["format", "video", "audio"]);
1997
+ warnUnknownOptions("movie.render()", options, ["format", "video", "audio", "motionBlur"]);
1882
1998
  try {
1883
1999
  return await this._quietly(() => exportFrames(this, options));
1884
2000
  } catch (err) {
@@ -1903,6 +2019,7 @@ var Movie = class {
1903
2019
  this._initState = "destroyed";
1904
2020
  }
1905
2021
  };
2022
+ var END_MARGIN = 1e-4;
1906
2023
  var clampFrame = (f, last) => Math.max(0, Math.min(Math.round(f), last));
1907
2024
  function encodeCanvas(canvas, type, as) {
1908
2025
  if (as === "dataURL") return Promise.resolve(canvas.toDataURL(type));
@@ -2144,11 +2261,107 @@ function orbit(opts) {
2144
2261
  return spec;
2145
2262
  }
2146
2263
 
2264
+ // src/presets/particles.ts
2265
+ var KEYS = ["count", "at", "emit", "life", "area", "angle", "speed", "gravity", "wind", "drag", "sway", "size", "scale", "fade", "colors", "shape", "spin", "seed", "name", "blendMode", "template", "sampleRate"];
2266
+ var SHAPES = ["circle", "rect", "star"];
2267
+ var MAX_KEYFRAMES = 3e4;
2268
+ function particles(opts) {
2269
+ warnUnknownOptions("particles()", opts, KEYS);
2270
+ 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;
2271
+ if (!(Number.isInteger(count) && count > 0)) throw new Error(`particles(): count must be a whole number of particles (at least 1), got ${count}`);
2272
+ const life = range("life", opts.life, 1e-6);
2273
+ 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");
2274
+ if (!(Number.isFinite(emit) && emit >= 0)) throw new Error(`particles(): emit must be a number of seconds >= 0, got ${emit}`);
2275
+ if (!(Number.isFinite(sampleRate) && sampleRate > 0)) throw new Error(`particles(): sampleRate must be a positive number (samples per second), got ${sampleRate}`);
2276
+ if (!SHAPES.includes(shape)) {
2277
+ const g = suggestName(String(shape), SHAPES);
2278
+ throw new Error(`particles(): shape "${shape}" is not one of ${SHAPES.map((s) => `"${s}"`).join(", ")}${g ? `; did you mean "${g}"?` : ""}`);
2279
+ }
2280
+ const angle = range("angle", opts.angle ?? [0, 360], -Infinity);
2281
+ const speed = range("speed", opts.speed ?? [100, 300], 0);
2282
+ const size = range("size", opts.size ?? [3, 6], 0);
2283
+ const spin = opts.spin === void 0 ? null : range("spin", opts.spin, -Infinity);
2284
+ const curved = gravity !== 0 || wind !== 0 || drag !== 0 || !!sway;
2285
+ const worst = curved ? Math.max(1, Math.ceil(life[1] * sampleRate)) : 1;
2286
+ if (count * worst > MAX_KEYFRAMES) {
2287
+ throw new Error(`particles(): too many keyframes (${count} particles \xD7 up to ${worst} samples each): lower count or life, or lower sampleRate (now ${sampleRate})`);
2288
+ }
2289
+ const round2 = (v) => Math.round(v * 1e6) / 1e6;
2290
+ const out = [];
2291
+ for (let i = 0; i < count; i++) {
2292
+ const r = random(seed * 1000003 + i * 7919 + 17);
2293
+ const pick = ([a2, b]) => a2 + r() * (b - a2);
2294
+ const born = at + r() * emit;
2295
+ const lifetime = pick(life);
2296
+ const ax = (r() - 0.5) * (opts.area.width ?? 0), ay = (r() - 0.5) * (opts.area.height ?? 0);
2297
+ const x0 = opts.area.x + ax, y0 = opts.area.y + ay;
2298
+ const a = pick(angle) * Math.PI / 180, v = pick(speed);
2299
+ const vx = v * Math.cos(a), vy = v * Math.sin(a);
2300
+ const s = pick(size);
2301
+ const color = colors[Math.min(colors.length - 1, Math.floor(r() * colors.length))];
2302
+ const turn = spin ? pick(spin) : 0;
2303
+ const startAngle = spin ? r() * 360 : 0;
2304
+ const swayAmp = sway?.amp ?? 0, swayFreq = sway?.freq ?? 1;
2305
+ const n0 = sway ? noise(0, seed * 1000003 + i) : 0;
2306
+ const at_ = (t) => {
2307
+ const axis = (p0, v0, acc) => {
2308
+ if (drag > 0) {
2309
+ const vInf = acc / drag;
2310
+ return p0 + vInf * t + (v0 - vInf) * (1 - Math.exp(-drag * t)) / drag;
2311
+ }
2312
+ return p0 + v0 * t + 0.5 * acc * t * t;
2313
+ };
2314
+ const sw = sway ? swayAmp * (noise(t * swayFreq, seed * 1000003 + i) - n0) : 0;
2315
+ return { x: axis(x0, vx, wind) + sw, y: axis(y0, vy, gravity) };
2316
+ };
2317
+ const kfs = [];
2318
+ const steps = curved ? Math.max(1, Math.ceil(lifetime * sampleRate)) : 1;
2319
+ const step = lifetime / steps;
2320
+ for (let k = 1; k <= steps; k++) {
2321
+ const p = at_(k * step);
2322
+ kfs.push({ at: round2((k - 1) * step), to: { x: round2(p.x), y: round2(p.y) }, duration: round2(step), ease: "none" });
2323
+ }
2324
+ if (opts.scale) kfs.push({ at: 0, to: { scale: opts.scale[1] }, duration: round2(lifetime), ease: "none" });
2325
+ if (turn !== 0) kfs.push({ at: 0, to: { rotation: round2(startAngle + turn * lifetime) }, duration: round2(lifetime), ease: "none" });
2326
+ if (fade?.in) kfs.push({ at: 0, to: { alpha: 1 }, duration: fade.in, ease: "none" });
2327
+ if (fade?.out) kfs.push({ at: -fade.out, from: { alpha: 1 }, to: { alpha: 0 }, duration: fade.out, ease: "none" });
2328
+ const initial = { x: round2(x0), y: round2(y0) };
2329
+ if (opts.scale) initial.scale = opts.scale[0];
2330
+ if (fade?.in) initial.alpha = 0;
2331
+ if (spin) initial.rotation = round2(startAngle);
2332
+ const common = { name: `${name}-${i}`, at: round2(born), duration: round2(lifetime), ...opts.blendMode ? { blendMode: opts.blendMode } : {} };
2333
+ if (template) {
2334
+ const t = template;
2335
+ out.push({ ...t, ...common, initial: { ...t.initial, ...initial }, keyframes: [...t.keyframes ?? [], ...kfs] });
2336
+ continue;
2337
+ }
2338
+ const style = { ...initial, fillColor: color };
2339
+ if (shape === "circle") out.push({ type: "shape", shape: "circle", radius: round2(s), ...common, initial: style, keyframes: kfs });
2340
+ else if (shape === "rect") out.push({ type: "shape", shape: "rect", width: round2(s * 2), height: round2(s * 2), ...common, initial: style, keyframes: kfs });
2341
+ else {
2342
+ const points = [];
2343
+ for (let p = 0; p < 10; p++) {
2344
+ const rad = p % 2 === 0 ? s : s * 0.45, ang = -Math.PI / 2 + p * Math.PI / 5;
2345
+ points.push([round2(rad * Math.cos(ang)), round2(rad * Math.sin(ang))]);
2346
+ }
2347
+ out.push({ type: "shape", shape: "polygon", points, ...common, initial: style, keyframes: kfs });
2348
+ }
2349
+ }
2350
+ return out;
2351
+ }
2352
+ function range(name, v, min) {
2353
+ const [a, b] = typeof v === "number" ? [v, v] : v;
2354
+ if (!(Number.isFinite(a) && Number.isFinite(b)) || a > b || a < min || min > 0 && a <= 0) {
2355
+ throw new Error(`particles(): ${name} must be a number or [min, max] with min <= max${min > -Infinity ? ` and min >= ${min}` : ""}, got ${JSON.stringify(v)}`);
2356
+ }
2357
+ return [a, b];
2358
+ }
2359
+
2147
2360
  // src/presets/followPath.ts
2148
- var KEYS = ["d", "at", "duration", "ease", "from", "to", "orient", "rotate", "frameRate"];
2361
+ var KEYS2 = ["d", "at", "duration", "ease", "from", "to", "orient", "rotate", "frameRate"];
2149
2362
  var MAX_STEPS = 2e3;
2150
2363
  function followPath(opts) {
2151
- warnUnknownOptions("followPath()", opts, KEYS);
2364
+ warnUnknownOptions("followPath()", opts, KEYS2);
2152
2365
  const { d, at = 0, duration, ease = "none", from = 0, to = 1, orient = false, rotate = 0, frameRate = 30 } = opts;
2153
2366
  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"');
2154
2367
  if (!(Number.isFinite(duration) && duration > 0)) throw new Error(`followPath(): duration must be a positive number of seconds, got ${duration}`);
@@ -2312,7 +2525,7 @@ function wiggle(opts) {
2312
2525
  }
2313
2526
 
2314
2527
  // src/presets/animateText.ts
2315
- var KEYS2 = ["by", "x", "y", "align", "name", "at", "duration", "in", "out", "stagger", "idle", "styleFor"];
2528
+ var KEYS3 = ["by", "x", "y", "align", "name", "at", "duration", "in", "out", "stagger", "idle", "styleFor"];
2316
2529
  var PRESETS = {
2317
2530
  rise: { from: { y: 40, alpha: 0 }, duration: 0.5, ease: "back.out(2)" },
2318
2531
  drop: { from: { y: -50, alpha: 0 }, duration: 0.7, ease: "bounce.out" },
@@ -2324,7 +2537,7 @@ var PRESETS = {
2324
2537
  };
2325
2538
  var PRESET_NAMES = Object.keys(PRESETS);
2326
2539
  function animateText(text, style, options) {
2327
- warnUnknownOptions("animateText()", options, KEYS2);
2540
+ warnUnknownOptions("animateText()", options, KEYS3);
2328
2541
  const { by = "chars", x = 0, y = 0, align = "left", name = "text", at = 0, duration, idle, styleFor } = options;
2329
2542
  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}`);
2330
2543
  const pieces = splitText(text, style, { by, x, y, align });
@@ -2427,6 +2640,6 @@ function withFade(spec, opts) {
2427
2640
  return spec;
2428
2641
  }
2429
2642
 
2430
- export { Movie, animateText, followPath, kenBurns, measureText, orbit, splitText, stagger, wiggle, withFade };
2643
+ export { Movie, animateText, dismissLoader, failLoader, followPath, kenBurns, measureText, orbit, particles, resolveLoader, splitText, stagger, wiggle, withFade };
2431
2644
  //# sourceMappingURL=index.js.map
2432
2645
  //# sourceMappingURL=index.js.map