pixi-effects 0.2.0 → 0.3.0

package/dist/three.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunk7OIWYXGV_cjs = require('./chunk-7OIWYXGV.cjs');
+var chunkSIRVULFF_cjs = require('./chunk-SIRVULFF.cjs');
 var pixi_js = require('pixi.js');
 var three$1 = require('three');
 
-var ThreeSequence = class extends chunk7OIWYXGV_cjs.Sequence {
+var ThreeSequence = class extends chunkSIRVULFF_cjs.Sequence {
   _renderer = null;
   _scene = null;
   _camera = null;
@@ -23,7 +23,7 @@ var ThreeSequence = class extends chunk7OIWYXGV_cjs.Sequence {
     if (this.duration === void 0) {
       this.duration = this.parent?.duration ?? this.root.duration;
     }
-    const scope = chunk7OIWYXGV_cjs.buildScope(this, this.parent, this.root);
+    const scope = chunkSIRVULFF_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;
@@ -143,12 +143,12 @@ var ThreeSequence = class extends chunk7OIWYXGV_cjs.Sequence {
 function resolveDim(v, scope) {
   if (v === void 0) return void 0;
   if (typeof v === "number") return v;
-  return chunk7OIWYXGV_cjs.evaluateExpr(v, scope);
+  return chunkSIRVULFF_cjs.evaluateExpr(v, scope);
 }
 
 // src/three/index.ts
 function registerThree() {
-  chunk7OIWYXGV_cjs.registerSequenceType("three", ThreeSequence);
+  chunkSIRVULFF_cjs.registerSequenceType("three", ThreeSequence);
 }
 function three(spec) {
   return spec;

package/dist/three.d.cts

@@ -1,6 +1,6 @@
-import { a as SequenceCommon, n as PropValue, S as SequenceSpec } from './types-CNBilhpz.cjs';
+import { b as SequenceCommon, n as PropValue, S as SequenceSpec } from './types-3c8Vymgw.cjs';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-B1Tdn0Cv.cjs';
+import { S as Sequence, P as PathRouters } from './Base-BDw6dKRB.cjs';
 import 'pixi.js';
 import 'gsap';
 

package/dist/three.d.ts

@@ -1,6 +1,6 @@
-import { a as SequenceCommon, n as PropValue, S as SequenceSpec } from './types-CNBilhpz.js';
+import { b as SequenceCommon, n as PropValue, S as SequenceSpec } from './types-3c8Vymgw.js';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-Bh_VSusi.js';
+import { S as Sequence, P as PathRouters } from './Base-Ba4Ta4ap.js';
 import 'pixi.js';
 import 'gsap';
 

package/dist/three.js

@@ -1,4 +1,4 @@
-import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-VJCDG6YG.js';
+import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-PN5A6QA7.js';
 import { Texture, Sprite } from 'pixi.js';
 import { WebGLRenderer, Scene, PerspectiveCamera } from 'three';
 

package/dist/{types-CNBilhpz.d.cts → types-3c8Vymgw.d.cts}

@@ -13,9 +13,21 @@ type PropValue = number | string;
 type Props = Record<string, PropValue>;
 /** A single keyframe entry. Either `set`, `to`, `from`, or `from`+`to` is meaningful per kind. */
 interface Keyframe {
+    /**
+     * Start time in seconds, measured from the start of the sequence this
+     * keyframe belongs to (After Effects style): `0` = the moment the layer
+     * appears. Negative values count back from the sequence's end
+     * (`-0.5` = 0.5 s before it ends).
+     */
     at?: number;
     duration?: number;
     ease?: string;
+    /** Extra plays of this tween after the first (a finite count; infinite repeats are not allowed — the timeline needs a fixed length). Total time = duration × (repeat + 1) plus delays. */
+    repeat?: number;
+    /** With `repeat`: every other play runs backwards (there-and-back). */
+    yoyo?: boolean;
+    /** With `repeat`: seconds to wait between plays. */
+    repeatDelay?: number;
     set?: Props;
     to?: Props;
     from?: Props;
@@ -63,7 +75,7 @@ interface TransitionCommon {
     from: string;
     /** Sibling sequence's `name` — the incoming scene. Must be declared after `from` in the parent's `sequences[]`. */
     to: string;
-    /** Start time (parent-relative seconds). Same `at` semantics as Keyframe. */
+    /** Start time in the PARENT composition's time (like a sequence's `at`, not sequence-local). Negative = back from the parent's end. */
     at: number;
     /** Length of the transition in seconds. Must be > 0. */
     duration: number;
@@ -127,10 +139,11 @@ interface SequenceCommon {
     filters?: FilterSpec[];
     /**
      * Override PIXI's auto-computed filter region. By default, filters apply
-     * only inside the target's bounding box. Setting this to a parent-relative
-     * rectangle lets a filter (e.g. a wipe / iris transition) draw across an
-     * area larger than the sprite — useful when the sprite content is small
-     * but the visual effect should cover the whole composition.
+     * only inside the target's bounding box. This rectangle is in the layer's
+     * OWN coordinate space (origin = the layer's local origin, before its
+     * x/y/scale/rotation — e.g. a circle's centre), not the parent's. Use it to
+     * let a filter (blur, glow, a wipe / iris transition) draw beyond the
+     * layer's own bounds; without it a blur is clipped to the bounding box.
      */
     filterArea?: {
         x: number;
@@ -189,7 +202,17 @@ interface ImageSequenceSpec extends SequenceCommon {
 }
 interface TextSequenceSpec extends SequenceCommon {
     type: 'text';
+    /**
+     * The text. May contain `{value}`, replaced by the layer's animatable number
+     * `value` (a counter): `text: '{value} users'`, `initial: { value: 0 }`,
+     * keyframe `to: { value: 2480 }`. Format it with `format`.
+     */
     text?: string;
+    /** How `{value}` is printed: `decimals` (default 0) and thousands `grouping` (default false). */
+    format?: {
+        decimals?: number;
+        grouping?: boolean;
+    };
     /** Subset of PIXI v8 TextStyleOptions. String values may be exprs (e.g. fontSize: 'GW * 0.05'). */
     style?: Record<string, PropValue | {
         color?: PropValue;
@@ -225,8 +248,32 @@ interface CompositionSequenceSpec extends SequenceCommon {
 interface CameraSequenceSpec extends SequenceCommon {
     type: 'camera';
 }
+/**
+ * A gradient fill for a shape (replaces `fillColor`). Positions are relative to the shape's own
+ * bounds (0–1), so it follows the shape's size. Colours may have alpha (`'rgba(0,0,0,0.6)'`), so a
+ * radial gradient from transparent to dark is a vignette. Not animatable.
+ */
+interface GradientSpec {
+    /** Default `'linear'`. */
+    type?: 'linear' | 'radial';
+    /** Colour stops, `[offset 0–1, colour]` or `{ offset, color }`. At least two. */
+    stops: Array<[number, string | number] | {
+        offset: number;
+        color: string | number;
+    }>;
+    /** linear: direction in degrees — 0 = left → right, 90 = top → bottom (default). */
+    angle?: number;
+    /** radial: centre in 0–1 of the bounds. Default `[0.5, 0.5]`. */
+    center?: [number, number];
+    /** radial: inner radius where the first stop applies, 0–1. Default 0. */
+    innerRadius?: number;
+    /** radial: outer radius where the last stop applies, 0–1. Default 0.5. */
+    radius?: number;
+}
 interface ShapeBase extends SequenceCommon {
     type: 'shape';
+    /** Fill with a gradient instead of `fillColor` (top level or in `initial`). */
+    fillGradient?: GradientSpec;
     /**
      * Colour space used to interpolate `fillColor` / `strokeColor` keyframes.
      *
@@ -317,4 +364,4 @@ interface AudioDescriptor {
     }[];
 }
 
-export type { AssetSpec as A, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, SequenceCommon as a, AudioSequenceSpec as b, CameraSequenceSpec as c, ChromaKeyFilterSpec as d, CircleShapeSpec as e, CompositionSequenceSpec as f, CompositionSpec as g, CrossfadeTransition as h, CustomFilterSpec as i, DissolveTransition as j, Expr as k, IrisTransition as l, PolygonShapeSpec as m, PropValue as n, Props as o, ShapeSequenceSpec as p, SlideTransition as q, TransitionCommon as r, TransitionSpec as s, AudioDescriptor as t };
+export type { AssetSpec as A, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AudioSequenceSpec as c, ChromaKeyFilterSpec as d, CircleShapeSpec as e, CompositionSequenceSpec as f, CompositionSpec as g, CrossfadeTransition as h, CustomFilterSpec as i, DissolveTransition as j, Expr as k, IrisTransition as l, PolygonShapeSpec as m, PropValue as n, Props as o, ShapeSequenceSpec as p, SlideTransition as q, TransitionCommon as r, TransitionSpec as s, AudioDescriptor as t };

package/dist/{types-CNBilhpz.d.ts → types-3c8Vymgw.d.ts}

@@ -13,9 +13,21 @@ type PropValue = number | string;
 type Props = Record<string, PropValue>;
 /** A single keyframe entry. Either `set`, `to`, `from`, or `from`+`to` is meaningful per kind. */
 interface Keyframe {
+    /**
+     * Start time in seconds, measured from the start of the sequence this
+     * keyframe belongs to (After Effects style): `0` = the moment the layer
+     * appears. Negative values count back from the sequence's end
+     * (`-0.5` = 0.5 s before it ends).
+     */
     at?: number;
     duration?: number;
     ease?: string;
+    /** Extra plays of this tween after the first (a finite count; infinite repeats are not allowed — the timeline needs a fixed length). Total time = duration × (repeat + 1) plus delays. */
+    repeat?: number;
+    /** With `repeat`: every other play runs backwards (there-and-back). */
+    yoyo?: boolean;
+    /** With `repeat`: seconds to wait between plays. */
+    repeatDelay?: number;
     set?: Props;
     to?: Props;
     from?: Props;
@@ -63,7 +75,7 @@ interface TransitionCommon {
     from: string;
     /** Sibling sequence's `name` — the incoming scene. Must be declared after `from` in the parent's `sequences[]`. */
     to: string;
-    /** Start time (parent-relative seconds). Same `at` semantics as Keyframe. */
+    /** Start time in the PARENT composition's time (like a sequence's `at`, not sequence-local). Negative = back from the parent's end. */
     at: number;
     /** Length of the transition in seconds. Must be > 0. */
     duration: number;
@@ -127,10 +139,11 @@ interface SequenceCommon {
     filters?: FilterSpec[];
     /**
      * Override PIXI's auto-computed filter region. By default, filters apply
-     * only inside the target's bounding box. Setting this to a parent-relative
-     * rectangle lets a filter (e.g. a wipe / iris transition) draw across an
-     * area larger than the sprite — useful when the sprite content is small
-     * but the visual effect should cover the whole composition.
+     * only inside the target's bounding box. This rectangle is in the layer's
+     * OWN coordinate space (origin = the layer's local origin, before its
+     * x/y/scale/rotation — e.g. a circle's centre), not the parent's. Use it to
+     * let a filter (blur, glow, a wipe / iris transition) draw beyond the
+     * layer's own bounds; without it a blur is clipped to the bounding box.
      */
     filterArea?: {
         x: number;
@@ -189,7 +202,17 @@ interface ImageSequenceSpec extends SequenceCommon {
 }
 interface TextSequenceSpec extends SequenceCommon {
     type: 'text';
+    /**
+     * The text. May contain `{value}`, replaced by the layer's animatable number
+     * `value` (a counter): `text: '{value} users'`, `initial: { value: 0 }`,
+     * keyframe `to: { value: 2480 }`. Format it with `format`.
+     */
     text?: string;
+    /** How `{value}` is printed: `decimals` (default 0) and thousands `grouping` (default false). */
+    format?: {
+        decimals?: number;
+        grouping?: boolean;
+    };
     /** Subset of PIXI v8 TextStyleOptions. String values may be exprs (e.g. fontSize: 'GW * 0.05'). */
     style?: Record<string, PropValue | {
         color?: PropValue;
@@ -225,8 +248,32 @@ interface CompositionSequenceSpec extends SequenceCommon {
 interface CameraSequenceSpec extends SequenceCommon {
     type: 'camera';
 }
+/**
+ * A gradient fill for a shape (replaces `fillColor`). Positions are relative to the shape's own
+ * bounds (0–1), so it follows the shape's size. Colours may have alpha (`'rgba(0,0,0,0.6)'`), so a
+ * radial gradient from transparent to dark is a vignette. Not animatable.
+ */
+interface GradientSpec {
+    /** Default `'linear'`. */
+    type?: 'linear' | 'radial';
+    /** Colour stops, `[offset 0–1, colour]` or `{ offset, color }`. At least two. */
+    stops: Array<[number, string | number] | {
+        offset: number;
+        color: string | number;
+    }>;
+    /** linear: direction in degrees — 0 = left → right, 90 = top → bottom (default). */
+    angle?: number;
+    /** radial: centre in 0–1 of the bounds. Default `[0.5, 0.5]`. */
+    center?: [number, number];
+    /** radial: inner radius where the first stop applies, 0–1. Default 0. */
+    innerRadius?: number;
+    /** radial: outer radius where the last stop applies, 0–1. Default 0.5. */
+    radius?: number;
+}
 interface ShapeBase extends SequenceCommon {
     type: 'shape';
+    /** Fill with a gradient instead of `fillColor` (top level or in `initial`). */
+    fillGradient?: GradientSpec;
     /**
      * Colour space used to interpolate `fillColor` / `strokeColor` keyframes.
      *
@@ -317,4 +364,4 @@ interface AudioDescriptor {
     }[];
 }
 
-export type { AssetSpec as A, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, SequenceCommon as a, AudioSequenceSpec as b, CameraSequenceSpec as c, ChromaKeyFilterSpec as d, CircleShapeSpec as e, CompositionSequenceSpec as f, CompositionSpec as g, CrossfadeTransition as h, CustomFilterSpec as i, DissolveTransition as j, Expr as k, IrisTransition as l, PolygonShapeSpec as m, PropValue as n, Props as o, ShapeSequenceSpec as p, SlideTransition as q, TransitionCommon as r, TransitionSpec as s, AudioDescriptor as t };
+export type { AssetSpec as A, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AudioSequenceSpec as c, ChromaKeyFilterSpec as d, CircleShapeSpec as e, CompositionSequenceSpec as f, CompositionSpec as g, CrossfadeTransition as h, CustomFilterSpec as i, DissolveTransition as j, Expr as k, IrisTransition as l, PolygonShapeSpec as m, PropValue as n, Props as o, ShapeSequenceSpec as p, SlideTransition as q, TransitionCommon as r, TransitionSpec as s, AudioDescriptor as t };

package/docs/api.md

@@ -0,0 +1,333 @@
+# API Reference
+
+- [`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).
+
+---
+
+## `Movie`
+
+Imported from `pixi-effects`.
+
+```ts
+import { Movie } from 'pixi-effects';
+
+const movie = new Movie();
+await movie.init({ /* ... */ });
+movie.play();
+```
+
+### Constructor
+
+```ts
+new Movie()
+```
+
+No arguments. State is fully populated by `init()`.
+
+### `movie.init(options): Promise<void>`
+
+Loads assets, builds the composition tree, mixes audio, and renders frame 0.
+
+```ts
+interface MovieOptions {
+  width?:      number;              // canvas pixels  (default 1920)
+  height?:     number;              // canvas pixels  (default 1080)
+  duration?:   number;              // seconds         (default 10)
+  frameRate?:  number;              // fps             (default 30)
+  background?: string;              // CSS color hex   (default '#000000')
+  canvas?:     HTMLCanvasElement;   // existing canvas to render into; otherwise PixiJS creates one
+  assets?:     AssetSpec[];         // [{ name, src }]
+  composition?: CompositionSpec;    // root composition (see DSL reference)
+}
+```
+
+Resolves once the composition is ready and the first frame has been rendered. Emits the `ready` event.
+
+### `movie.play(): void`
+
+Starts the requestAnimationFrame loop that drives `gotoFrame()` per tick. If `currentFrame >= totalFrames`, restarts from 0.
+
+If audio sources exist, schedules them on the AudioContext at the appropriate offsets.
+
+### `movie.pause(): void`
+
+Stops the rAF loop and any playing audio. Emits `'pause'` only when the previous state was playing (so calling `pause()` on an already-paused movie is a no-op for listeners).
+
+### `movie.gotoFrame(frame, force?): Promise<void>`
+
+```ts
+gotoFrame(frame: number, force?: boolean): Promise<void>
+```
+
+Seeks to a specific frame. Pauses if currently playing? **No** — does not change `isPlaying`. Updates `timeline.time()`, awaits any video frame readiness, renders, and emits `'frame'`.
+
+`force=true` skips the early-return when the requested frame equals `currentFrame`. Use it after a composition rebuild.
+
+### `movie.snapshot(frame?, options?): Promise<Blob | string>`
+
+```ts
+snapshot(frame?: number, options?: { scale?: number; type?: 'image/png' | 'image/jpeg'; as?: 'blob' | 'dataURL' }): Promise<Blob | string>
+```
+
+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.
+
+### `movie.contactSheet(options?): Promise<Blob | string>`
+
+```ts
+contactSheet(options?: {
+  frames?: number[]; times?: number[]; count?: number;   // which frames: explicit, in seconds, or `count` evenly spread (default 6)
+  columns?: number;                                       // default 3
+  cellWidth?: number;                                     // picture width in px, default 480
+  as?: 'blob' | 'dataURL';
+}): Promise<Blob | string>
+```
+
+Many frames on **one** PNG, each labelled `frame N · T s`. The cheapest way to check a whole animation by eye (include the middle of every transition and the last second). Restores the current frame afterwards.
+
+### `movie.inspect(frame?, options?): Promise<InspectReport>`
+
+Where every layer is drawn at `frame`, as JSON — for checking layout without eyes. Seeks there and stays there. `options.layers`: `'visible'` (default, only layers drawn at this frame), `'all'`, or `'none'` (just `summary` and `issues`). Faint layers (alpha < 0.3) and text whose x / y is animated (tickers) are not reported.
+
+```ts
+interface InspectReport {
+  frame: number; time: number; canvas: { width: number; height: number };
+  summary: { layers: number; visible: number };
+  issues: string[];              // text off the canvas / cut by an edge / empty / overlapping other text — read this first
+  layers: Array<{
+    path: string;                // names (or type#index) from the root, joined by '/'
+    name?: string; type: string; threeD: boolean;
+    visible: boolean;            // alive at this frame, not hidden by an ancestor, alpha > 0
+    alpha: number;
+    bounds: { x: number; y: number; width: number; height: number } | null;   // canvas pixels; null inside a threeD layer
+    onCanvas: 'full' | 'partial' | 'none' | null;
+  }>;
+}
+```
+
+### `movie.render(options?): Promise<Blob>`
+
+Renders the entire timeline to a single video file. Pauses playback first.
+
+```ts
+interface RenderOptions {
+  format?: 'mp4' | 'mov' | 'webm' | 'mkv';   // default 'mp4'
+  video?: {
+    codec?:   string;   // default per format (mp4/mov→avc, webm/mkv→vp9)
+    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';   // default 'high'
+  };
+  audio?: {
+    codec?:   string;   // default per format (mp4/mov→aac, webm/mkv→opus)
+    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';   // default 'high'
+  };
+}
+```
+
+Returns a `Blob` whose `type` is the container's MIME (e.g. `video/mp4`). Emits `'progress'` repeatedly during the render.
+
+The renderer also forces a keyframe every ~2 seconds so the resulting file scrubs efficiently in standard players.
+
+### `movie.destroy(): Promise<void>`
+
+Pauses playback, destroys the underlying PIXI Application, releases audio buffers and AudioContext, and marks the instance unusable.
+
+### Events
+
+```ts
+movie.on(event, fn): this
+movie.off(event, fn): this
+```
+
+| Event       | Payload                                           | Fired                                                 |
+| ----------- | ------------------------------------------------- | ----------------------------------------------------- |
+| `'ready'`   | none                                              | once, after `init()` resolves                         |
+| `'frame'`   | `{ frame: number; totalFrames: number }`          | every `gotoFrame` (so once per playback frame too)    |
+| `'pause'`   | none                                              | when `pause()` actually transitions from playing      |
+| `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
+
+`progress` is `0..100` (rounded integer percent).
+
+### Public properties
+
+| Property         | Type      | Notes                                                   |
+| ---------------- | --------- | ------------------------------------------------------- |
+| `isPlaying`      | boolean   | true while the rAF loop is active                       |
+| `currentFrame`   | number    | 0-based current frame                                   |
+| `totalFrames`    | number    | `Math.round(duration * frameRate)`                      |
+| `frameRate`      | number    | from `init`                                             |
+| `duration`       | number    | seconds                                                 |
+| `width`, `height`| number    | canvas pixels                                           |
+| `background`     | string    | CSS color                                               |
+| `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)              |
+
+### `movie.toggleMute(): boolean`
+
+Flips `muted` and returns the new value.
+
+---
+
+## `Controller`
+
+Imported from `pixi-effects/controller`.
+
+```ts
+import { Controller } from 'pixi-effects/controller';
+
+const ctrl = new Controller(movie, { canvas });
+// later:
+ctrl.destroy();
+```
+
+A YouTube-style overlay anchored to the canvas:
+
+```
+[▶] [🔉━━━] 0:00 / 0:08 ··· [⬇] [⛶]
+└── play   └── volume   └── time     └── export   └── fullscreen
+```
+
+The bar auto-hides 2.5s after pointer activity stops (in both playing and paused state) and reappears on pointer move. Clicking the download icon opens a popover with format/quality selectors and a `Download` confirm button. Fullscreen scales the canvas + bar to the viewport.
+
+### Constructor
+
+```ts
+new Controller(movie: Movie, options: ControllerOptions)
+
+interface ControllerOptions {
+  canvas: HTMLCanvasElement;          // required
+  showExportButton?: boolean;         // default true; hides ⬇ + popover
+  enableKeyboardShortcuts?: boolean;  // default true
+  className?: string;                 // default 'movie-controller'
+}
+```
+
+Mounting strategy:
+
+- If `canvas.parentElement` already has a non-static `position`, the controller is appended directly into it.
+- Otherwise the canvas is wrapped in a `<div class="movie-controller-wrap">` (with `position: relative`). The wrapper is removed on `destroy()`.
+
+### `controller.destroy(): void`
+
+Idempotent. Removes:
+
+- the controller bar DOM
+- all listeners (Movie events, document keydown/pointerdown/fullscreenchange, wrapper pointermove/mouseleave)
+- the auto-hide timer
+- the wrapper, if it was created here
+- the injected stylesheet (ref-counted across multiple controllers)
+
+If the controller still owns `document.fullscreenElement`, it calls `exitFullscreen()`.
+
+### Export popover
+
+Format options: **MP4**, **WebM**, **MOV** (mp4 ↔ avc/aac, webm ↔ vp9/opus, mov ↔ avc/aac).
+
+Quality options: **Low**, **Medium**, **High** (default), **Very High**.
+
+These map directly to `Movie.render()`'s `format` and `video.bitrate` / `audio.bitrate` parameters. Selection persists for the lifetime of the controller instance (no localStorage).
+
+The download is triggered by an in-page `<a download>` click, so the file lands in the browser's default download location with a name like `movie-{YYYYMMDD-HHMMSS}.{ext}`.
+
+### Keyboard shortcuts
+
+Active when `enableKeyboardShortcuts: true` and the key target is not `<input>`/`<textarea>`/`<select>`/contenteditable.
+
+| Key         | Action                                              |
+| ----------- | --------------------------------------------------- |
+| `Space`     | play / pause                                        |
+| `←` / `→`   | step ±1 frame                                       |
+| `↑` / `↓`   | volume ±5% (clears mute when increasing past zero)  |
+| `M`         | toggle mute                                         |
+| `Shift+E`   | export with current settings (skips the popover)    |
+| `F`         | toggle fullscreen                                   |
+| `Esc`       | close the export popover or exit fullscreen (browser) |
+
+### Theming
+
+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:
+
+```ts
+import { registerThree, three, ThreeSequence } from 'pixi-effects/three';
+```
+
+**Install:** `npm i three`. `three` is a peer dependency marked optional (`peerDependenciesMeta.three.optional = true`) — consumers who never import `pixi-effects/three` are unaffected either way.
+
+For the `type: 'three'` spec shape (fields, keyframe paths, rules), see [DSL reference § three](./dsl.md#three).
+
+### `registerThree(): void`
+
+Registers the `'three'` sequence type with the composition builder. Call once, before `Movie.init()` builds a composition containing a `type: 'three'` sequence. Idempotent.
+
+### `three(spec: ThreeSequenceSpec): SequenceSpec`
+
+Typing helper — accepts a strongly-typed three spec and returns it as a plain `SequenceSpec`, so it drops straight into `composition.sequences` alongside `text` / `image` / etc. A cast only; not required for the sequence to work, but gives editor autocomplete on `setup` / `update` / `dispose`.
+
+### `ThreeSequence`
+
+The `Sequence` subclass that backs `type: 'three'`. Exported for advanced use (e.g. `instanceof` checks); most consumers only need `registerThree()` and `three()`.
+
+### Exported types
+
+```ts
+import type { ThreeContext, ThreeSetupResult, ThreeSequenceSpec } from 'pixi-effects/three';
+```
+
+| Type                | Notes                                                                          |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `ThreeContext`      | `{ scene, camera, renderer, width, height }` handed to `setup` / `update` / `dispose`. |
+| `ThreeSetupResult`  | `{ objects?, camera? }` returned from `setup`.                                 |
+| `ThreeSequenceSpec` | the `type: 'three'` sequence spec.                                             |