pixi-effects 0.9.0 → 0.10.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 (51) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +6 -6
  3. package/ai/SKILL.md +2 -1
  4. package/ai/reference/cheatsheet.md +13 -5
  5. package/ai/reference/pitfalls.md +2 -2
  6. package/ai/reference/recipes.md +123 -2
  7. package/ai/template.html +3 -3
  8. package/dist/{Base-CSIulyIq.d.cts → Base-CwUxTfja.d.cts} +1 -1
  9. package/dist/{Base-DVgwyIUj.d.ts → Base-CyvSLoCP.d.ts} +1 -1
  10. package/dist/Composition-EKVTUYCI.cjs +14 -0
  11. package/dist/{Composition-CM62XJKT.cjs.map → Composition-EKVTUYCI.cjs.map} +1 -1
  12. package/dist/Composition-NJCOMGD7.js +5 -0
  13. package/dist/{Composition-RJDSQYTV.js.map → Composition-NJCOMGD7.js.map} +1 -1
  14. package/dist/Controller.cjs +34 -0
  15. package/dist/Controller.cjs.map +1 -1
  16. package/dist/Controller.d.cts +12 -2
  17. package/dist/Controller.d.ts +12 -2
  18. package/dist/Controller.js +34 -0
  19. package/dist/Controller.js.map +1 -1
  20. package/dist/{Movie-QMlFyHkf.d.ts → Movie-puD9oZPg.d.ts} +1 -1
  21. package/dist/{Movie-qGHp15c_.d.cts → Movie-w3GliuP3.d.cts} +1 -1
  22. package/dist/{chunk-PDBDDGG5.cjs → chunk-4WJUSDJJ.cjs} +103 -30
  23. package/dist/chunk-4WJUSDJJ.cjs.map +1 -0
  24. package/dist/{chunk-FNKSXBKB.js → chunk-JAMNDBXW.js} +193 -14
  25. package/dist/chunk-JAMNDBXW.js.map +1 -0
  26. package/dist/{chunk-AGMNSJJH.cjs → chunk-S3ZI4MKS.cjs} +196 -12
  27. package/dist/chunk-S3ZI4MKS.cjs.map +1 -0
  28. package/dist/{chunk-O4AJYUPK.js → chunk-WDGAVOMS.js} +85 -12
  29. package/dist/chunk-WDGAVOMS.js.map +1 -0
  30. package/dist/index.cjs +309 -22
  31. package/dist/index.cjs.map +1 -1
  32. package/dist/index.d.cts +231 -5
  33. package/dist/index.d.ts +231 -5
  34. package/dist/index.js +282 -11
  35. package/dist/index.js.map +1 -1
  36. package/dist/three.cjs +5 -5
  37. package/dist/three.d.cts +2 -2
  38. package/dist/three.d.ts +2 -2
  39. package/dist/three.js +1 -1
  40. package/dist/{types-oJijbn-K.d.ts → types-BXu28nJj.d.cts} +26 -2
  41. package/dist/{types-oJijbn-K.d.cts → types-BXu28nJj.d.ts} +26 -2
  42. package/docs/api.md +1 -0
  43. package/docs/dsl.md +108 -2
  44. package/llms-full.txt +249 -12
  45. package/package.json +1 -1
  46. package/dist/Composition-CM62XJKT.cjs +0 -14
  47. package/dist/Composition-RJDSQYTV.js +0 -5
  48. package/dist/chunk-AGMNSJJH.cjs.map +0 -1
  49. package/dist/chunk-FNKSXBKB.js.map +0 -1
  50. package/dist/chunk-O4AJYUPK.js.map +0 -1
  51. package/dist/chunk-PDBDDGG5.cjs.map +0 -1
package/dist/three.cjs CHANGED
@@ -1,11 +1,11 @@
1
1
  'use strict';
2
2
 
3
- var chunkAGMNSJJH_cjs = require('./chunk-AGMNSJJH.cjs');
3
+ var chunkS3ZI4MKS_cjs = require('./chunk-S3ZI4MKS.cjs');
4
4
  require('./chunk-UQBGW5DO.cjs');
