pixi-effects 0.28.2 → 0.29.0

package/dist/{types-DpK1vwcl.d.cts → types-BzIB65Vk.d.ts}

@@ -1,128 +1,3 @@
-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). */
@@ -154,97 +29,6 @@ interface Stop {
     advance?: number;
     pdf?: boolean;
 }
-/**
- * The stops of a composition, checked and in order. Numbers are stops; with no `page` anywhere every stop is a page of its
- * own, otherwise only the stops that say `page` start one (the first stop always does). Negative times count back from the end;
- * two stops on the same frame are one; anything outside the movie or not a number is dropped, with a warning that names it.
- */
-declare function normalizeStops(raw: ReadonlyArray<number | StopSpec> | undefined, duration: number, frameRate: number): Stop[];
-/**
- * The stops whose pictures stand for the pages (`which: 'pages'`, default) or for every stop. A page's picture is, in order: the stop flagged
- * `pdf: true` (the last such one, or the first with `pick: 'first'`), else the last (or first) stop not flagged `pdf: false`, else, for a page
- * list, its last (or first) stop, and for a PDF (`pdf: true` here) nothing: the page is left out. With `which: 'stops'` a PDF leaves out the
- * stops flagged `pdf: false`.
- */
-declare function pictureStops(stops: readonly Stop[], opts?: {
-    which?: 'pages' | 'stops';
-    pick?: 'last' | 'first';
-    pdf?: boolean;
-}): Stop[];
-
-/** 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[];
-    }>;
-}
 
 /**
  * pixi-effects public DSL types.
@@ -325,7 +109,7 @@ interface ChromaKeyFilterSpec {
 /**
  * A filter by name: `{ type: 'glow', outerStrength: 3, color: '#ffd166' }`. The type is the filter's class name without
  * `Filter` in camelCase (case does not matter); every other key is the filter's own option. `blur`, `noise`, `alpha` and
- * `colorMatrix` (`preset: 'sepia' | 'grayscale' | …` or a 20-number `matrix`) come from pixi.js; the rest are the filters of
+ * `colorMatrix` (`preset: 'sepia' | 'grayscale' | …` or a 20-number `matrix`) come from pixi.js; `grain` and `warp` are this library's own, the rest are the filters of
  * the `pixi-filters` package (add it to the import map, or `npm i pixi-filters`), loaded on first use. Animate an option with
  * `'filters.<name>.<option>'` like any other filter.
  */
@@ -334,7 +118,7 @@ interface NamedFilterSpec {
     name?: string;
     [option: string]: unknown;
 }
