pixi-effects 0.26.2 → 0.27.0

package/dist/loader.css

@@ -1,7 +1,7 @@
 /*
  * pixi-effects loader: one line of HTML on the page, a few lines of CSS, no JavaScript of your own.
  *
- *   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.26.2/dist/loader.css">
+ *   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.27.0/dist/loader.css">
  *   <div class="stage" style="position: relative">                      <!-- any box the canvas sits in, with position: relative -->
  *     <canvas id="stage" width="1280" height="720"></canvas>
  *     <div class="pe-loader" data-label="LOADING"></div>                <!-- or class="pe-loader pe-loader--bar" -->

package/dist/three.cjs

@@ -1,12 +1,12 @@
 'use strict';
 
-var chunkWPXDRSGN_cjs = require('./chunk-WPXDRSGN.cjs');
-require('./chunk-ECA2WNRX.cjs');
+var chunkRQMI7EJT_cjs = require('./chunk-RQMI7EJT.cjs');
+require('./chunk-ZMAD3KJU.cjs');
 require('./chunk-TWZNOUM7.cjs');
 var pixi_js = require('pixi.js');
 var three$1 = require('three');
 
-var ThreeSequence = class extends chunkWPXDRSGN_cjs.Sequence {
+var ThreeSequence = class extends chunkRQMI7EJT_cjs.Sequence {
   _renderer = null;
   _scene = null;
   _camera = null;
@@ -25,7 +25,7 @@ var ThreeSequence = class extends chunkWPXDRSGN_cjs.Sequence {
     if (this.duration === void 0) {
       this.duration = this.parent?.duration ?? this.root.duration;
     }
-    const scope = chunkWPXDRSGN_cjs.buildScope(this, this.parent, this.root);
+    const scope = chunkRQMI7EJT_cjs.buildScope(this, this.parent, this.root);
     const width = resolveDim(spec.width, scope) ?? this.parent?.width ?? this.root.width;
     const height = resolveDim(spec.height, scope) ?? this.parent?.height ?? this.root.height;
     const resolution = spec.resolution ?? 1;
@@ -145,12 +145,12 @@ var ThreeSequence = class extends chunkWPXDRSGN_cjs.Sequence {
 function resolveDim(v, scope) {
   if (v === void 0) return void 0;
   if (typeof v === "number") return v;
-  return chunkWPXDRSGN_cjs.evaluateExpr(v, scope);
+  return chunkRQMI7EJT_cjs.evaluateExpr(v, scope);
 }
 
 // src/three/index.ts
 function registerThree() {
-  chunkWPXDRSGN_cjs.registerSequenceType("three", ThreeSequence);
+  chunkRQMI7EJT_cjs.registerSequenceType("three", ThreeSequence);
 }
 function three(spec) {
   return spec;

package/dist/three.d.cts

@@ -1,8 +1,7 @@
-import { d as SequenceCommon, O as PropValue, S as SequenceSpec } from './types-DSGwN5w1.cjs';
+import { d as SequenceCommon, O as PropValue, S as SequenceSpec } from './types-DUVefWiB.cjs';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-TbBhHPrG.cjs';
+import { S as Sequence, P as PathRouters } from './Base-DzC3i919.cjs';
 import 'pixi.js';
-import 'gsap';
 
 /** Handed to setup / update / dispose. One per three sequence. */
 interface ThreeContext {

package/dist/three.d.ts

@@ -1,8 +1,7 @@
-import { d as SequenceCommon, O as PropValue, S as SequenceSpec } from './types-DSGwN5w1.js';
+import { d as SequenceCommon, O as PropValue, S as SequenceSpec } from './types-DUVefWiB.js';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-CpdDs4HT.js';
+import { S as Sequence, P as PathRouters } from './Base-CVezIEdo.js';
 import 'pixi.js';
-import 'gsap';
 
 /** Handed to setup / update / dispose. One per three sequence. */
 interface ThreeContext {

package/dist/three.js

@@ -1,5 +1,5 @@
-import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-X3HB4DSR.js';
-import './chunk-TLYTYBWX.js';
+import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-TGJACVLD.js';
+import './chunk-45QKLD6M.js';
 import './chunk-BXOCEZ4U.js';
 import { Texture, Sprite } from 'pixi.js';
 import { WebGLRenderer, Scene, PerspectiveCamera } from 'three';

package/dist/{types-DSGwN5w1.d.ts → types-DUVefWiB.d.cts}

@@ -1,3 +1,128 @@
+type EaseFn = (p: number) => number;
+
+/**
+ * A timeline that is a pure function of time (spike: see docs/superpowers/specs/2026-10-10-pure-timeline-design.md).
+ *
+ * For every (target, property) it keeps the segments that write it, ordered by start time. The value at `t`
+ * is the value of the last segment that has started, computed from `t` alone; nothing is remembered between
+ * two calls except the start values captured when the segment was built. GSAP is the oracle: the rules below
+ * were taken from black-box probes of `gsap.timeline` and are checked against it by tests/core/pure/timelineParity.test.ts.
+ */
+interface PureVars {
+    duration?: number;
+    ease?: string | EaseFn;
+    repeat?: number;
+    yoyo?: boolean;
+    repeatDelay?: number;
+    onUpdate?: () => void;
+    /** The Pixi plugin's shorthands: `scale`, `anchor`, `rotation` (degrees), `tint`, `autoAlpha` ... */
+    pixi?: Record<string, unknown>;
+    [prop: string]: unknown;
+}
+/** One thing a timeline writes: see `segments()`. */
+interface SegmentInfo {
+    target: object;
+    /** The property (`'alpha'`, `'scale.x'`, `'fill'`). */
+    id: string;
+    start: number;
+    duration: number;
+    repeat: number;
+    yoyo: boolean;
+    repeatDelay: number;
+    kind: 'set' | 'to' | 'from' | 'fromTo';
+}
+/** A marker that only lengthens a timeline (what `gsap.to({}, { duration })` is used for). */
+interface Spacer {
+    readonly spacer: true;
+    readonly duration: number;
+}
+declare class PureTimeline {
+    private readonly defaultEase;
+    private readonly channels;
+    private readonly channelList;
+    private readonly children;
+    private spans;
+    private now;
+    private order;
+    private killed;
+    private prepared;
+    constructor(opts?: {
+        paused?: boolean;
+        defaults?: {
+            ease?: string | EaseFn;
+        };
+    });
+    /** Adds a child timeline (played with its local time) or a spacer that lengthens this one. */
+    add(child: PureTimeline | Spacer, at?: number): this;
+    set(target: object, vars: PureVars, at?: number): this;
+    to(target: object, vars: PureVars, at?: number): this;
+    from(target: object, vars: PureVars, at?: number): this;
+    fromTo(target: object, fromVars: PureVars, toVars: PureVars, at?: number): this;
+    private build;
+    private channel;
+    /**
+     * A property moved by a function of the caller (a colour in OKLab, a gradient): `to` and `from` say how to get the two ends from
+     * the value before the segment, `make` the interpolator between them. The value is only written while the segment is the last
+     * one that has started, so nothing is read or kept between two frames.
+     */
+    tweenValue<T>(spec: {
+        holder: object;
+        id: string;
+        get(): T;
+        set(v: T): void;
+        from?: (prev: T) => T;
+        to: (start: T, prev: T, base: T) => T;
+        make: (a: T, b: T) => (p: number) => T;
+        duration: number;
+        ease: string | EaseFn;
+        at: number;
+        repeat?: number;
+        yoyo?: boolean;
+        repeatDelay?: number;
+    }): this;
+    /**
+     * A write that is undone when time goes back before it: the property is `value` from `at` on, and what it was before otherwise.
+     * `holder` and `id` name the property, so a set and the tweens of the same property are one channel; `write` is the way the caller
+     * writes it (it may do more than assign: redraw), and runs again whenever this set is what the property shows.
+     */
+    setValue<T>(holder: object, id: string, at: number, read: () => T, write: (v: T) => void, value: T): this;
+    /** What the timeline will write, for tools and tests: every segment of this timeline and of the ones under it, starts in this timeline's time. */
+    segments(offset?: number): SegmentInfo[];
+    /** How many timelines are directly under this one. */
+    timelines(): number;
+    duration(): number;
+    time(): number;
+    time(value: number): this;
+    /** GSAP's name for `time(t)`. */
+    seek(t: number): this;
+    progress(): number;
+    progress(p: number): this;
+    kill(): void;
+    /**
+     * What GSAP ended up with once it had been played to the end and back (what Movie used to do at build), as rules that depend
+     * on the segments of a property only:
+     * - a `from` / `fromTo` shows its start from the moment it is built, so a `to` that comes first starts at the start of the
+     *   `from` built last, else at the property's own value;
+     * - a `to` (and a `set`) starts where the segment before it ended;
+     * - a `from` ends where the segment before it ended, or, with none before, where the property was when it was built;
+     * - before the first segment the property shows that segment's start.
+     */
+    private prepare;
+    /** Every channel of this timeline and of its children reads the property it starts from before any of them writes. */
+    private prepareDeep;
+    /** How many channels write each (target, property) in this timeline and everything under it. */
+    private countChannels;
+    private isExclusive;
+    private markExclusive;
+    private evaluate;
+}
+
+/**
+ * The timeline of the library and the few things around it: a timeline is a pure function of time (a value at a time is computed from the
+ * script and the time alone, never from the way the playhead came), see docs/superpowers/specs/2026-10-10-pure-timeline-design.md.
+ */
+type Timeline = PureTimeline;
+
 /** What an author writes in `composition.stops`: a time in seconds, or an object. */
 interface StopSpec {
     /** Where playback stops, in seconds (negative counts back from the end). */
@@ -146,7 +271,7 @@ interface TransitionCommon {
     at: number;
     /** Length of the transition in seconds. Must be > 0. */
     duration: number;
-    /** GSAP easing name. Default `'none'` (linear). */
+    /** Ease name (`'power2.out'`, `'back.out(1.7)'`, `'spring.bouncy'`, `'cubic-bezier(.4,0,.2,1)'`, `'steps(8)'`). Default `'none'` (linear). */
     ease?: string;
 }
 interface CrossfadeTransition extends TransitionCommon {
@@ -591,7 +716,7 @@ interface ShapeBase extends SequenceCommon {
     /**
      * Colour space used to interpolate `fillColor` / `strokeColor` keyframes.
      *
-     * - `'rgb'` (default): linear RGB tween via `gsap.utils.interpolate`.
+     * - `'rgb'` (default): a straight lerp of the red, green and blue channels.
      *   Fast, but a red → green ramp passes through muddy brown / olive
      *   greys at the midpoint because intermediate sRGB values are
      *   perceptually unbalanced.
@@ -743,4 +868,4 @@ interface AudioDescriptor {
     sourceMap?: (u: number) => number;
 }
 
-export { type StopSpec as $, type ArcShapeSpec as A, type BlendModeName as B, type CompositionShape as C, type DipTransition as D, type EllipseShapeSpec as E, type FilterSpec as F, type GradientSpec as G, type PathShapeSpec as H, type ImageSequenceSpec as I, type PolygonShapeSpec as J, type Keyframe as K, type LightSequenceSpec as L, type MusicOptions as M, type NullSequenceSpec as N, type PropValue as O, type Props as P, type SfxKnobs as Q, type RectShapeSpec as R, type SequenceSpec as S, type TextSequenceSpec as T, type SfxOptions as U, type SfxPreset as V, type SfxVoice as W, type ShaderSequenceSpec as X, type ShapeSequenceSpec as Y, type SlideTransition as Z, type Stop as _, type CameraSequenceSpec as a, type TransitionCommon as a0, type VideoSequenceSpec as a1, type WipeTransition as a2, type ZoomTransition as a3, normalizeStops as a4, pictureStops as a5, type AudioDescriptor as a6, type TransitionSpec as b, type CompositionSpec as c, type SequenceCommon as d, type AssetSpec as e, type AudioAssetSpec as f, type AudioMusicSpec as g, type AudioSequenceSpec as h, type AudioSfxSpec as i, type ChromaKeyFilterSpec as j, type CircleShapeSpec as k, type CompositionSequenceSpec as l, type CrossfadeTransition as m, type CustomFilterSpec as n, type DissolveTransition as o, type Expr as p, type IrisTransition as q, type LineShapeSpec as r, type LumaTransition as s, type MaskRefSpec as t, type MatteRefSpec as u, type MusicDrum as v, type MusicDrums as w, type MusicInstrument as x, type MusicLevel as y, type MusicTrack as z };
+export { type StopSpec as $, type ArcShapeSpec as A, type BlendModeName as B, type CompositionShape as C, type DipTransition as D, type EllipseShapeSpec as E, type FilterSpec as F, type GradientSpec as G, type PathShapeSpec as H, type ImageSequenceSpec as I, type PolygonShapeSpec as J, type Keyframe as K, type LightSequenceSpec as L, type MusicOptions as M, type NullSequenceSpec as N, type PropValue as O, type Props as P, type SfxKnobs as Q, type RectShapeSpec as R, type SequenceSpec as S, type TextSequenceSpec as T, type SfxOptions as U, type SfxPreset as V, type SfxVoice as W, type ShaderSequenceSpec as X, type ShapeSequenceSpec as Y, type SlideTransition as Z, type Stop as _, type CameraSequenceSpec as a, type TransitionCommon as a0, type VideoSequenceSpec as a1, type WipeTransition as a2, type ZoomTransition as a3, normalizeStops as a4, pictureStops as a5, type Timeline as a6, type AudioDescriptor as a7, type TransitionSpec as b, type CompositionSpec as c, type SequenceCommon as d, type AssetSpec as e, type AudioAssetSpec as f, type AudioMusicSpec as g, type AudioSequenceSpec as h, type AudioSfxSpec as i, type ChromaKeyFilterSpec as j, type CircleShapeSpec as k, type CompositionSequenceSpec as l, type CrossfadeTransition as m, type CustomFilterSpec as n, type DissolveTransition as o, type Expr as p, type IrisTransition as q, type LineShapeSpec as r, type LumaTransition as s, type MaskRefSpec as t, type MatteRefSpec as u, type MusicDrum as v, type MusicDrums as w, type MusicInstrument as x, type MusicLevel as y, type MusicTrack as z };

package/dist/{types-DSGwN5w1.d.cts → types-DUVefWiB.d.ts}

@@ -1,3 +1,128 @@
+type EaseFn = (p: number) => number;
+
+/**
+ * A timeline that is a pure function of time (spike: see docs/superpowers/specs/2026-10-10-pure-timeline-design.md).
+ *
+ * For every (target, property) it keeps the segments that write it, ordered by start time. The value at `t`
+ * is the value of the last segment that has started, computed from `t` alone; nothing is remembered between
+ * two calls except the start values captured when the segment was built. GSAP is the oracle: the rules below
+ * were taken from black-box probes of `gsap.timeline` and are checked against it by tests/core/pure/timelineParity.test.ts.
+ */
+interface PureVars {
+    duration?: number;
+    ease?: string | EaseFn;
+    repeat?: number;
+    yoyo?: boolean;
+    repeatDelay?: number;
+    onUpdate?: () => void;
+    /** The Pixi plugin's shorthands: `scale`, `anchor`, `rotation` (degrees), `tint`, `autoAlpha` ... */
+    pixi?: Record<string, unknown>;
+    [prop: string]: unknown;
+}
+/** One thing a timeline writes: see `segments()`. */
+interface SegmentInfo {
+    target: object;
+    /** The property (`'alpha'`, `'scale.x'`, `'fill'`). */
+    id: string;
+    start: number;
+    duration: number;
+    repeat: number;
+    yoyo: boolean;
+    repeatDelay: number;
+    kind: 'set' | 'to' | 'from' | 'fromTo';
+}
+/** A marker that only lengthens a timeline (what `gsap.to({}, { duration })` is used for). */
+interface Spacer {
+    readonly spacer: true;
+    readonly duration: number;
+}
+declare class PureTimeline {
+    private readonly defaultEase;
+    private readonly channels;
+    private readonly channelList;
+    private readonly children;
+    private spans;
+    private now;
+    private order;
+    private killed;
+    private prepared;
+    constructor(opts?: {
+        paused?: boolean;
+        defaults?: {
+            ease?: string | EaseFn;
+        };
+    });
+    /** Adds a child timeline (played with its local time) or a spacer that lengthens this one. */
+    add(child: PureTimeline | Spacer, at?: number): this;
+    set(target: object, vars: PureVars, at?: number): this;
+    to(target: object, vars: PureVars, at?: number): this;
+    from(target: object, vars: PureVars, at?: number): this;
+    fromTo(target: object, fromVars: PureVars, toVars: PureVars, at?: number): this;
+    private build;
+    private channel;
+    /**
+     * A property moved by a function of the caller (a colour in OKLab, a gradient): `to` and `from` say how to get the two ends from
+     * the value before the segment, `make` the interpolator between them. The value is only written while the segment is the last
+     * one that has started, so nothing is read or kept between two frames.
+     */
+    tweenValue<T>(spec: {
+        holder: object;
+        id: string;
+        get(): T;
+        set(v: T): void;
+        from?: (prev: T) => T;
+        to: (start: T, prev: T, base: T) => T;
+        make: (a: T, b: T) => (p: number) => T;
+        duration: number;
+        ease: string | EaseFn;
+        at: number;
+        repeat?: number;
+        yoyo?: boolean;
+        repeatDelay?: number;
+    }): this;
+    /**
+     * A write that is undone when time goes back before it: the property is `value` from `at` on, and what it was before otherwise.
+     * `holder` and `id` name the property, so a set and the tweens of the same property are one channel; `write` is the way the caller
+     * writes it (it may do more than assign: redraw), and runs again whenever this set is what the property shows.
+     */
+    setValue<T>(holder: object, id: string, at: number, read: () => T, write: (v: T) => void, value: T): this;
+    /** What the timeline will write, for tools and tests: every segment of this timeline and of the ones under it, starts in this timeline's time. */
+    segments(offset?: number): SegmentInfo[];
+    /** How many timelines are directly under this one. */
+    timelines(): number;
+    duration(): number;
+    time(): number;
+    time(value: number): this;
+    /** GSAP's name for `time(t)`. */
+    seek(t: number): this;
+    progress(): number;
+    progress(p: number): this;
+    kill(): void;
+    /**
+     * What GSAP ended up with once it had been played to the end and back (what Movie used to do at build), as rules that depend
+     * on the segments of a property only:
+     * - a `from` / `fromTo` shows its start from the moment it is built, so a `to` that comes first starts at the start of the
+     *   `from` built last, else at the property's own value;
+     * - a `to` (and a `set`) starts where the segment before it ended;
+     * - a `from` ends where the segment before it ended, or, with none before, where the property was when it was built;
+     * - before the first segment the property shows that segment's start.
+     */
+    private prepare;
+    /** Every channel of this timeline and of its children reads the property it starts from before any of them writes. */
+    private prepareDeep;
+    /** How many channels write each (target, property) in this timeline and everything under it. */
+    private countChannels;
+    private isExclusive;
+    private markExclusive;
+    private evaluate;
+}
+
+/**
+ * The timeline of the library and the few things around it: a timeline is a pure function of time (a value at a time is computed from the
+ * script and the time alone, never from the way the playhead came), see docs/superpowers/specs/2026-10-10-pure-timeline-design.md.
+ */
+type Timeline = PureTimeline;
+
 /** What an author writes in `composition.stops`: a time in seconds, or an object. */
 interface StopSpec {
     /** Where playback stops, in seconds (negative counts back from the end). */
@@ -146,7 +271,7 @@ interface TransitionCommon {
     at: number;
     /** Length of the transition in seconds. Must be > 0. */
     duration: number;
-    /** GSAP easing name. Default `'none'` (linear). */
+    /** Ease name (`'power2.out'`, `'back.out(1.7)'`, `'spring.bouncy'`, `'cubic-bezier(.4,0,.2,1)'`, `'steps(8)'`). Default `'none'` (linear). */
     ease?: string;
 }
 interface CrossfadeTransition extends TransitionCommon {
@@ -591,7 +716,7 @@ interface ShapeBase extends SequenceCommon {
     /**
      * Colour space used to interpolate `fillColor` / `strokeColor` keyframes.
      *
-     * - `'rgb'` (default): linear RGB tween via `gsap.utils.interpolate`.
+     * - `'rgb'` (default): a straight lerp of the red, green and blue channels.
      *   Fast, but a red → green ramp passes through muddy brown / olive
      *   greys at the midpoint because intermediate sRGB values are
      *   perceptually unbalanced.
@@ -743,4 +868,4 @@ interface AudioDescriptor {
     sourceMap?: (u: number) => number;
 }
 
-export { type StopSpec as $, type ArcShapeSpec as A, type BlendModeName as B, type CompositionShape as C, type DipTransition as D, type EllipseShapeSpec as E, type FilterSpec as F, type GradientSpec as G, type PathShapeSpec as H, type ImageSequenceSpec as I, type PolygonShapeSpec as J, type Keyframe as K, type LightSequenceSpec as L, type MusicOptions as M, type NullSequenceSpec as N, type PropValue as O, type Props as P, type SfxKnobs as Q, type RectShapeSpec as R, type SequenceSpec as S, type TextSequenceSpec as T, type SfxOptions as U, type SfxPreset as V, type SfxVoice as W, type ShaderSequenceSpec as X, type ShapeSequenceSpec as Y, type SlideTransition as Z, type Stop as _, type CameraSequenceSpec as a, type TransitionCommon as a0, type VideoSequenceSpec as a1, type WipeTransition as a2, type ZoomTransition as a3, normalizeStops as a4, pictureStops as a5, type AudioDescriptor as a6, type TransitionSpec as b, type CompositionSpec as c, type SequenceCommon as d, type AssetSpec as e, type AudioAssetSpec as f, type AudioMusicSpec as g, type AudioSequenceSpec as h, type AudioSfxSpec as i, type ChromaKeyFilterSpec as j, type CircleShapeSpec as k, type CompositionSequenceSpec as l, type CrossfadeTransition as m, type CustomFilterSpec as n, type DissolveTransition as o, type Expr as p, type IrisTransition as q, type LineShapeSpec as r, type LumaTransition as s, type MaskRefSpec as t, type MatteRefSpec as u, type MusicDrum as v, type MusicDrums as w, type MusicInstrument as x, type MusicLevel as y, type MusicTrack as z };
+export { type StopSpec as $, type ArcShapeSpec as A, type BlendModeName as B, type CompositionShape as C, type DipTransition as D, type EllipseShapeSpec as E, type FilterSpec as F, type GradientSpec as G, type PathShapeSpec as H, type ImageSequenceSpec as I, type PolygonShapeSpec as J, type Keyframe as K, type LightSequenceSpec as L, type MusicOptions as M, type NullSequenceSpec as N, type PropValue as O, type Props as P, type SfxKnobs as Q, type RectShapeSpec as R, type SequenceSpec as S, type TextSequenceSpec as T, type SfxOptions as U, type SfxPreset as V, type SfxVoice as W, type ShaderSequenceSpec as X, type ShapeSequenceSpec as Y, type SlideTransition as Z, type Stop as _, type CameraSequenceSpec as a, type TransitionCommon as a0, type VideoSequenceSpec as a1, type WipeTransition as a2, type ZoomTransition as a3, normalizeStops as a4, pictureStops as a5, type Timeline as a6, type AudioDescriptor as a7, type TransitionSpec as b, type CompositionSpec as c, type SequenceCommon as d, type AssetSpec as e, type AudioAssetSpec as f, type AudioMusicSpec as g, type AudioSequenceSpec as h, type AudioSfxSpec as i, type ChromaKeyFilterSpec as j, type CircleShapeSpec as k, type CompositionSequenceSpec as l, type CrossfadeTransition as m, type CustomFilterSpec as n, type DissolveTransition as o, type Expr as p, type IrisTransition as q, type LineShapeSpec as r, type LumaTransition as s, type MaskRefSpec as t, type MatteRefSpec as u, type MusicDrum as v, type MusicDrums as w, type MusicInstrument as x, type MusicLevel as y, type MusicTrack as z };

package/docs/api.md

@@ -155,14 +155,16 @@ Renders the entire timeline to a single video file. Pauses playback first.
 
 ```ts
 interface RenderOptions {
-  format?: 'mp4' | 'mov' | 'webm' | 'mkv';   // default 'mp4'
+  format?: 'mp4' | 'mov' | 'webm' | 'mkv' | 'wav' | 'ogg';   // default 'mp4'; wav / ogg: ONLY the movie's sound (an error when it has none)
   video?: {
-    codec?:   string;   // default per format (mp4/mov→avc, webm/mkv→vp9)
-    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';   // default 'high'
+    codec?:   string;   // 'avc' (H.264) | 'hevc' | 'vp9' | 'av1' | 'vp8'; default per format (mp4/mov→avc, webm→vp9, mkv→vp9)
+    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high' | number | string;   // default 'high'; or bits a second: 8_000_000, '8M', '800k'
+    hardware?: 'no-preference' | 'prefer-hardware' | 'prefer-software';   // where to encode (default 'no-preference')
+    keyFrameInterval?: number;   // seconds between keyframes (default 2): shorter seeks faster, a bigger file
   };
   audio?: {
-    codec?:   string;   // default per format (mp4/mov→aac, webm/mkv→opus)
-    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';   // default 'high'
+    codec?:   string;   // default per format (mp4/mov→aac, webm/mkv/ogg→opus, wav→pcm-s16)
+    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high' | number | string;   // default 'high' (not for wav: it is not compressed)
   };
   motionBlur?: boolean | number | { samples?: number; shutter?: number };   // overrides movie.init's; false turns it off
 }
@@ -177,6 +179,10 @@ interface RenderOptions {
 - After a blurred snapshot, contact sheet or render the playhead and the stage are on an exact frame again, not a sample.
 - `pixi-effects-render --motion-blur 8 [--shutter 0.5]` sets it for one file.
 
+**Video codec:** unless you name `video.codec`, the usual one for the format is used (mp4 / mov: `avc`; webm: `vp9`); if this browser cannot encode it, the next that works is used and a warning says so. A codec you name is never swapped: it is used, or the error names the one that would work (`"av1" ... "avc" would work: render({ format: 'mp4', video: { codec: 'avc' } })`). `hevc` and `av1` make smaller files at the same quality but play in fewer places than `avc`; `hardware: 'prefer-hardware'` asks the GPU's encoder.
+
+**Sound only:** `render({ format: 'wav' })` (16-bit PCM, no loss) or `render({ format: 'ogg' })` (Opus) writes the movie's mixed sound without drawing a frame: a tune written as `music` becomes an audio file. `range` cuts it like a video. `pixi-effects render page.html -o mix.wav` does the same from a script. `mp3` and `flac` are not offered: browsers cannot encode them.
+
 **Audio codec fallback:** unless you name `audio.codec`, the first codec this browser can actually encode is used (mp4: `aac`, then `opus`, `mp3`, `flac`; webm: `opus`, `vorbis`). Chrome on Linux has no AAC encoder, so there an mp4 with sound carries Opus and a warning says so (before, the export failed with a message about encoder configurations). A codec you name is never swapped: if it cannot be encoded the error says which one would work.
 
 Returns a `Blob` whose `type` is the container's MIME (e.g. `video/mp4`). Emits `'progress'` repeatedly during the render.
@@ -205,6 +211,10 @@ The whole movie as rows on a time axis, for a person to read at a glance. `timel
 
 `movie.timelineSvg()` is the chart alone (one `<svg>`, geometry in `data-*` attributes, each row `<g class="row" data-start>`): `pixi-effects-view` puts a playhead on it and turns a click into a seek.
 
+### `ease(name): (p: number) => number`
+
+The function behind an ease name (`ease('power2.out')(0.5)`, `ease('spring.bouncy')`, `ease('cubic-bezier(.4, 0, .2, 1)')`), for a preset or a check of your own. A name nobody knows warns once and runs as `power1.out`.
+
 ### `movie.destroy(): Promise<void>`
 
 Pauses playback, destroys the underlying PIXI Application, releases audio buffers and AudioContext, and marks the instance unusable.
@@ -248,7 +258,7 @@ The names are the ones an HTML5 `<video>` uses, so a player written for `<video>
 | `volume`         | number    | 0..1 getter/setter; immediate. Setter clamps and applies to active audio |
 | `muted`          | boolean   | getter/setter; immediate                                |
 | `app`            | `pixi.js Application \| null` | PIXI Application instance (advanced/escape hatch) |
-| `timeline`       | GSAP Timeline `\| null`         | underlying GSAP timeline (advanced)              |
+| `timeline`       | `Timeline \| null`              | the movie's timeline (advanced): `time(t)`, `duration()`, `segments()` |
 | `stops`          | `Stop[]`  | the composition's stops (see Presentations); empty for an ordinary movie |
 | `stopIndex`, `pageIndex`, `pageCount`, `currentStop` | number, number, number, `Stop \| null` | where the playhead is among the stops and pages (`-1` / `null` before the first stop) |
 

package/docs/dsl.md

@@ -401,7 +401,7 @@ Fill a shape with a gradient instead of `fillColor` (top level or in `initial`).
 
 #### `colorSpace`
 
-Per-shape choice of how colour keyframes are interpolated. Default `'rgb'` (linear sRGB lerp via `gsap.utils.interpolate`) is fast but classic — a red → green ramp passes through muddy olive at the midpoint. The two perceptually uniform options keep saturation through the transition:
+Per-shape choice of how colour keyframes are interpolated. Default `'rgb'` (a straight lerp of the red, green and blue channels) is fast but classic — a red → green ramp passes through muddy olive at the midpoint. The two perceptually uniform options keep saturation through the transition:
 
 | Value     | Behaviour                                                                                         |
 |-----------|---------------------------------------------------------------------------------------------------|
@@ -924,7 +924,7 @@ Supported formats are whatever PixiJS Assets and the browser's audio/video decod
 interface Keyframe {
   at?: number;       // start, in seconds from the start of THIS sequence; negative = back from the sequence's end (-0.5 = 0.5 s before it ends)
   duration?: number | 'auto'; // seconds (default 0 — instantaneous); 'auto' = the time a spring ease takes to settle
-  ease?: string;     // GSAP easing name (default 'none'), or a spring: 'spring(mass, stiffness, damping)', 'spring.gentle|snappy|bouncy|wobbly|slow'
+  ease?: string;     // Ease name (default 'none'), or a spring: 'spring(mass, stiffness, damping)', 'spring.gentle|snappy|bouncy|wobbly|slow'
   set?:  Props;      // jump to these values at `at`
   to?:   Props;      // animate from current to these values over `duration`
   from?: Props;      // animate from these values to current
@@ -932,6 +932,8 @@ interface Keyframe {
 }
 ```
 
+**Relative values.** A number in `to`, `from` or `set` may be written `'+=36'` or `'-=36'`: it is measured from where the property stands when the keyframe starts (the way GSAP writes them), and the right side is an expression (`'-=GW*0.1'`). `from: { x: '-=36' }` starts 36 px to the left of where the layer is and arrives there (the usual slide-in); `to: { y: '+=40' }` moves 40 px further. Several keyframes one after another stack, whatever order you seek in; with `repeat` the same move plays again from the same start (it does not stack). A relative value in `initial`, a style, or the start side of a `from` + `to` keyframe has nothing to be measured from: it warns and is read as the number.
+
 The four kinds are mutually exclusive per keyframe:
 
 - **`set`** — instantaneous property assignment at `at`.
@@ -994,13 +996,13 @@ If `at < 0`, it's interpreted as `duration + at` — measured back from the end
 
 ### Easing
 
-`'cubic-bezier(x1, y1, x2, y2)'` is the CSS curve exactly (x1 and x2 between 0 and 1, y1 and y2 may overshoot): `'cubic-bezier(.4, 0, .2, 1)'` is a gentle in-out, `'cubic-bezier(.2, .8, .2, 1)'` is front-loaded, not slow motion (half of the change in the first 13 % of the time, 99 % by 74 %, then a long settle). GSAP's `power2` is a cubic: `power2.in` has done only 12.5 % at half time. A malformed one warns once and runs as `'none'`.
+`'cubic-bezier(x1, y1, x2, y2)'` is the CSS curve exactly (x1 and x2 between 0 and 1, y1 and y2 may overshoot): `'cubic-bezier(.4, 0, .2, 1)'` is a gentle in-out, `'cubic-bezier(.2, .8, .2, 1)'` is front-loaded, not slow motion (half of the change in the first 13 % of the time, 99 % by 74 %, then a long settle). `power2` is a cubic: `power2.in` has done only 12.5 % at half time. A malformed one warns once and runs as `'none'`.
 
-Standard GSAP easing strings: `'none'`, `'linear'`, `'power1.in'` ... `'power4.inOut'`, `'sine.in/out/inOut'`, `'expo.in/out/inOut'`, `'circ.in/out/inOut'`, `'back.in/out/inOut(overshoot)'`, `'elastic.in/out/inOut(amplitude, period)'`, `'bounce.in/out/inOut'`. See [GSAP easing docs](https://gsap.com/docs/v3/Eases/).
+Ease strings (the names GSAP made familiar): `'none'`, `'linear'`, `'power1.in'` ... `'power4.inOut'`, `'sine.in/out/inOut'`, `'expo.in/out/inOut'`, `'circ.in/out/inOut'`, `'back.in/out/inOut(overshoot)'`, `'elastic.in/out/inOut(amplitude, period)'`, `'bounce.in/out/inOut'`. `'steps(n)'` is n equal steps.
 
 ### PIXI shorthands
 
-These keys are auto-routed through GSAP's PixiPlugin when used in `initial` / `set` / `to` / `from` / `keyframes`:
+These keys are shorthands the timeline understands when used in `initial` / `set` / `to` / `from` / `keyframes`:
 
 ```
 scale, scaleX, scaleY
@@ -1011,12 +1013,10 @@ position, positionX, positionY
 tilePosition, tilePositionX, tilePositionY
 tileScale, tileScaleX, tileScaleY
 tint, autoAlpha
-colorize, colorizeAmount, colorMatrixFilter
-blur, blurX, blurY, blurPadding
-lineColor, lineAlpha, fillColor, fillAlpha
+fillColor, fillAlpha                 (a shape's own colour keys)
 ```
 
-(In addition to plain DisplayObject props like `x`, `y`, `rotation`, `alpha`, `width`, `height`, `visible`.) **Angles are in degrees**: `rotation`, `skew` / `skewX` / `skewY` (PixiPlugin converts them), and `rotationX` / `rotationY` for 3D layers.
+(In addition to plain DisplayObject props like `x`, `y`, `rotation`, `alpha`, `width`, `height`, `visible`.) `blur`, `colorize` and the other colour-matrix shorthands of GSAP's PixiPlugin are gone: use a named filter and animate `filters.<name>.<prop>` (below). **Angles are in degrees**: `rotation`, `skew` / `skewX` / `skewY`, and `rotationX` / `rotationY` for 3D layers.
 
 ### Filter keyframe paths
 
@@ -1143,7 +1143,7 @@ Common fields (`TransitionCommon`):
 | `to`       | string  | sibling sequence's `name`. Must be declared **after** `from` in `sequences[]`.         |
 | `at`       | number  | start of the transition, in the **parent composition's** time (like a sequence's `at`, not sequence-local); negative = back from the parent's end. |
 | `duration` | number  | seconds, must be > 0.                                                                  |
-| `ease`     | string? | GSAP easing name. Default `'none'` (linear).                                           |
+| `ease`     | string? | Ease name. Default `'none'` (linear).                                           |
 
 Validation runs at composition build time. Errors throw with the offending `transitions[<index>]` quoted in the message: missing names, `to` before `from`, transition window outside either sequence's lifespan, duplicate use of one sequence as `from`, `from === to`, `duration <= 0`.
 
@@ -1410,7 +1410,7 @@ The image is centred on the canvas; `fit` (default `'cover'`) controls how the t
 | `name?`    | string                | sequence name so transitions can reference it                                        |
 | `at?`      | number                | start time, parent-relative seconds                                                  |
 | `fit?`     | `'cover'` \| `'contain'` | how the texture fills the canvas. Default `'cover'`.                              |
-| `ease?`    | string                | GSAP easing name. Default `'sine.inOut'`.                                            |
+| `ease?`    | string                | Ease name. Default `'sine.inOut'`.                                            |
 
 #### `motion: 'still'`
 
@@ -1546,7 +1546,7 @@ import { cameraPath, wiggle } from 'pixi-effects';
 | `points` | `[[x, y, z], …]`, at least two, the route in order |
 | `duration` | seconds; required |
 | `at` | start, seconds from the start of the camera layer (default 0) |
-| `ease` | GSAP ease for the progress along the route (default `'none'`: constant speed; `'power2.in'` an accelerating rush) |
+| `ease` | Ease for the progress along the route (default `'none'`: constant speed; `'power2.in'` an accelerating rush) |
 | `look` | `'ahead'` (default: face where it flies) or a fixed `[x, y, z]` |
 | `lookAhead` | with `'ahead'`: how far ahead, as a fraction 0–1 of the route (default 0.08); past the end it continues along the last direction |
 | `smooth` | `true` (default): a smooth curve through the points (Catmull-Rom); `false`: straight lines |
@@ -1572,7 +1572,7 @@ import { followPath } from 'pixi-effects';
 | `d` | the route: SVG path data in canvas coordinates; several sub-paths are walked in order; a closed one comes back to its start |
 | `duration` | seconds; required |
 | `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 |
-| `ease` | GSAP ease for the progress along the path (default `'none'`: constant speed) |
+| `ease` | Ease for the progress along the path (default `'none'`: constant speed) |
 | `from` / `to` | fractions 0–1 of the path to start and stop at (default 0 → 1; `from: 1, to: 0` goes backwards) |
 | `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) |
 | `frameRate` | samples per second (default 30) |
@@ -1641,7 +1641,7 @@ const ripple = stagger(18, { each: 0.12, grid: [6, 3], from: 'center', ease: 'si
 | `amount` | seconds from the first to the last, however many there are |
 | `from` | `'start'` (default), `'end'`, `'center'` (outward), `'edges'` (inward), `'random'` (a seeded shuffle of the same delays) or an item index |
 | `grid` | `[columns, rows]`: items fill the grid row by row, and the wave travels by straight-line distance (a ripple) |
-| `ease` | a GSAP ease that reshapes the spread (default `'none'`); the first stays at 0, the last at the full spread |
+| `ease` | an ease that reshapes the spread (default `'none'`); the first stays at 0, the last at the full spread |
 | `seed` | for `from: 'random'`: another seed, another order |
 
 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).