5
5
  var pixi_js = require('pixi.js');
6
6
  var three$1 = require('three');
7
7
 
8
- var ThreeSequence = class extends chunkAGMNSJJH_cjs.Sequence {
8
+ var ThreeSequence = class extends chunkS3ZI4MKS_cjs.Sequence {
9
9
  _renderer = null;
10
10
  _scene = null;
11
11
  _camera = null;
@@ -24,7 +24,7 @@ var ThreeSequence = class extends chunkAGMNSJJH_cjs.Sequence {
24
24
  if (this.duration === void 0) {
25
25
  this.duration = this.parent?.duration ?? this.root.duration;
26
26
  }
27
- const scope = chunkAGMNSJJH_cjs.buildScope(this, this.parent, this.root);
27
+ const scope = chunkS3ZI4MKS_cjs.buildScope(this, this.parent, this.root);
28
28
  const width = resolveDim(spec.width, scope) ?? this.parent?.width ?? this.root.width;
29
29
  const height = resolveDim(spec.height, scope) ?? this.parent?.height ?? this.root.height;
30
30
  const resolution = spec.resolution ?? 1;
@@ -144,12 +144,12 @@ var ThreeSequence = class extends chunkAGMNSJJH_cjs.Sequence {
144
144
  function resolveDim(v, scope) {
145
145
  if (v === void 0) return void 0;
146
146
  if (typeof v === "number") return v;
147
- return chunkAGMNSJJH_cjs.evaluateExpr(v, scope);
147
+ return chunkS3ZI4MKS_cjs.evaluateExpr(v, scope);
148
148
  }
149
149
 
150
150
  // src/three/index.ts
151
151
  function registerThree() {
152
- chunkAGMNSJJH_cjs.registerSequenceType("three", ThreeSequence);
152
+ chunkS3ZI4MKS_cjs.registerSequenceType("three", ThreeSequence);
153
153
  }
154
154
  function three(spec) {
155
155
  return spec;
package/dist/three.d.cts CHANGED
@@ -1,6 +1,6 @@
1
- import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-oJijbn-K.cjs';
1
+ import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-BXu28nJj.cjs';
2
2
  import { Scene, Camera, WebGLRenderer } from 'three';
3
- import { S as Sequence, P as PathRouters } from './Base-CSIulyIq.cjs';
3
+ import { S as Sequence, P as PathRouters } from './Base-CwUxTfja.cjs';
4
4
  import 'pixi.js';
5
5
  import 'gsap';
6
6
 
package/dist/three.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-oJijbn-K.js';
1
+ import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-BXu28nJj.js';
2
2
  import { Scene, Camera, WebGLRenderer } from 'three';
3
- import { S as Sequence, P as PathRouters } from './Base-DVgwyIUj.js';
3
+ import { S as Sequence, P as PathRouters } from './Base-CyvSLoCP.js';
4
4
  import 'pixi.js';
5
5
  import 'gsap';
6
6
 
package/dist/three.js CHANGED
@@ -1,4 +1,4 @@
1
- import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-FNKSXBKB.js';
1
+ import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-JAMNDBXW.js';
2
2
  import './chunk-DKGG7WD4.js';
3
3
  import { Texture, Sprite } from 'pixi.js';
4
4
  import { WebGLRenderer, Scene, PerspectiveCamera } from 'three';
@@ -145,6 +145,12 @@ interface DissolveTransition extends TransitionCommon {
145
145
  type TransitionSpec = CrossfadeTransition | WipeTransition | IrisTransition | SlideTransition | DipTransition | ZoomTransition | DissolveTransition;
146
146
  interface SequenceCommon {
147
147
  name?: string;
148
+ /**
149
+ * Attach this layer to a `{ type: 'null' }` layer (by its `name`): it is drawn inside that layer, so its `x` / `y`
150
+ * are measured from the null's origin and the null's position, rotation, scale and alpha carry it along. The layer is
151
+ * drawn where the null is in the stack, not where it is listed. Only `null` layers can be parents (they chain); not for `threeD` layers.
152
+ */
153
+ parent?: string;
148
154
  at?: number;
149
155
  duration?: number;
150
156
  initial?: Props;
@@ -450,9 +456,27 @@ interface PathShapeSpec extends ShapeBase, Trimmable {
450
456
  shape: 'path';
451
457
  /** SVG path data (`d` attribute). Goes through PIXI's GraphicsContext.svg(). */
452
458
  d: string;
459
+ /**
460
+ * A second outline (SVG path data, in the same canvas coordinates as `d`) to morph into. Animate `morph` from 0 (the
461
+ * `d` outline) to 1 (this one); in between the layer is drawn as a polygon of points half way from one to the other.
462
+ * Sub-paths are paired in order (an extra one grows from / shrinks to its centre), and closed outlines are lined up so
463
+ * they do not twist.
464
+ */
465
+ morphTo?: string;
466
+ /** How far the morph has gone, 0–1 (animatable, top level or in `initial`). Needs `morphTo`. Default 0. */
467
+ morph?: number;
468
+ /** Points per sub-path the outlines are sampled at for the in-between shapes (8–2048, default 128). */
469
+ morphPoints?: number;
453
470
  }
454
471
  type ShapeSequenceSpec = RectShapeSpec | CircleShapeSpec | EllipseShapeSpec | ArcShapeSpec | LineShapeSpec | PolygonShapeSpec | PathShapeSpec;
455
- type SequenceSpec = VideoSequenceSpec | ImageSequenceSpec | TextSequenceSpec | AudioSequenceSpec | CompositionSequenceSpec | CameraSequenceSpec | ShapeSequenceSpec;
472
+ /**
473
+ * A layer that draws nothing, only moves: the parent of other layers (`parent: 'name'`). Animate `x y rotation scale
474
+ * scaleX scaleY skewX skewY alpha pivotX pivotY` in `initial` / `keyframes` like any layer; its children follow.
475
+ */
476
+ interface NullSequenceSpec extends SequenceCommon {
477
+ type: 'null';
478
+ }
479
+ type SequenceSpec = NullSequenceSpec | VideoSequenceSpec | ImageSequenceSpec | TextSequenceSpec | AudioSequenceSpec | CompositionSequenceSpec | CameraSequenceSpec | ShapeSequenceSpec;
456
480
  /** Top-level composition (root node) — same as `CompositionSequenceSpec` minus the discriminant. */
457
481
  interface CompositionSpec extends SequenceCommon {
458
482
  width?: number;
@@ -489,4 +513,4 @@ interface AudioDescriptor {
489
513
  }[];
490
514
  }
491
515
 
492
- export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };
516
+ export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, NullSequenceSpec as N, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };
@@ -145,6 +145,12 @@ interface DissolveTransition extends TransitionCommon {
145
145
  type TransitionSpec = CrossfadeTransition | WipeTransition | IrisTransition | SlideTransition | DipTransition | ZoomTransition | DissolveTransition;
146
146
  interface SequenceCommon {
147
147
  name?: string;
148
+ /**
149
+ * Attach this layer to a `{ type: 'null' }` layer (by its `name`): it is drawn inside that layer, so its `x` / `y`
150
+ * are measured from the null's origin and the null's position, rotation, scale and alpha carry it along. The layer is
151
+ * drawn where the null is in the stack, not where it is listed. Only `null` layers can be parents (they chain); not for `threeD` layers.
152
+ */
153
+ parent?: string;
148
154
  at?: number;
149
155
  duration?: number;
150
156
  initial?: Props;
@@ -450,9 +456,27 @@ interface PathShapeSpec extends ShapeBase, Trimmable {
450
456
  shape: 'path';
451
457
  /** SVG path data (`d` attribute). Goes through PIXI's GraphicsContext.svg(). */
452
458
  d: string;
459
+ /**
460
+ * A second outline (SVG path data, in the same canvas coordinates as `d`) to morph into. Animate `morph` from 0 (the
461
+ * `d` outline) to 1 (this one); in between the layer is drawn as a polygon of points half way from one to the other.
462
+ * Sub-paths are paired in order (an extra one grows from / shrinks to its centre), and closed outlines are lined up so
463
+ * they do not twist.
464
+ */
465
+ morphTo?: string;
466
+ /** How far the morph has gone, 0–1 (animatable, top level or in `initial`). Needs `morphTo`. Default 0. */
467
+ morph?: number;
468
+ /** Points per sub-path the outlines are sampled at for the in-between shapes (8–2048, default 128). */
469
+ morphPoints?: number;
453
470
  }
454
471
  type ShapeSequenceSpec = RectShapeSpec | CircleShapeSpec | EllipseShapeSpec | ArcShapeSpec | LineShapeSpec | PolygonShapeSpec | PathShapeSpec;
455
- type SequenceSpec = VideoSequenceSpec | ImageSequenceSpec | TextSequenceSpec | AudioSequenceSpec | CompositionSequenceSpec | CameraSequenceSpec | ShapeSequenceSpec;
472
+ /**
473
+ * A layer that draws nothing, only moves: the parent of other layers (`parent: 'name'`). Animate `x y rotation scale
474
+ * scaleX scaleY skewX skewY alpha pivotX pivotY` in `initial` / `keyframes` like any layer; its children follow.
475
+ */
476
+ interface NullSequenceSpec extends SequenceCommon {
477
+ type: 'null';
478
+ }
479
+ type SequenceSpec = NullSequenceSpec | VideoSequenceSpec | ImageSequenceSpec | TextSequenceSpec | AudioSequenceSpec | CompositionSequenceSpec | CameraSequenceSpec | ShapeSequenceSpec;
456
480
  /** Top-level composition (root node) — same as `CompositionSequenceSpec` minus the discriminant. */
457
481
  interface CompositionSpec extends SequenceCommon {
458
482
  width?: number;
@@ -489,4 +513,4 @@ interface AudioDescriptor {
489
513
  }[];
490
514
  }
491
515
 
492
- export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };
516
+ export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, NullSequenceSpec as N, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };
package/docs/api.md CHANGED
@@ -288,6 +288,7 @@ interface ControllerOptions {
288
288
  canvas: HTMLCanvasElement; // required
289
289
  showExportButton?: boolean; // default true; hides ⬇ + popover
290
290
  enableKeyboardShortcuts?: boolean; // default true
291
+ clickToPlay?: boolean; // default true: a click / tap on the picture plays / pauses (like <video>); false leaves the canvas alone
291
292
  className?: string; // default 'movie-controller'
292
293
  theme?: ControllerTheme; // colours / thickness / font of the bar, see Theme
293
294
  }
package/docs/dsl.md CHANGED
@@ -171,6 +171,23 @@ Renders a video. Intrinsic `w`/`h` come from the video's natural size. `currentT
171
171
 
172
172
  Use `scale: 'cover'` or `scale: 'contain'` (these resolve via the [scope](#expressions)) to fit the video to the parent composition.
173
173
 
174
+ ### `null` and `parent`
175
+
176
+ A `null` layer draws nothing; it only moves. Any layer can name it as its `parent`, and is then drawn **inside** it: the null's position, rotation, scale, skew and alpha carry the layer along. Use it to move, turn, scale or fade a group at once, to turn something about a point (a planet and its moon, a clock hand, a hinged arm), or to build a rig.
177
+
178
+ ```js
179
+ { type: 'null', name: 'planet', initial: { x: 640, y: 360 },
180
+ keyframes: [{ at: 0, to: { rotation: 360 }, duration: 8, ease: 'none' }] },
181
+ { type: 'shape', shape: 'circle', radius: 20, parent: 'planet', initial: { x: 200, y: 0, fillColor: '#ffffff' } }, // circles the point (640, 360)
182
+ ```
183
+
184
+ - A child's `x` / `y` are measured **from the null's origin** (not from the composition's corner): with the null at (640, 360), a child at `x: 200` is drawn at 840. Rotation turns the child about the null's origin; give the null `pivotX` / `pivotY` to turn about another point.
185
+ - Nulls **chain**: a null may have a null as its `parent` (shoulder → elbow → hand). A cycle is reported and broken.
186
+ - The children are **drawn where the null stands in the list** (stack order), together, not where each is listed: to put another layer between two children, split them across two nulls. A child's own `at` / `duration` still apply, in composition time.
187
+ - The null lives for the whole composition unless it has `at` / `duration`; when it is not alive its children are not drawn.
188
+ - A **mask** on a child shares the child's space, so it follows the null as well.
189
+ - Only `null` layers can be parents (not shapes, text or images), and a `threeD` layer or a camera cannot have a parent. These cases, an unknown name and a cycle are each warned about, and the layer is drawn without a parent.
190
+
174
191
  ### `audio`
175
192
 
176
193
  Audio-only sequence. No visual. Volume is animatable via keyframes.
@@ -267,7 +284,7 @@ Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `p
267
284
  | `arc` | `radius` | `innerRadius`, `startAngle` (0), `endAngle` (360) |
268
285
  | `line` | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | `trimStart`, `trimEnd` |
269
286
  | `polygon` | `points: [[x,y], …]` | `open` (default false), `trimStart`, `trimEnd` |
270
- | `path` | `d` (SVG path data) | `trimStart`, `trimEnd` |
287
+ | `path` | `d` (SVG path data) | `trimStart`, `trimEnd`, `morphTo`, `morph`, `morphPoints` |
271
288
 
272
289
  **`arc`** is an arc around its local origin (the centre). Angles are in **degrees: 0° is 3 o'clock and positive is clockwise**, so a progress ring starts at `startAngle: -90` (12 o'clock) and animates `endAngle` from `-90` to `270`. With a stroke and no fill it is an open arc line (`strokeCap: 'round'` for rounded ends); with a fill it is a sector (a pie slice), and with `innerRadius` a ring segment (a donut slice). A sweep of 360° or more is a full circle; `endAngle < startAngle` sweeps counter-clockwise. `radius`, `innerRadius`, `startAngle` and `endAngle` are all animatable.
273
290
 
@@ -285,6 +302,14 @@ Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `p
285
302
  keyframes: [{ at: 0, to: { trimEnd: 1 }, duration: 1, ease: 'power2.inOut' }] } // a check mark drawing itself
286
303
  ```
287
304
 
305
+ **Morph (`morphTo` / `morph`).** A `path` can turn into another outline: give `morphTo` (SVG path data in the same canvas coordinates as `d`) and animate `morph` from 0 (the `d` outline) to 1 (the `morphTo` outline). In between it is drawn as a polygon of points half way from one to the other (`morphPoints`: 8–2048, default 128). Closed outlines are lined up (start point and direction) so they do not twist; sub-paths are paired in order, and an extra one grows from (or shrinks into) its own centre. Fill and stroke both follow, and `trimStart` / `trimEnd` walk the morphing outline. Write both outlines as `M … L … C … Z` in absolute coordinates (arcs and holes work too, but keep the same number of sub-paths on both sides).
306
+
307
+ ```ts
308
+ { type: 'shape', shape: 'path', d: 'M 640 160 C 780 160 860 260 860 360 C 860 470 770 560 640 560 C 510 560 420 470 420 360 C 420 250 500 160 640 160 Z',
309
+ morphTo: 'M 640 130 L 700 300 L 880 300 L 735 410 L 790 590 L 640 480 L 490 590 L 545 410 L 400 300 L 580 300 Z',
310
+ initial: { fillColor: '#ffd166' }, keyframes: [{ at: 0.5, to: { morph: 1 }, duration: 1.5, ease: 'power2.inOut' }] } // a blob turns into a star
311
+ ```
312
+
288
313
  `strokeCap` (`'butt'`, `'round'`, `'square'`) and `strokeJoin` (`'miter'`, `'round'`, `'bevel'`) work on every shape, at the top level or in `initial`; they are not animated. Sharp corners (the apex of an M in outlined text, a thin polygon) poke out with the default `miter` join: use `'round'`.
289
314
 
290
315
  **Style** is set on `initial` and animatable via keyframes:
@@ -747,8 +772,18 @@ The expression parser is in-tree (no eval, CSP-safe). See [`src/expr/Parser.ts`]
747
772
  | `sqrt(x)` | |
748
773
  | `pow(a, b)` | power |
749
774
  | `sin(x)`, `cos(x)`, `tan(x)` | radians |
775
+ | `lerp(a, b, t)` | `a + (b - a) * t` |
776
+ | `clamp(x, lo, hi)` | |
777
+ | `smoothstep(a, b, x)` | 0 below `a`, 1 above `b`, smooth in between |
778
+ | `mod(a, b)` | never negative (`mod(-1, 3)` is 2) |
779
+ | `step(edge, x)` | 0 below `edge`, 1 from `edge` on: the way to write an "if" |
780
+ | `rand(seed)` | a number in 0…1; the same seed always gives the same number |
781
+ | `noise(x, seed)` | smooth noise in −1…1, continuous in `x`; `seed` is optional |
782
+ | `PI` | a constant |
750
783
 
751
- No comparison, conditional, bitwise, or string operators — keep it numeric.
784
+ No comparison, conditional, bitwise, or string operators — keep it numeric (`step()` and `clamp()` cover most "if"s).
785
+
786
+ **Randomness is seeded.** `rand(seed)` and `noise(x, seed)` depend only on their arguments, so playback, seeking and export agree; never use `Math.random()` for anything that ends up in the picture. Expressions are still evaluated once, when the layer is built, so give each layer its own seed (in a JS loop: `x: `W/2 + rand(${i}) * 200``). For randomness in plain JS use `random(seed)` (`const r = random(7); r(); r()`), exported by the library. For a shake that changes over time use [`wiggle()`](#wiggle).
752
787
 
753
788
  ### Scope variables
754
789
 
@@ -1126,6 +1161,77 @@ sequences: [
1126
1161
 
1127
1162
  `z` is specified, so it stops following `fov`; for an orbit **plus** a dolly zoom write your own `fov` and `z = (H/2) / tan(fov/2)` keyframes.
1128
1163
 
1164
+ ### `wiggle`
1165
+
1166
+ A seeded shake as keyframes (an expression cannot change over time, so it is baked into ordinary keyframes): drift, hand-held camera, a flickering light.
1167
+
1168
+ ```ts
1169
+ import { wiggle } from 'pixi-effects';
1170
+
1171
+ { type: 'text', text: 'hi', at: 0, duration: 6, initial: { x: 'GW/2', y: 'GH/2' },
1172
+ keyframes: [
1173
+ ...wiggle({ duration: 6, freq: 4, seed: 3, props: { x: { around: 'GW/2', amp: 6 }, rotation: { around: 0, amp: 1.5 } } }),
1174
+ ] }
1175
+ ```
1176
+
1177
+ | Option | Type | Notes |
1178
+ | ------ | ---- | ----- |
1179
+ | `duration` | number | seconds; required |
1180
+ | `props` | `{ [prop]: { around, amp } }` | each property moves on its own (x and y are not in lockstep). `around` is the resting value: a number or an expression; the shake starts and ends there. `amp` is how far it strays. Any animatable name works (`rotation`, `scale`, `alpha`, `'filters.blur.blur'`). |
1181
+ | `at` | number | start, seconds from the start of the layer (default 0) |
1182
+ | `freq` | number | new random targets per second (default 3 drifts; 8 and up shakes) |
1183
+ | `seed` | number | another seed is another take (default 0) |
1184
+ | `ease` | string | between targets (default `'sine.inOut'`; `'none'` gives jittery straight lines) |
1185
+
1186
+ It returns `Keyframe[]`: spread it into `keyframes`, next to others. Do not put another keyframe on the same property during the wiggle.
1187
+
1188
+ ### `followPath`
1189
+
1190
+ A layer travelling along an SVG path, as keyframes for `x` and `y` (and `rotation`). The layer's own `x` / `y` are the points of the path (give shapes their centre there, and text `anchorX: 0.5, anchorY: 0.5`). The path is walked by arc length, so the speed is even whatever the curve, and sampled once per frame as short straight steps: set `frameRate` to the movie's and the layer is exactly on the path at every frame.
1191
+
1192
+ ```ts
1193
+ import { followPath } from 'pixi-effects';
1194
+
1195
+ { type: 'shape', shape: 'polygon', points: [[-18, -12], [18, 0], [-18, 12]], at: 0.5, duration: 4,
1196
+ initial: { fillColor: '#ffd166' },
1197
+ keyframes: followPath({ d: 'M 120 560 C 360 120 920 120 1160 560', duration: 4, ease: 'power2.inOut', orient: true, frameRate: 30 }) }
1198
+ ```
1199
+
1200
+ | Option | Notes |
1201
+ | ------ | ----- |
1202
+ | `d` | the route: SVG path data in canvas coordinates; several sub-paths are walked in order; a closed one comes back to its start |
1203
+ | `duration` | seconds; required |
1204
+ | `at` | start, seconds from the start of the layer (default 0): give the layer its own `at` so it is not drawn at the origin before the trip |
1205
+ | `ease` | GSAP ease for the progress along the path (default `'none'`: constant speed) |
1206
+ | `from` / `to` | fractions 0–1 of the path to start and stop at (default 0 → 1; `from: 1, to: 0` goes backwards) |
1207
+ | `orient` / `rotate` | `orient: true` also keyframes `rotation` (degrees) to face the way it is going, without ever jumping by a turn; `rotate` adds an offset (`-90` for an image that points up) |
1208
+ | `frameRate` | samples per second (default 30) |
1209
+
1210
+ It returns `Keyframe[]`: spread it next to other keyframes, but not another `x`, `y` or `rotation` during the trip.
1211
+
1212
+ ### `stagger`
1213
+
1214
+ Delays for a wave of items, in the style of GSAP's `stagger`. Pure and seeded, so playback and export agree.
1215
+
1216
+ ```ts
1217
+ import { stagger } from 'pixi-effects';
1218
+
1219
+ const d = stagger(6, { each: 0.08 }); // [0, 0.08, 0.16, 0.24, 0.32, 0.4] -> `at: 1 + d[i]`
1220
+ const letters = stagger(layers, { each: 0.05, from: 'center' }); // the same layers, `at` pushed back (the originals are not touched)
1221
+ const ripple = stagger(18, { each: 0.12, grid: [6, 3], from: 'center', ease: 'sine.out' });
1222
+ ```
1223
+
1224
+ | Option | Notes |
1225
+ | ------ | ----- |
1226
+ | `each` | seconds between neighbours (the farthest one waits `each` × its distance). Default 0.1. Not together with `amount`. |
1227
+ | `amount` | seconds from the first to the last, however many there are |
1228
+ | `from` | `'start'` (default), `'end'`, `'center'` (outward), `'edges'` (inward), `'random'` (a seeded shuffle of the same delays) or an item index |
1229
+ | `grid` | `[columns, rows]`: items fill the grid row by row, and the wave travels by straight-line distance (a ripple) |
1230
+ | `ease` | a GSAP ease that reshapes the spread (default `'none'`); the first stays at 0, the last at the full spread |
1231
+ | `seed` | for `from: 'random'`: another seed, another order |
1232
+
1233
+ With a layer array each layer's own `at` is kept and the delay is added to it. Keyframes inside the layers stay as they are (they count from the layer's start).
1234
+
1129
1235
  ### `withFade`
1130
1236
 
1131
1237
  Spec helper that adds alpha fade-in / fade-out to **any** sequence spec. Mutates and returns the spec, so it composes with other presets (`kenBurns`, …) and drops straight into `sequences[]`.