-type NamedFilterType = 'blur' | 'noise' | 'alpha' | 'colorMatrix' | 'grain' | 'adjustment' | 'advancedBloom' | 'ascii' | 'backdropBlur' | 'bevel' | 'bloom' | 'bulgePinch' | 'colorGradient' | 'colorMap' | 'colorOverlay' | 'colorReplace' | 'convolution' | 'crossHatch' | 'crt' | 'dot' | 'dropShadow' | 'emboss' | 'glitch' | 'glow' | 'godray' | 'grayscale' | 'hslAdjustment' | 'kawaseBlur' | 'motionBlur' | 'multiColorReplace' | 'oldFilm' | 'outline' | 'pixelate' | 'radialBlur' | 'reflection' | 'rgbSplit' | 'shockwave' | 'simpleLightmap' | 'simplexNoise' | 'tiltShift' | 'tiltShiftAxis' | 'twist' | 'zoomBlur';
+type NamedFilterType = 'blur' | 'noise' | 'alpha' | 'colorMatrix' | 'grain' | 'warp' | 'adjustment' | 'advancedBloom' | 'ascii' | 'backdropBlur' | 'bevel' | 'bloom' | 'bulgePinch' | 'colorGradient' | 'colorMap' | 'colorOverlay' | 'colorReplace' | 'convolution' | 'crossHatch' | 'crt' | 'dot' | 'dropShadow' | 'emboss' | 'glitch' | 'glow' | 'godray' | 'grayscale' | 'hslAdjustment' | 'kawaseBlur' | 'motionBlur' | 'multiColorReplace' | 'oldFilm' | 'outline' | 'pixelate' | 'radialBlur' | 'reflection' | 'rgbSplit' | 'shockwave' | 'simpleLightmap' | 'simplexNoise' | 'tiltShift' | 'tiltShiftAxis' | 'twist' | 'zoomBlur';
 type FilterSpec = ChromaKeyFilterSpec | CustomFilterSpec | NamedFilterSpec;
 interface TransitionCommon {
     /** Sibling sequence's `name` — the outgoing scene. */
@@ -407,9 +191,12 @@ interface LumaTransition extends TransitionCommon {
 type TransitionSpec = CrossfadeTransition | WipeTransition | IrisTransition | SlideTransition | DipTransition | ZoomTransition | DissolveTransition | LumaTransition;
 /** How a layer blends with what is behind it: the CSS `mix-blend-mode` names, plus `add` and `linear-burn`. */
 type BlendModeName = 'normal' | 'add' | 'screen' | 'multiply' | 'overlay' | 'soft-light' | 'hard-light' | 'color-dodge' | 'color-burn' | 'darken' | 'lighten' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'linear-burn';
-/** A matte given by name: another layer of the same composition. `channel` is how it is read (`'alpha'` by default, or `'luma'`: its brightness); `invert` uses 1 − matte. */
+/**
+ * A matte with options: `layer` is another layer of the same composition by name, or a layer written in place. `channel` is how it is read (`'alpha'` by
+ * default, or `'luma'`: its brightness); `invert` uses 1 − matte (a hole instead of a crop). A layer written in place cannot go inside a list.
+ */
 interface MatteRefSpec {
-    layer: string;
+    layer: string | SequenceSpec;
     channel?: 'alpha' | 'luma';
     invert?: boolean;
 }
@@ -457,18 +244,10 @@ interface SequenceCommon {
      * geometric reveals.
      *
      * Instead of a layer written in place, `mask` can name another layer of the same composition (a matte: it is not drawn, and several
-     * layers can share it), `{ layer, channel, invert }`, or a list of those (all of them must let the layer through: intersect; subtract
-     * with `invert: true`).
+     * layers can share it), `{ layer, channel, invert }` (`layer` is a name, or a layer written in place), or a list of names and `{ layer: name }`
+     * (all of them must let the layer through: intersect; subtract with `invert: true`). A hole instead of a crop: `mask: { layer: { …the shape… }, invert: true }`.
      */
     mask?: SequenceSpec | MaskRefSpec | MaskRefSpec[];
-    /**
-     * When true, the mask is inverted: pixels inside the mask shape become
-     * transparent and pixels outside become visible. Useful for "knockout"
-     * effects (cut a hole through an image / panel). Default false.
-     *
-     * Routed through PIXI's native `setMask({ inverse: true })`.
-     */
-    maskInverted?: boolean;
     /**
      * How this layer blends with what is behind it (everything drawn below it). `'add'` and `'screen'` brighten (glows, light
      * leaks, overlapping halos add up instead of covering each other), `'multiply'` darkens; `'overlay'`, `'soft-light'`,
@@ -899,7 +678,7 @@ interface CompositionSpec extends SequenceCommon {
     transitions?: TransitionSpec[];
     /**
      * Where a presentation pauses: seconds, or `{ at, page?, notes?, advance? }` (see `StopSpec`). A stop with `page` begins a page, the others
-     * are steps of it; with no `page` anywhere each stop is a page. Nothing changes for an ordinary player: `Presenter` (and `movie.next()`)
+     * are steps of it; with no `page` anywhere each stop is a page. Nothing changes for an ordinary player: `Presenter` (and `next(movie)`, from `pixi-effects/present`)
      * stop at them, `Controller` shows them as marks on the seek bar.
      */
     stops?: Array<number | StopSpec>;
@@ -914,38 +693,5 @@ interface CompositionShape {
     /** Called after each layer is built (the root shape only): feeds `loadprogress` and lets the page paint now and then. */
     onLayerBuilt?: () => void | Promise<void>;
 }
-/** Audio descriptor pushed to the mixdown queue by AudioSequence/VideoSequence. */
-interface AudioDescriptor {
-    /** Decoded audio (a file or a video's soundtrack). Exactly one of `buffer` / `synth` is set. */
-    buffer?: AudioBuffer;
-    /** Stereo samples (left, right) made on demand at the mix's sample rate (a synthesised sfx). Equal keys render equal samples. */
-    synth?: {
-        key: string;
-        render: (sampleRate: number) => [Float32Array, Float32Array];
-        /** The same samples in slices: `pace(done)` (0..1) runs between them and may wait, so a long piece does not freeze the page. */
-        renderAsync?: (sampleRate: number, pace?: (done: number) => Promise<void> | void) => Promise<[Float32Array, Float32Array]>;
-    };
-    /** Who made it, for warnings and inspectAudio: `layer "pop-1"`. */
-    layer?: string;
-    /** What it plays: `sfx "pop"`, `asset "bgm"`, `video "green"`. */
-    source?: string;
-    /** A music layer's score read back: bars per track, what starts in each bar, the drum spans (for `movie.inspectAudio()` and the `check` tool). */
-    music?: MusicSummary;
-    loop: boolean;
-    start: number;
-    end: number;
-    initialVolume: number;
-    volumeKeyframes: {
-        time: number;
-        value: number;
-    }[];
-    /**
-     * Time remap. `warp` maps the movie's time to the time `start` / `end` / `volumeKeyframes` are measured in (a remapped composition's
-     * local time), NaN where it is silent. `sourceMap` maps that time to a position in the sound (the layer's own speed / `time`); absent:
-     * the sound plays straight from `start`. The mixer resamples through them, so a speed other than 1 changes the pitch.
-     */
-    warp?: (t: number) => number;
-    sourceMap?: (u: number) => number;
-}
 
-export { type SfxPreset 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 MusicInstrument as H, type ImageSequenceSpec as I, type MusicLevel as J, type Keyframe as K, type LightSequenceSpec as L, type MusicOptions as M, type MusicNote as N, type MusicSummary as O, type Props as P, type MusicTrack as Q, type MusicTrackEvents as R, type SequenceSpec as S, type TextSequenceSpec as T, type NullSequenceSpec as U, type PathShapeSpec as V, type PolygonShapeSpec as W, type PropValue as X, type RectShapeSpec as Y, type SfxKnobs as Z, type SfxOptions as _, type CameraSequenceSpec as a, type SfxVoice as a0, type ShaderSequenceSpec as a1, type ShapeSequenceSpec as a2, type SlideTransition as a3, type Stop as a4, type StopSpec as a5, type TransitionCommon as a6, type VideoSequenceSpec as a7, type WipeTransition as a8, type ZoomTransition as a9, normalizeStops as aa, pictureStops as ab, type Timeline as ac, type AudioDescriptor as ad, type MusicEvents as b, type TransitionSpec as c, type CompositionSpec as d, type SequenceCommon as e, type AssetSpec as f, type AudioAssetSpec as g, type AudioMusicSpec as h, type AudioSequenceSpec as i, type AudioSfxSpec as j, type ChromaKeyFilterSpec as k, type CircleShapeSpec as l, type CompositionSequenceSpec as m, type CrossfadeTransition as n, type CustomFilterSpec as o, type DissolveTransition as p, type Expr as q, type IrisTransition as r, type LineShapeSpec as s, type LumaTransition as t, type MaskRefSpec as u, type MatteRefSpec as v, type MusicDrum as w, type MusicDrumEvents as x, type MusicDrumHit as y, type MusicDrums as z };
+export type { TransitionCommon as $, ArcShapeSpec as A, BlendModeName as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, PropValue as H, ImageSequenceSpec as I, Props as J, Keyframe as K, LightSequenceSpec as L, MusicOptions as M, NullSequenceSpec as N, SfxKnobs as O, PathShapeSpec as P, SfxOptions as Q, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, SfxPreset as U, SfxVoice as V, ShaderSequenceSpec as W, ShapeSequenceSpec as X, SlideTransition as Y, Stop as Z, StopSpec as _, CameraSequenceSpec as a, TransitionSpec as a0, VideoSequenceSpec as a1, WipeTransition as a2, ZoomTransition as a3, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioMusicSpec as e, AudioSequenceSpec as f, AudioSfxSpec as g, ChromaKeyFilterSpec as h, CircleShapeSpec as i, CompositionSequenceSpec as j, CompositionSpec as k, CrossfadeTransition as l, CustomFilterSpec as m, DissolveTransition as n, Expr as o, IrisTransition as p, LineShapeSpec as q, LumaTransition as r, MaskRefSpec as s, MatteRefSpec as t, MusicDrum as u, MusicDrums as v, MusicInstrument as w, MusicLevel as x, MusicTrack as y, PolygonShapeSpec as z };

package/docs/api.md

@@ -2,7 +2,6 @@
 
 - [`Movie`](#movie) — composition runtime: init, playback, render
 - [`Controller`](#controller) — drop-in player UI overlay
-- [Helpers](#helpers) — pure utilities exported from `pixi-effects/controller`
 - [`pixi-effects/three`](#pixi-effectsthree) — optional three.js integration
 
 For DSL types (composition spec, sequences, filters, keyframes, expressions), see [DSL reference](./dsl.md).
@@ -71,13 +70,21 @@ Seeks to a specific frame. Pauses if currently playing? **No** — does not chan
 
 `force=true` skips the early-return when the requested frame equals `currentFrame`. Use it after a composition rebuild.
 
+### `movie.playUntil(seconds?): Promise<boolean>`
+
+Play, and pause exactly at `seconds` (the frame `round(seconds × frameRate)`). It resolves `true` when the playhead has landed there; `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: it also pauses the movie where it is; 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, says `ended`, and resolves `true`. An ordinary `play()` is not affected. It is the one move a presentation (`pixi-effects/present`) is built on; it is also the way to "play the intro, then wait": `await movie.playUntil(4.5)`.
+
+### `movie.peek(fn): Promise<T>`
+
+Look around and put the movie back: pauses, runs `fn` (seek, take pictures with `snapshot()`; 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. `stopImages()` and `inspectStops()` (`pixi-effects/present`) are made with it.
+
 ### `movie.snapshot(frame?, options?): Promise<Blob | string>`
 
 ```ts
-snapshot(frame?: number, options?: { scale?: number; type?: 'image/png' | 'image/jpeg'; as?: 'blob' | 'dataURL'; motionBlur?: MotionBlurSpec }): Promise<Blob | string>
+snapshot(frame?: number, options?: { scale?: number; type?: 'image/png' | 'image/jpeg'; quality?: number; as?: 'blob' | 'dataURL' | 'imageData'; motionBlur?: MotionBlurSpec }): Promise<Blob | string | ImageData>
 ```
 
-A picture of one frame: **the canvas only** (the player bar is not in it). Seeks to `frame` (default: the current frame) and stays there. `as: 'dataURL'` returns a `data:` URL string, handy when a script can only return text. Use it to look at what you built.
+A picture of one frame: **the canvas only** (the player bar is not in it). Seeks to `frame` (default: the current frame) and stays there. `as: 'dataURL'` returns a `data:` URL string, `as: 'imageData'` the pixels as an `ImageData` (to measure or compare; `quality` is the JPEG quality, 0 to 1), handy when a script can only return text. Use it to look at what you built.
 
 ### `movie.contactSheet(options?): Promise<Blob | string>`
 
@@ -174,10 +181,10 @@ interface RenderOptions {
 
 `movie.init({ motionBlur })` (or the same option on a single `render()`, `snapshot()` or `contactSheet()` call) exposes each frame the way a film camera does: the frame is drawn `samples` times at moments spread over the shutter interval around its time, and the pictures are averaged. Fast motion smears along its path; a still picture is unchanged. `true` is 8 samples at a 180° shutter, a number is the sample count (2–64), `{ samples, shutter }` sets both (`shutter` is the fraction of a frame the shutter stays open, above 0 and up to 1; `0.5` is the film look, `1` blurs more). `false` turns it off for one call.
 
-- It applies to what is **made**: the exported file, snapshots, contact sheets (so `pixi-effects-check` and `inspect`-style reviews show what the file will have). Live playback is not blurred.
+- It applies to what is **made**: the exported file, snapshots, contact sheets (so `pixi-effects check` and `inspect`-style reviews show what the file will have). Live playback is not blurred.
 - Cost: a render takes about `samples` times as long (video layers are decoded once per sample). Eight samples is enough for most motion; raise it for very fast or large movement, where fewer samples show as separate ghost images instead of a smear.
 - 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.
+- `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.
 
@@ -203,13 +210,13 @@ const blob = await movie.posterImage();             // the picture at that time
 - Once the movie is ready the **canvas shows the poster frame**, while the playhead stays at frame 0 (`currentFrame` is 0, the player shows 0:00). The first `play()` or `gotoFrame()` replaces it, and **play starts from 0**.
 - `posterImage()` leaves the movie as it was: still showing the poster, or back at the frame it was at. `contactSheet()` does the same.
 - A time past the end is clamped to the last frame, and something that is not a number is ignored; both warn.
-- `pixi-effects-check` writes the poster as `poster.jpg`.
+- `pixi-effects check` writes the poster as `poster.jpg`.
 
 ### `movie.timelineData(): TimelineData` and `movie.timelineChart(options?): string`
 
-The whole movie as rows on a time axis, for a person to read at a glance. `timelineData()` is the data: `{ duration, rows, transitions }`, a row per layer with `name`, `type`, `depth` (1 inside a composition), absolute `start` / `end` in seconds, `keys` (when each keyframe starts) and, for a family of generated layers, `parts` (one span per layer). Layers of one type whose names differ only by numbers (`ring10-0`, `ring9-1`, `pop-3` …), four or more, become ONE row (`ring#-# ×19`), so a movie with 700 generated layers is a screenful. `timelineChart({ title })` returns one self-contained HTML page (an inline SVG, no scripts): bars coloured by type, ◆ at each keyframe start, a shaded band per transition, a tooltip per bar. `pixi-effects-check` writes it next to the contact sheet as `timeline.html`.
+The whole movie as rows on a time axis, for a person to read at a glance. `timelineData()` is the data: `{ duration, rows, transitions }`, a row per layer with `name`, `type`, `depth` (1 inside a composition), absolute `start` / `end` in seconds, `keys` (when each keyframe starts) and, for a family of generated layers, `parts` (one span per layer). Layers of one type whose names differ only by numbers (`ring10-0`, `ring9-1`, `pop-3` …), four or more, become ONE row (`ring#-# ×19`), so a movie with 700 generated layers is a screenful. `timelineChart({ title })` returns one self-contained HTML page (an inline SVG, no scripts): bars coloured by type, ◆ at each keyframe start, a shaded band per transition, a tooltip per bar. `pixi-effects check` writes it next to the contact sheet as `timeline.html`.
 
-`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.
+`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.
 
 ### Your own layer type: `Sequence` and `registerSequenceType(type, ctor)`
 
@@ -252,7 +259,6 @@ movie.off(event, fn): this
 | `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
 | `'loadprogress'` | `{ stage: 'assets' \| 'build' \| 'sound' \| 'frames'; loaded: number; total: number; progress: number }` | during `init()`, after each asset and each layer built, once the sound is mixed; `progress` is 0 to 1 for the whole init. The page's `.pe-loader` already shows it; `movie.loadStages` gives the milliseconds per stage afterwards |
 | `'seeking'` / `'seeked'` | `{ frame, totalFrames }` (the frame it lands on) | a `gotoFrame()` to another frame starts / has finished. NOT emitted for playback ticks, `render()`, `snapshot()` or `contactSheet()` |
-| `'stop'`    | `{ index: number; stop: Stop; pageIndex: number }` | a presentation is on a stop: `next()` played to it, or `prev()` / `goToStop()` / `goToPage()` jumped to it |
 | `'ended'`   | none                                              | playback ran off the end (after `'pause'`); pausing by hand does not emit it |
 | `'volumechange'` | `{ volume: number; muted: boolean }`         | `volume` or `muted` really changed (clamping counts) |
 | `'error'`   | `{ where: 'init' \| 'render' \| 'playback'; message: string; error: unknown }` | `init()` / `render()` failed (the call still rejects), or a frame failed during playback |
@@ -276,28 +282,32 @@ The names are the ones an HTML5 `<video>` uses, so a player written for `<video>
 | `muted`          | boolean   | getter/setter; immediate                                |
 | `app`            | `pixi.js Application \| null` | PIXI Application instance (advanced/escape hatch) |
 | `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) |
+| `stops`          | `Stop[]`  | the composition's stops: named times (see Presentations); empty for an ordinary movie |
 
-### Presentations: `stops`, `next()`, `prev()`, `Presenter`
+### Presentations: `stops` and `pixi-effects/present`
 
 A composition can say where a presentation pauses: `composition: { stops: [...] }`. A stop is a time in seconds or `{ at, page?, notes?, advance?, pdf? }`; a stop with `page` (a name, or `true`) begins a page, the others are steps of it; with no `page` anywhere each stop is a page; the first stop always begins one. A negative `at` counts back from the end; two stops on one frame are one; a stop outside the movie is ignored with a warning. `movie.play()` ignores the stops and plays to the end; the `Controller`'s play button, Space and a click on the picture play to the next stop and pause there (see `pauseAtStops`). `pdf: true` marks the stop whose picture stands for its page in a PDF (and in the page overview); `pdf: false` keeps a stop's picture out of the PDF (a last stop that is mid-exit, a step you do not want on paper). Without flags a page is pictured by its last stop.
 
 ```ts
-movie.stops                    // Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance?, pdf? }
-await movie.next();            // play to the next stop and pause exactly on its frame; pressed again while playing, skip to that stop at once;
+import { next, prev, goToStop, goToPage, onStop, stopIndex, pageIndex, pageCount, currentStop } from 'pixi-effects/present';
+
+movie.stops                    // (the core) Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance?, pdf? }
+await next(movie);             // play to the next stop and pause exactly on its frame; pressed again while playing, skip to that stop at once;
                                // after the last stop play to the end. Resolves when it has landed (or stopped for another reason).
-await movie.prev();            // jump back to the previous stop at once (no reverse playback); from the first stop, to the start
-await movie.goToStop(i);       // 0-based
-await movie.goToPage(n);       // 0-based: the first stop of page n
-movie.stopIndex / movie.pageIndex / movie.pageCount / movie.currentStop
-movie.on('stop', ({ index, stop, pageIndex }) => …)
+await prev(movie);             // jump back to the previous stop at once (no reverse playback); from the first stop, to the start
+await goToStop(movie, i);      // 0-based
+await goToPage(movie, n);      // 0-based: the first stop of page n
+stopIndex(movie) / pageIndex(movie) / pageCount(movie) / currentStop(movie)      // where the playhead is (-1 / null before the first stop)
+const off = onStop(movie, ({ index, stop, pageIndex }) => …);                    // a stop was landed on; off() stops listening
 ```
 
-`deck({ pages, transition? })` builds such a movie from pages (see the DSL reference). **`Presenter`** (`pixi-effects/presenter`) is the player for it:
+The presentation side is a separate entry, `pixi-effects/present`, built on the core's public API only (an import map line: `"pixi-effects/present": ".../dist/present.js"`). The core knows `stops` (named times) and two general moves it is made of: `movie.playUntil(seconds)` and `movie.peek(fn)` (below). An ordinary `movie.play()` ignores the stops. `onStop` listeners belong to the `pixi-effects/present` module the page imported: the `Controller` loads `present.js` from beside itself, so map `"pixi-effects/present"` to the same folder as `Controller.js`, or a Controller landing will not reach your `onStop`.
+
+
+`deck({ pages, transition? })` (from `pixi-effects/present`) builds such a movie from pages (see the DSL reference). **`Presenter`** (also `pixi-effects/present`) is the player for it:
 
 ```ts
-import { Presenter } from 'pixi-effects/presenter';
+import { Presenter } from 'pixi-effects/present';
 const presenter = new Presenter(movie, { canvas });     // instead of Controller; await presenter.start() to go fullscreen and play to the first stop
 ```
 
@@ -315,18 +325,19 @@ const presenter = new Presenter(movie, { canvas });     // instead of Controller
 
 **The page overview (`G`)** is a grid of every page with its picture, the current page marked: arrows choose, Enter or a click goes there, `G` or Esc closes. **The presenter view (`P`)** opens a second window for the speaker: the picture that is on screen (live), the picture of the next stop, the notes of the page, a timer (with reset), the page counter and Back / Next buttons; the keys work there too. Both use a picture of every stop that `start()` makes **before** the audience sees anything (behind a "Preparing…" cover; taking them moves the playhead through the stops and back, so it must not happen on screen); `presenter.ensureThumbs()` makes them on demand (an overview opened before that does it on the spot, with a flicker). A browser needs a click or key press to open a popup: `P` is one; if it is blocked a warning says so.
 
-`presenter.start()`, `presenter.openPresenterView()`, `presenter.closePresenterView()`, `presenter.next()`, `presenter.prev()`, `presenter.setCover('black' \| 'white' \| 'off')`, `presenter.exit()`, `presenter.destroy()`. It uses the canvas's positioned parent, or wraps the canvas like `Controller` does. A movie with stops shown through a **`Controller`** gets a mark per stop on the seek bar and a Present button (`present: false` leaves the marks only) that hands the page to a `Presenter` (fullscreen, keys, click and swipe move through the stops; Esc gives the bar back).
+`presenter.start()`, `presenter.openPresenterView()`, `presenter.closePresenterView()`, `presenter.next()`, `presenter.prev()`, `presenter.setCover('black' \| 'white' \| 'off')`, `presenter.exit()`, `presenter.destroy()`. It uses the canvas's positioned parent, or wraps the canvas like `Controller` does. A movie with stops shown through a **`Controller`** gets a mark per stop on the seek bar and a Present button (`presentButton: false` leaves the marks only) that hands the page to a `Presenter` (fullscreen, keys, click and swipe move through the stops; Esc gives the bar back).
 
-### `movie.inspectStops(options?)`
+### `inspectStops(movie, options?)`
 
-Is the picture at each stop still changing? Each stop is compared with the picture `lookback` frames before it (default 3); when more than `tolerance` (default 0.004, a share of the pixels) differs, the audience, the page overview and a PDF would see a half-finished animation. Returns `{ stops: [{ index, page, at, frame, moving, settled }], issues: string[] }`; each issue names the stop and the page and says what to do (move the stop to after the animation has ended, or flag a settled stop of the page `pdf: true`). Leaves the playhead where it was. `pixi-effects-check` runs it for any page with `stops`.
+Is the picture at each stop still changing? Each stop is compared with the picture `lookback` frames before it (default 3); when more than `tolerance` (default 0.004, a share of the pixels) differs, the audience, the page overview and a PDF would see a half-finished animation. Returns `{ stops: [{ index, page, at, frame, moving, settled }], issues: string[] }`; each issue names the stop and the page and says what to do (move the stop to after the animation has ended, or flag a settled stop of the page `pdf: true`). Leaves the playhead where it was. `pixi-effects check` runs it for any page with `stops` (it loads the page's own `pixi-effects/present`; add that line to the import map).
 
-### Pictures of the stops and the deck as a PDF: `movie.stopImages()`, `movie.exportPDF()`
+### Pictures of the stops and the deck as a PDF: `stopImages(movie)`, `exportPDF(movie)`
 
 ```ts
-const pages = await movie.stopImages({ as: 'dataURL', type: 'image/jpeg', scale: 0.25 });   // one picture per PAGE: its last stop, fully built
+import { stopImages, exportPDF } from 'pixi-effects/present';
+const pages = await stopImages(movie, { as: 'dataURL', type: 'image/jpeg', scale: 0.25 });   // one picture per PAGE: its last stop, fully built
 // [{ stop, page, image }, …]; { which: 'stops' } is one per stop, { pick: 'first' } the first stop of each page; onImage(img) is called as each one is ready
-const pdf = await movie.exportPDF({ title: 'My talk' });                                    // a Blob: one PDF page per page of the deck (JPEG at the canvas size)
+const pdf = await exportPDF(movie, { title: 'My talk' });                                    // a Blob: one PDF page per page of the deck (JPEG at the canvas size)
 ```
 
 Both pause the movie and leave the playhead where it was; a movie with no stops returns an empty list / throws (a PDF needs pages). The picture of a page is, in order: its last stop flagged `pdf: true`, else its last (with `pick: 'first'`, first) stop that is not `pdf: false`; a page whose stops are all `pdf: false` is left out of a PDF (a page list still shows it by its last stop); `which: 'stops'` makes a page of every stop that is not `pdf: false`. `exportPDF` options: `which`, `pick`, `scale`, `quality` (JPEG, default 0.92), `title`, `motionBlur`, `onImage`. A transparent background comes out black in a JPEG: give the movie a `background`. From a script, `npx pixi-effects render my-talk.html -o my-talk.pdf` (add `--all-stops` for a page per stop).
@@ -411,7 +422,7 @@ el('play').onclick = () => (movie.isPlaying ? movie.pause() : movie.play());
 el('seek').oninput = e => movie.gotoFrame(+e.target.value);
 ```
 
-What you have: `play()`, `pause()`, `gotoFrame(frame)`, `volume`, `muted` / `toggleMute()`; the state `currentFrame`, `totalFrames`, `frameRate`, `duration`, `isPlaying`, `isReady`, `loadStages` (milliseconds `init()` spent in `assets` / `build` / `sound` / `frames`), `audioBlocked` (true while the browser keeps the movie's sound silent until a tap: show "tap for sound"; a tap or key press that arrives while `play()` is pending, or the next `play()` made from a tap, starts it); the events above; `render()` for a download button; `snapshot()` for a thumbnail; `timelineData()` / `timelineSvg()` for a timeline like `pixi-effects-view`'s. Keep the movie's `canvas` wherever your layout wants it (the page's CSS sizes it). To only change how `Controller` looks, see **Theme** below.
+What you have: `play()`, `pause()`, `gotoFrame(frame)`, `volume`, `muted` / `toggleMute()`; the state `currentFrame`, `totalFrames`, `frameRate`, `duration`, `isPlaying`, `isReady`, `loadStages` (milliseconds `init()` spent in `assets` / `build` / `sound` / `frames`), `audioBlocked` (true while the browser keeps the movie's sound silent until a tap: show "tap for sound"; a tap or key press that arrives while `play()` is pending, or the next `play()` made from a tap, starts it); the events above; `render()` for a download button; `snapshot()` for a thumbnail; `timelineData()` / `timelineSvg()` for a timeline like `pixi-effects view`'s. Keep the movie's `canvas` wherever your layout wants it (the page's CSS sizes it). To only change how `Controller` looks, see **Theme** below.
 
 ## `Controller`
 
@@ -441,9 +452,9 @@ new Controller(movie: Movie, options: ControllerOptions)
 
 interface ControllerOptions {
   canvas: HTMLCanvasElement;          // required
-  showExportButton?: boolean;         // default true; hides ⬇ + popover
-  enableKeyboardShortcuts?: boolean;  // default true
-  present?: boolean;                  // default true: a movie with stops gets a Present button (marks on the seek bar are always shown)
+  exportButton?: boolean;             // default true; false hides ⬇ + popover
+  keyboard?: boolean;                 // default true
+  presentButton?: boolean;            // default true: a movie with stops gets a Present button (marks on the seek bar are always shown)
   pauseAtStops?: boolean;             // default true: with stops, play / Space / click on the picture play to the next stop and pause; false plays straight through
   clickToPlay?: boolean;              // default true: a click / tap on the picture plays / pauses (like <video>); false leaves the canvas alone
   className?: string;                 // default 'movie-controller'
@@ -478,7 +489,7 @@ controller.setTheme({ accent: null });               // null = back to the defau
 | `trackHeight` | `--mc-track-height` | thickness of the progress bar (a number is px) | `3px` |
 | `font` | `--mc-font` | `font-family` of the bar | system UI font |
 
-A misspelt key warns with the valid ones. The default stylesheet is exported as `CONTROLLER_CSS` (from `pixi-effects/controller`) if you want to copy and restyle more.
+A misspelt key warns with the valid ones. To restyle more than the theme covers, set the `--mc-*` custom properties (or override the `.movie-controller` classes) in your own CSS.
 
 ### `controller.destroy(): void`
 
@@ -504,7 +515,7 @@ The download is triggered by an in-page `<a download>` click, so the file lands
 
 ### Keyboard shortcuts
 
-Active when `enableKeyboardShortcuts: true` and the key target is not `<input>`/`<textarea>`/`<select>`/contenteditable.
+Active when `keyboard: true` and the key target is not `<input>`/`<textarea>`/`<select>`/contenteditable.
 
 | Key         | Action                                              |
 | ----------- | --------------------------------------------------- |
@@ -520,50 +531,6 @@ Active when `enableKeyboardShortcuts: true` and the key target is not `<input>`/
 
 The bar uses fixed colors (`#007AFF` for the active track / fill / confirm button, white for icons, `rgba(0,0,0,0.75)` gradient background). Override by adding stricter CSS rules under `.movie-controller`. A theming API (CSS custom properties) is on the roadmap.
 
----
-
-## Helpers
-
-These pure functions are exported from `pixi-effects/controller` for consumers who want to build custom controls or reuse the parsing utilities. All are side-effect-free.
-
-```ts
-import { formatTime, frameToPercent, pxToFrame, pxToFraction, extensionForMimeType }
-  from 'pixi-effects/controller';
-```
-
-### `formatTime(seconds: number): string`
-
-Returns `M:SS` (no leading zero on minutes). `formatTime(125)` → `"2:05"`. Negatives clamp to zero.
-
-### `frameToPercent(frame: number, totalFrames: number): number`
-
-Returns 0..100 (clamped). `totalFrames <= 0` returns 0.
-
-### `pxToFrame(clientX, rect, totalFrames): number`
-
-Maps a pointer X coordinate (relative to viewport) inside a `DOMRect`-shaped object to a frame index 0..totalFrames. Rounded.
-
-```ts
-pxToFrame(150, { left: 100, width: 200 } as DOMRect, 100)  // 25
-```
-
-### `pxToFraction(clientX, rect, inset?): number`
-
-Same as `pxToFrame` but returns a normalized 0..1 fraction. The optional `inset` shrinks the active range by that many pixels on each side (used internally for the volume slider).
-
-### `extensionForMimeType(mime: string): string`
-
-Maps common video MIME types to file extensions. Falls back to `'mp4'`.
-
-| MIME contains       | Extension |
-| ------------------- | --------- |
-| `webm`              | `webm`    |
-| `quicktime` / `mov` | `mov`     |
-| `matroska` / `mkv`  | `mkv`     |
-| anything else       | `mp4`     |
-
----
-
 ## `pixi-effects/three`
 
 Optional three.js integration, imported from its own entry so the core `pixi-effects` entry never touches three.js: