pixi-effects 0.28.2 → 0.29.0

package/dist/{Movie-CHcM8HNB.d.ts → Movie-C2rZFkrO.d.ts}

@@ -1,5 +1,204 @@
 import { Application } from 'pixi.js';
-import { O as MusicSummary, ac as Timeline, a4 as Stop, f as AssetSpec, d as CompositionSpec } from './types-DpK1vwcl.js';
+import { Z as Stop, c as AssetSpec, k as CompositionSpec } from './types-BzIB65Vk.js';
+
+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;
+
+/** One note or chord of a track, as a score reader sees it. */
+interface MusicNote {
+    /** Where it starts: beats from the start, and the same moment in seconds (the tempo map applied; swing and humanize are not). */
+    beat: number;
+    time: number;
+    /** How long it is held, in beats and in seconds. */
+    duration: number;
+    seconds: number;
+    /** The bar it starts in (1-based, from `meter`) and its beat inside that bar (1 = the downbeat, 1.5 = the "and" of 1). */
+    bar: number;
+    beatInBar: number;
+    /** The audible MIDI notes (`music.transpose` and the track's `transpose` are in). */
+    midi: number[];
+    /** What the score called it: `Am7`, `c4`, `[c4 e4 g4]`. */
+    name: string;
+    /** More than one note at once. */
+    chord: boolean;
+    /** 0–1 (0.8 normal, 1 accented with `!`, 0.55 soft with `,`). */
+    velocity: number;
+}
+interface MusicTrackEvents {
+    inst: string;
+    /** The track's length in beats and in bars (not a whole number when a bar is short: that is what to look for). */
+    beats: number;
+    bars: number;
+    notes: MusicNote[];
+}
+interface MusicDrumHit {
+    beat: number;
+    time: number;
+    bar: number;
+    beatInBar: number;
+    velocity: number;
+}
+interface MusicDrumEvents {
+    kind: string;
+    hits: MusicDrumHit[];
+}
+interface MusicEvents {
+    /** The tempo at the start. */
+    bpm: number;
+    meter: number;
+    beats: number;
+    bars: number;
+    /** The music without its reverb tail. */
+    seconds: number;
+    tracks: MusicTrackEvents[];
+    /** Every drum that is hit, over all sections, with every hit written out. */
+    drums: MusicDrumEvents[];
+}
+/** What the `check` tool prints about a music layer: lengths in bars (a short track shows), what starts in each bar, where the drums play. */
+interface MusicSummary {
+    bpm: number;
+    meter: number;
+    /** The score set `meter`; when false 4 is only assumed. */
+    meterSet: boolean;
+    beats: number;
+    bars: number;
+    seconds: number;
+    tail: number;
+    tracks: Array<{
+        inst: string;
+        beats: number;
+        bars: number;
+        events: number;
+        perBar: string[];
+    }>;
+    drums: Array<{
+        from: number;
+        to: number;
+        kinds: string[];
+    }>;
+}
 
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */
@@ -323,34 +522,10 @@ interface SnapshotOptions {
     scale?: number;
     /** `'image/png'` (default) or `'image/jpeg'`. */
     type?: 'image/png' | 'image/jpeg';
-    /** Return a `data:` URL string instead of a Blob (handy for scripts that can only return text). */
-    as?: 'blob' | 'dataURL';
-}
-/** One picture of a stop (see `movie.stopImages()`). */
-interface StopImage {
-    stop: Stop; /** The page it belongs to (0-based). */
-    page: number;
-    image: Blob | string;
-}
-interface StopImagesOptions {
-    /** One picture per page (default) or one per stop. */
-    which?: 'pages' | 'stops';
-    /** With `which: 'pages'`: the page's last stop (default: the page fully built) or its first. */
-    pick?: 'last' | 'first';
-    /** Output size relative to the canvas. Default 1. */
-    scale?: number;
-    /** `'image/png'` (default) or `'image/jpeg'`. */
-    type?: 'image/png' | 'image/jpeg';
-    /** JPEG quality, 0–1. */
+    /** JPEG quality, 0 to 1 (the encoder's default when left out). */
     quality?: number;
-    /** Return `data:` URLs instead of Blobs. */
-    as?: 'blob' | 'dataURL';
-    /** Motion blur for the pictures (off unless you ask: they are usually for looking at). */
-    motionBlur?: MotionBlurSpec;
-    /** Pictures for a PDF: stops flagged `pdf: false` are left out (a page whose stops are all flagged has no picture). `exportPDF` sets it. */
-    pdf?: boolean;
-    /** Called as each picture is ready, in order. */
-    onImage?: (image: StopImage) => void;
+    /** Return a `data:` URL string instead of a Blob (handy for scripts that can only return text), or `'imageData'`: the pixels as an `ImageData` (to measure, compare). */
+    as?: 'blob' | 'dataURL' | 'imageData';
 }
 interface ContactSheetOptions {
     /** Motion blur for these pictures (see `MovieOptions.motionBlur`); overrides the movie's own setting, `false` turns it off. */
@@ -384,12 +559,6 @@ interface FrameEvent {
     frame: number;
     totalFrames: number;
 }
-/** A presentation reached a stop (`movie.next()` played to it, or `prev()` / `goToStop()` / `goToPage()` jumped to it). */
-interface StopEvent {
-    index: number;
-    stop: Stop;
-    pageIndex: number;
-}
 interface ProgressEvent {
     progress: number;
     frame: number;
@@ -413,17 +582,14 @@ declare class Movie {
     app: Application | null;
     timeline: Timeline | null;
     audioBuffer: AudioBuffer | null;
-    audioSource: AudioBufferSourceNode | null;
-    gainNode: GainNode | null;
     private _cancelAudioStart;
     /** The poster time in seconds (`movie.init({ poster })`), or null. */
     poster: number | null;
-    /** The stops of the composition (`composition.stops`), checked and in order: where `next()` pauses. Empty for an ordinary movie. */
+    /** The stops of the composition (`composition.stops`), checked and in order: named times for a presentation to pause on (`pixi-effects/present`). Empty for an ordinary movie. */
     stops: Stop[];
-    /** The frame `next()` is playing toward, or null. */
-    private _stopAt;
-    private _stopWaiters;
-    private _arriving;
+    /** The frame `playUntil()` is playing toward, or null (also null while it plays to the end). */
+    private _until;
+    private _untilWaiters;
     /** The motion blur `render()`, `snapshot()` and `contactSheet()` apply unless told otherwise (`movie.init({ motionBlur })`), or null. */
     motionBlur: ResolvedMotionBlur | null;
     private _posterFrame;
@@ -454,8 +620,6 @@ declare class Movie {
     private _audioSources;
     private _mixStats;
     on(event: 'ready', fn: () => void): this;
-    /** A presentation is now on a stop (see `stops` in the composition, `next()`, `prev()`). */
-    on(event: 'stop', fn: (e: StopEvent) => void): this;
     on(event: 'frame', fn: (e: FrameEvent) => void): this;
     /** A jump to another frame (`gotoFrame`, a seek bar) starts / finishes. Not emitted for playback ticks, `render()`, `snapshot()` or `contactSheet()`. */
     on(event: 'seeking' | 'seeked', fn: (e: FrameEvent) => void): this;
@@ -469,7 +633,6 @@ declare class Movie {
     on(event: 'play', fn: () => void): this;
     on(event: 'pause', fn: () => void): this;
     off(event: string, fn: Listener): this;
-    emit(event: string, ...args: unknown[]): void;
     get isReady(): boolean;
     /** Milliseconds `init()` spent in each stage (assets, build, sound, frames), or null before it has finished: `check` says which stage is the slow one. */
     get loadStages(): Record<LoadStage, number> | null;
@@ -514,55 +677,13 @@ declare class Movie {
     snapshot(frame: number | undefined, opts: SnapshotOptions & {
         as: 'dataURL';
     }): Promise<string>;
+    snapshot(frame: number | undefined, opts: SnapshotOptions & {
+        as: 'imageData';
+    }): Promise<ImageData>;
     /** Seek to `frame` (quietly, and stay there) and draw the canvas on a new canvas of `scale` times its size. */
     private _frameCanvas;
-    /** The pixels of `frame`, small (about 320 px wide) and without motion blur, to compare pictures. */
-    private _framePixels;
     /** Seek to `frame` (quietly, and stay there) and encode the canvas as a picture. */
     private _captureFrame;
-    /**
-     * A picture of the settled state of each page (default: the page's last stop, fully built) or of every stop, for a page list, an
-     * overview, an export. Pauses the movie, and leaves the playhead where it was. `onImage` is called as each picture is ready.
-     */
-    stopImages(opts: StopImagesOptions & {
-        as: 'dataURL';
-    }): Promise<Array<StopImage & {
-        image: string;
-    }>>;
-    stopImages(opts?: StopImagesOptions): Promise<StopImage[]>;
-    /**
-     * Look at every stop: is the picture there still changing? A stop is compared with the picture `lookback` frames before it (default 3):
-     * when more than `tolerance` (default 0.4 %) of the picture differs, the audience, a page overview and a PDF all see a half-finished
-     * animation. `issues` says which stop, which page and what to do; leaves the playhead where it was.
-     */
-    inspectStops(opts?: {
-        lookback?: number;
-        tolerance?: number;
-    }): Promise<{
-        stops: Array<{
-            index: number;
-            page: string | null;
-            at: number;
-            frame: number;
-            moving: number;
-            settled: boolean;
-        }>;
-        issues: string[];
-    }>;
-    /**
-     * The deck as a PDF: one page per page of the talk (the page's last stop, fully built, unless a stop says `pdf: true` or `pdf: false`;
-     * `which: 'stops'` makes a page of every stop that is not `pdf: false`), each a
-     * JPEG at the canvas size. Needs `composition.stops`. A transparent background comes out black: give the movie a `background`.
-     */
-    exportPDF(opts?: {
-        which?: 'pages' | 'stops';
-        pick?: 'last' | 'first';
-        scale?: number;
-        quality?: number;
-        title?: string;
-        motionBlur?: MotionBlurSpec;
-        onImage?: (image: StopImage) => void;
-    }): Promise<Blob>;
     /**
      * One picture of a movement: `count` frames from `from` to `to` drawn one over the other, each later one stronger, so a thing that
      * moves leaves a trail (its path and its easing: even steps = constant speed, bunched = slow) and what stays still stays itself.
@@ -596,7 +717,7 @@ declare class Movie {
     timelineData(): TimelineData;
     /** The timeline as one self-contained HTML page (an inline SVG, no scripts): layers as bars on a time axis, ◆ keyframes, transition bands. Open it in a browser. */
     timelineChart(opts?: TimelineHtmlOptions): string;
-    /** Just the chart: one `<svg>` whose geometry is in `data-*` attributes (a viewer puts a playhead on it: `pixi-effects-view`). */
+    /** Just the chart: one `<svg>` whose geometry is in `data-*` attributes (a viewer puts a playhead on it: `pixi-effects view`). */
     timelineSvg(opts?: TimelineSvgOptions): string;
     /**
      * The soundtrack, measured: when every audio layer plays, how loud the mix is over time, and `issues`
@@ -608,7 +729,7 @@ declare class Movie {
         frame: number;
     }>;
     /**
-     * One call that looks at everything `pixi-effects-check` looks at inside the page: layout issues over the whole timeline (every
+     * One call that looks at everything `pixi-effects check` looks at inside the page: layout issues over the whole timeline (every
      * scene's first and last frame and a frame every 0.25 s), fonts and the sound. See `ReviewReport`. Page warnings are in `window.__logs`. The movie is left as it was.
      */
     review(opts?: ReviewOptions): Promise<ReviewReport>;
@@ -637,37 +758,24 @@ declare class Movie {
     private _updateSpace;
     /** The motion blur an operation uses: its own option when given (`false` is off), otherwise the movie's. */
     private _blurFor;
+    private _blurCanvas;
     /**
-     * @internal Draw `frame` with motion blur into `target` (a canvas the size of the stage): the average of `mb.samples` renders at moments
-     * spread over the shutter interval around the frame time. With `settle` the playhead and the stage are left exactly on the frame.
+     * Play and pause exactly at `seconds`: it resolves `true` when the playhead has landed on that frame, `false` when something else ended it
+     * first (a `pause()`, a seek, a newer `playUntil()`), or when there is nothing to play toward (a time at or before the playhead, which also
+     * pauses it where it is, or a movie that is not ready). A time at or past the end lands on the last frame; with no time at all it plays to
+     * the end and resolves `true` once the movie has ended (and says `ended`). An ordinary `play()` is
+     * not affected by it. It is the one primitive a presentation is built on (see `pixi-effects/present`).
      */
-    _exposeFrame(frame: number, mb: ResolvedMotionBlur, target: HTMLCanvasElement, settle: boolean): Promise<void>;
-    private _blurCanvas;
-    /** Which stop the playhead is on or has passed (-1 before the first). */
-    get stopIndex(): number;
-    /** The stop the playhead is on or has passed, or null. */
-    get currentStop(): Stop | null;
-    /** Which page the playhead is in (0-based), -1 before the first stop. */
-    get pageIndex(): number;
-    /** How many pages the stops make. */
-    get pageCount(): number;
-    private _cancelStop;
-    private _settleStopWaiters;
-    private _emitStop;
-    /** Land exactly on a stop's frame, pause, and say so. */
-    private _arriveAtStop;
+    playUntil(seconds?: number): Promise<boolean>;
     /**
-     * Play to the next stop and pause exactly there (a presentation's "next"). Pressed again while it is playing toward a stop, it skips the
-     * rest of the animation and lands on that stop at once. After the last stop it plays to the end. Resolves when it has landed (or
-     * stopped for another reason). An ordinary `play()` ignores the stops.
+     * Look around and put the movie back: pauses, runs `fn` (seek, take pictures: the seeks made inside are not reported as `seeking` / `seeked`),
+     * then puts the playhead (or the poster) back where it was, whatever `fn` did, and returns what `fn` returned.
      */
-    next(): Promise<void>;
-    /** Jump back to the previous stop at once (no reverse playback); from the first stop, to the start. */
-    prev(): Promise<void>;
-    /** Jump to stop `index` (0-based). */
-    goToStop(index: number): Promise<void>;
-    /** Jump to the first stop of page `page` (0-based). */
-    goToPage(page: number): Promise<void>;
+    peek<T>(fn: () => Promise<T>): Promise<T>;
+    private _settleUntil;
+    private _cancelUntil;
+    /** The playhead reached the frame `playUntil()` was playing to: land exactly on it, pause, resolve true. */
+    private _arriveUntil;
     play(): void;
     pause(): void;
     set volume(v: number);
@@ -679,4 +787,4 @@ declare class Movie {
     destroy(): Promise<void>;
 }
 
-export { type AudioInspectOptions as A, type ContactSheetOptions as C, type FontReport as F, type InspectOptions as I, type LayerInfo as L, type MotionBlurOptions as M, type OnionSkinOptions as O, type ProgressEvent as P, type RenderOptions as R, type SnapshotOptions as S, type TimelineData as T, type VolumeEvent as V, type AudioReport as a, type AudioSourceReport as b, type FrameEvent as c, type InspectReport as d, type IssueGroup as e, type LoadProgressState as f, type LoadStage as g, type LoaderOption as h, type MotionBlurSpec as i, Movie as j, type MovieErrorEvent as k, type MovieOptions as l, type ReviewOptions as m, type ReviewReport as n, type SoundMeasure as o, type StopEvent as p, type StopImage as q, type StopImagesOptions as r, type TimelineHtmlOptions as s, type TimelineRow as t, type TimelineSvgOptions as u, type TimelineTransition as v, dismissLoader as w, failLoader as x, resolveLoader as y };
+export { type AudioInspectOptions as A, failLoader as B, type ContactSheetOptions as C, resolveLoader as D, type FontReport as F, type InspectOptions as I, type LayerInfo as L, type MusicEvents as M, type OnionSkinOptions as O, type ProgressEvent as P, type RenderOptions as R, type SnapshotOptions as S, type TimelineData as T, type VolumeEvent as V, type AudioReport as a, type AudioSourceReport as b, type FrameEvent as c, type InspectReport as d, type IssueGroup as e, type LoadProgressState as f, type LoadStage as g, type LoaderOption as h, type MotionBlurOptions as i, type MotionBlurSpec as j, Movie as k, type MovieErrorEvent as l, type MovieOptions as m, type MusicDrumEvents as n, type MusicDrumHit as o, type MusicNote as p, type MusicSummary as q, type MusicTrackEvents as r, type ReviewOptions as s, type ReviewReport as t, type SoundMeasure as u, type TimelineHtmlOptions as v, type TimelineRow as w, type TimelineSvgOptions as x, type TimelineTransition as y, dismissLoader as z };