pixi-effects 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.9.0
+
+**Added**
+
+- **Poster time.** `movie.init({ poster: 9.5 })` names the moment that stands for the movie (a negative value counts back from the end). Once the movie is ready the canvas shows that frame while the playhead stays at 0, and play still starts from 0, like `<video poster>` but derived from the same data, with no separate image file. `movie.poster`, `movie.posterFrame` and `movie.posterImage()` (a `snapshot()` at the poster time that leaves the movie as it was); `pixi-effects-check` writes `poster.jpg`. The gallery uses it: every piece declares `poster` once (the `?poster` handling copied into all 33 pieces and `posterFrame` in their meta are gone), `node scripts/make-posters.mjs` takes the posters and writes `posters/manifest.json` (with a hash of each page, so a poster that is out of date fails a test).
+- A guide for people, as a standalone site on GitHub Pages (`/guide/`, next to the gallery and the live demos): your first video, how it works, guides for text, shapes, images and video, audio, filters, transitions, 2.5D, exporting, the player and reviewing, a cookbook of tested recipes with live demos, a page on working with an AI, and a FAQ. It puts the AI-development tools up front: `check`, the contact sheet, the timeline and viewer, `inspect`, `inspectAudio` and `render`. Pages are markdown in `site/guide/`, built to HTML by `scripts/build-guide.mjs` (`npm run guide` previews it in `guide-preview/`); the recipes in them are built and linted by the tests, and the first-video page is a real file checked in Chrome.
+
 ## 0.8.0
 
 **Added**

package/README.md

@@ -1,8 +1,8 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.8.0`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.8.0` adds events and a theme for building your own player, `0.7.0` adds filters by name, the `pixi-effects-render` and `pixi-effects-view` commands and the timeline chart, `0.6.0` adds draw-on strokes (`trimEnd`) and text that changes over time, `0.5.0` adds synthesised sound effects (`sfx`, no files) and the `check` tool, `0.4.0` makes a mask share its layer's lifetime, `0.3.0` made keyframe `at` relative to the layer).
+> **Status**: experimental — current release `0.9.0`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.9.0` adds a poster time (`movie.init({ poster })`) and a guide site, `0.8.0` adds events and a theme for building your own player, `0.7.0` adds filters by name, the `pixi-effects-render` and `pixi-effects-view` commands and the timeline chart, `0.6.0` adds draw-on strokes (`trimEnd`) and text that changes over time, `0.5.0` adds synthesised sound effects (`sfx`, no files) and the `check` tool, `0.4.0` makes a mask share its layer's lifetime, `0.3.0` made keyframe `at` relative to the layer).
 
-**[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 33 portfolio pieces written as plain data by AI models · **[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
+**[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 33 portfolio pieces written as plain data by AI models · **[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
 
 Declarative composition and video rendering for the web. After Effects-style timelines on top of [PixiJS v8](https://pixijs.com/) and [GSAP](https://gsap.com/), with strict TypeScript types. Render to MP4 / WebM / MOV via [mediabunny](https://mediabunny.dev/).
 
@@ -40,8 +40,8 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
     "gsap":                    "https://esm.sh/gsap@3.12.5",
     "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
     "mediabunny":              "https://esm.sh/mediabunny",
-    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.8.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.8.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.9.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.9.0/dist/Controller.js"
   }
 }
 </script>
@@ -52,7 +52,7 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
 </script>
 ```
 
-Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.8.0/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
+Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.9.0/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
 
 > **Using three.js?** Add two more entries (`three` and `pixi-effects/three`) to this importmap — see [Adding three.js](#adding-threejs-optional) below.
 >
@@ -68,7 +68,7 @@ Add two more entries to the importmap above: three.js itself, and the `pixi-effe
   "imports": {
     "...":                     "(everything from the importmap above)",
     "three":                   "https://esm.sh/three@0.178.0",
-    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.8.0/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.9.0/dist/three.js"
   }
 }
 </script>

package/ai/SKILL.md

@@ -10,16 +10,17 @@ You describe a video as a tree of plain objects; the library plays it in a canva
 ## Workflow
 
 1. **Start from `template.html`** (copy it; it loads the library from a CDN, collects every console warning into `window.__logs`, and exposes `window.movie`). One HTML file, plain JS. Default canvas 1280×720 @ 30 fps.
-2. **Write the composition as data.** Anything repeated (letters, bars, particles, scenes) is a JS function or loop that returns specs — never copy-paste objects. Derive coordinates and times from constants/data, not magic numbers.
-3. **Show the human:** `node ai/tools/view.mjs my-video.html` opens their browser on the page with a scrubbable, zoomable timeline under it (click / drag to seek, + / − or Ctrl/⌘ + wheel to zoom) (`npx pixi-effects-view …` in an installed package); it keeps running until Ctrl-C. **Deliver the file:** `node ai/tools/render.mjs my-video.html -o my-video.mp4` (`npx pixi-effects-render …` in an installed package) renders the page headless to mp4 / webm / mov / mkv and exits 0 only when the file is written; run it AFTER the check below passes. **Run the check — one command does steps 3, 4 and the export:** `node ai/tools/check.mjs my-video.html` (Node ≥ 22 and Chrome installed; no npm install; in an installed package it is `npx pixi-effects-check my-video.html`). It starts its own private Chrome (nothing is shared with other sessions), waits for `window.__ready`, and writes `timeline.html` (every layer as a bar on a time axis: ◆ keyframes, shaded transitions; hand it to the human to open) and prints: console warnings, `movie.inspect` over the WHOLE timeline (grouped), `movie.inspectAudio()`, then exports an mp4 and decodes it again (video size and length, audio length, loudness per second, silence). It writes `check-out/<name>/sheet.png` — **open that picture and look at it** — plus the mp4 and `report.json`. Exit 0 = nothing to fix; exit 1 = a list of problems; fix them and run it again. Text that overlaps text is listed under `review` (not a failure: ghost layers, glow copies and per-letter boxes are often intentional; look at the sheet; `--strict` makes them fail). The manual steps below are for looking at one frame closely.
+2. **Give the movie a poster time.** In `movie.init` add `poster: <seconds>`: the most striking moment (a title fully on screen, not the first frame, which is often black). The canvas shows that picture before play (the playhead stays at 0 and play starts from 0), and the check writes it as `poster.jpg`.
+3. **Write the composition as data.** Anything repeated (letters, bars, particles, scenes) is a JS function or loop that returns specs — never copy-paste objects. Derive coordinates and times from constants/data, not magic numbers.
+4. **Show the human:** `node ai/tools/view.mjs my-video.html` opens their browser on the page with a scrubbable, zoomable timeline under it (click / drag to seek, + / − or Ctrl/⌘ + wheel to zoom) (`npx pixi-effects-view …` in an installed package); it keeps running until Ctrl-C. **Deliver the file:** `node ai/tools/render.mjs my-video.html -o my-video.mp4` (`npx pixi-effects-render …` in an installed package) renders the page headless to mp4 / webm / mov / mkv and exits 0 only when the file is written; run it AFTER the check below passes. **Run the check — one command does steps 3, 4 and the export:** `node ai/tools/check.mjs my-video.html` (Node ≥ 22 and Chrome installed; no npm install; in an installed package it is `npx pixi-effects-check my-video.html`). It starts its own private Chrome (nothing is shared with other sessions), waits for `window.__ready`, and writes `timeline.html` (every layer as a bar on a time axis: ◆ keyframes, shaded transitions; hand it to the human to open) and prints: console warnings, `movie.inspect` over the WHOLE timeline (grouped), `movie.inspectAudio()`, then exports an mp4 and decodes it again (video size and length, audio length, loudness per second, silence). It writes `check-out/<name>/sheet.png` — **open that picture and look at it** — plus the mp4 and `report.json`. Exit 0 = nothing to fix; exit 1 = a list of problems; fix them and run it again. Text that overlaps text is listed under `review` (not a failure: ghost layers, glow copies and per-letter boxes are often intentional; look at the sheet; `--strict` makes them fail). The manual steps below are for looking at one frame closely.
    **Or by hand: run it and read the logs first.** `window.__ready` must be `true` and `window.__logs` should be `[]`. A pixi-effects warning is an instruction: fix what it names.
-4. **Look at it** — you cannot judge motion from code. The library has the tools built in:
+5. **Look at it** — you cannot judge motion from code. The library has the tools built in:
    - `await movie.contactSheet({ count: 6, as: 'dataURL' })` → ONE image of several labelled frames (pass `frames: [...]` / `times: [...]` to choose; include the middle of every transition and the last second). Save it and view it.
    - `await movie.inspect(frame)` → every layer's canvas bounds and visibility, plus `issues` (text off the canvas, cut off by an edge, empty, or overlapping other text). Run it at several frames; fix every issue it names.
    - `await movie.snapshot(frame, { as: 'dataURL' })` → one frame, canvas only (no player bar).
    - `movie.inspectAudio()` → **hear with numbers**: for every sound its `start`, `sound.length`, `sound.peakDb`, `sound.loudestAt` (line this up with the picture) and `sound.brightnessHz` (< 500 dark, > 8000 airy), plus `issues` (limited mix, inaudible or cut-off sounds). Check it whenever the movie has audio; `render()` encodes this same mix.
    From a browser tool the result is a `data:` URL string: `agent-browser eval "movie.contactSheet({ count: 6, as: 'dataURL' })" | python3 ai/tools/save-image.py /absolute/sheet.png`, then open the PNG. Sheet tiles are small (~480 px): use `snapshot` for detail. `inspect` output is long on busy scenes: pass `{ layers: 'none' }` and read `issues` first. Give layers a `name` so inspect paths are readable. A moving ticker is not flagged as cut off.
-5. **Iterate** on what you saw (clipped text, collisions, wrong timing). Then export: `const blob = await movie.render({ format: 'mp4' })` (about real time; `movie.on('progress', …)` reports 0–100).
+6. **Iterate** on what you saw (clipped text, collisions, wrong timing). Then export: `const blob = await movie.render({ format: 'mp4' })` (about real time; `movie.on('progress', …)` reports 0–100).
 
 ## The rules that cause most failures
 
@@ -43,7 +44,7 @@ Centred text must be positioned by `anchorX/anchorY: 0.5`; estimate text width a
 - `reference/cheatsheet.md` — every layer type, prop, default and rule on one page.
 - `reference/recipes.md` — tested building blocks: slam type, lower-third, marquee, count-up, bar chart, 2.5D title, camera orbit, slideshow with transitions + music, looping, particles, gradients/vignette, three.js metal.
 - `reference/pitfalls.md` — the full list of real mistakes, with status.
-- `tools/check.mjs` — the one-command review (see Workflow step 3).
+- `tools/check.mjs` — the one-command review (see Workflow step 5).
 - `template.html` — the starting file. (It loads the library from a CDN; when testing against a local build, point the three `pixi-effects*` importmap entries at `../../dist/…`.)
 - `tools/save-image.py` — save a `dataURL` result (contact sheet / snapshot) to a PNG.
 - Full reference: `docs/dsl.md` and `docs/api.md` in the repository.

package/ai/reference/cheatsheet.md

@@ -83,6 +83,10 @@ Style (`initial` / keyframes): `fillColor fillAlpha strokeColor strokeAlpha stro
 
 Add `threeD: true` to any visual layer, then use `z`, `rotationX`, `rotationY` (centre rotation with `anchorX/Y: 0.5` or `pivotX/Y`). Add a `{ type: 'camera' }` layer for a view. A `threeD` layer at `z: 0` with the default camera looks identical to a 2D one. Consecutive `threeD` layers are drawn farthest-first (equal `z` keeps array order); non-`threeD` layers ignore the camera and keep array order. Layers at/behind the camera plane are hidden. Not supported on `threeD` layers: masks, transitions, `filterArea`.
 
+## Poster
+
+`movie.init({ …, poster: 9.5 })` names the moment (seconds; negative = from the end) that stands for the movie: the canvas shows it before play (the playhead stays at 0, play starts from 0), `movie.poster` / `movie.posterFrame` read it, `await movie.posterImage({ as: 'dataURL', type: 'image/jpeg', scale: 0.5 })` is the picture. Pick the most striking moment, not frame 0 (which is often black).
+
 ## Player
 
 `new Controller(movie, { canvas, theme: { accent: '#ff4d6d' } })` (import from `pixi-effects/controller`; theme keys `accent foreground track barBackground trackHeight font`, or CSS `--mc-accent` …; `controller.setTheme(…)`). Your own player: `movie.play() pause() gotoFrame(f) volume muted toggleMute()`, state `currentFrame totalFrames frameRate duration isPlaying`, events `ready frame play pause ended seeking seeked volumechange error progress` (`<video>` names). `examples/15-custom-player.html` is a complete one.

package/ai/template.html

@@ -36,9 +36,9 @@
       "gsap":                    "https://esm.sh/gsap@3.12.5",
       "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
       "mediabunny":              "https://esm.sh/mediabunny",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.8.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.8.0/dist/Controller.js",
-      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.8.0/dist/three.js",
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.9.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.9.0/dist/Controller.js",
+      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.9.0/dist/three.js",
       "pixi-filters":            "https://esm.sh/pixi-filters@6.1.5?external=pixi.js",
       "three":                   "https://esm.sh/three@0.178.0"
     }
@@ -73,6 +73,7 @@
       await movie.init({
         canvas: document.getElementById('stage'),
         width: W, height: H, duration: DURATION, frameRate: FPS,
+        poster: DURATION * 0.75,        // the moment that stands for the video before it plays (pick your most striking one)
         background: '#0a0a0f',
         // assets: [{ name: 'photo', src: './photo.jpg' }, { name: 'bgm', src: './bgm.mp3' }],
         composition: { sequences },

package/ai/tools/check.mjs

@@ -279,6 +279,14 @@ export async function runCheck(opts, log = console.log) {
     fs.writeFileSync(sheetFile, Buffer.from(sheet.slice(sheet.indexOf(',') + 1), 'base64'));
     report.files.sheet = shown(sheetFile);
 
+    // the poster: the picture that stands for the movie (its poster time, or the first frame)
+    const poster = await cdp.eval(`movie.posterImage({ as: 'dataURL', type: 'image/jpeg', scale: 0.5 })`).catch(() => null);
+    if (poster) {
+      const posterFile = path.join(outDir, 'poster.jpg');
+      fs.writeFileSync(posterFile, Buffer.from(poster.slice(poster.indexOf(',') + 1), 'base64'));
+      report.files.poster = shown(posterFile);
+    }
+
     // the timeline: every layer as a bar on a time axis (for a human to open in a browser)
     const timeline = await cdp.eval(`movie.timelineChart({ title: ${JSON.stringify(name)} })`).catch(() => null);
     if (timeline) {

package/dist/Controller.d.cts

@@ -1,4 +1,4 @@
-import { M as Movie } from './Movie-CQOhUmko.cjs';
+import { M as Movie } from './Movie-qGHp15c_.cjs';
 import 'pixi.js';
 import 'gsap';
 import './types-oJijbn-K.cjs';

package/dist/Controller.d.ts

@@ -1,4 +1,4 @@
-import { M as Movie } from './Movie-HF3pSGjQ.js';
+import { M as Movie } from './Movie-QMlFyHkf.js';
 import 'pixi.js';
 import 'gsap';
 import './types-oJijbn-K.js';

package/dist/{Movie-HF3pSGjQ.d.ts → Movie-QMlFyHkf.d.ts}

@@ -140,6 +140,12 @@ interface MovieOptions {
     canvas?: HTMLCanvasElement;
     assets?: AssetSpec[];
     composition?: CompositionSpec;
+    /**
+     * The poster time in seconds: the moment that stands for the movie before it plays. The canvas shows that frame once the movie is
+     * ready, the playhead stays at 0 and play starts from 0 (like `<video poster>`); `movie.posterImage()` is that picture. A negative
+     * value counts back from the end. Default: none (the first frame).
+     */
+    poster?: number;
 }
 interface RenderOptions {
     format?: 'mp4' | 'mov' | 'webm' | 'mkv';
@@ -203,6 +209,11 @@ declare class Movie {
     audioSource: AudioBufferSourceNode | null;
     gainNode: GainNode | null;
     private _cancelAudioStart;
+    /** The poster time in seconds (`movie.init({ poster })`), or null. */
+    poster: number | null;
+    private _posterFrame;
+    /** The canvas shows the poster picture while the playhead is still at frame 0 (like `<video poster>`): the first seek or play replaces it. */
+    private _atPoster;
     /** > 0 while the movie moves its own playhead (playback, render, snapshot, contactSheet): those are not the seeks `seeking` / `seeked` report. */
     private _quiet;
     private _volume;
@@ -236,6 +247,20 @@ declare class Movie {
     off(event: string, fn: Listener): this;
     emit(event: string, ...args: unknown[]): void;
     get isReady(): boolean;
+    /** The poster time as a frame number, or null. */
+    get posterFrame(): number | null;
+    /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */
+    private _showPoster;
+    /**
+     * The picture at the poster time (frame 0 if the movie has none), as `snapshot()` returns it, and the movie is left as it was:
+     * still showing the poster, or back at the frame it was at.
+     */
+    posterImage(opts?: SnapshotOptions & {
+        as?: 'blob';
+    }): Promise<Blob>;
+    posterImage(opts: SnapshotOptions & {
+        as: 'dataURL';
+    }): Promise<string>;
     private _ensureAudioContext;
     init(options?: MovieOptions): Promise<void>;
     gotoFrame(frame: number, force?: boolean): Promise<void>;

package/dist/{Movie-CQOhUmko.d.cts → Movie-qGHp15c_.d.cts}

@@ -140,6 +140,12 @@ interface MovieOptions {
     canvas?: HTMLCanvasElement;
     assets?: AssetSpec[];
     composition?: CompositionSpec;
+    /**
+     * The poster time in seconds: the moment that stands for the movie before it plays. The canvas shows that frame once the movie is
+     * ready, the playhead stays at 0 and play starts from 0 (like `<video poster>`); `movie.posterImage()` is that picture. A negative
+     * value counts back from the end. Default: none (the first frame).
+     */
+    poster?: number;
 }
 interface RenderOptions {
     format?: 'mp4' | 'mov' | 'webm' | 'mkv';
@@ -203,6 +209,11 @@ declare class Movie {
     audioSource: AudioBufferSourceNode | null;
     gainNode: GainNode | null;
     private _cancelAudioStart;
+    /** The poster time in seconds (`movie.init({ poster })`), or null. */
+    poster: number | null;
+    private _posterFrame;
+    /** The canvas shows the poster picture while the playhead is still at frame 0 (like `<video poster>`): the first seek or play replaces it. */
+    private _atPoster;
     /** > 0 while the movie moves its own playhead (playback, render, snapshot, contactSheet): those are not the seeks `seeking` / `seeked` report. */
     private _quiet;
     private _volume;
@@ -236,6 +247,20 @@ declare class Movie {
     off(event: string, fn: Listener): this;
     emit(event: string, ...args: unknown[]): void;
     get isReady(): boolean;
+    /** The poster time as a frame number, or null. */
+    get posterFrame(): number | null;
+    /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */
+    private _showPoster;
+    /**
+     * The picture at the poster time (frame 0 if the movie has none), as `snapshot()` returns it, and the movie is left as it was:
+     * still showing the poster, or back at the frame it was at.
+     */
+    posterImage(opts?: SnapshotOptions & {
+        as?: 'blob';
+    }): Promise<Blob>;
+    posterImage(opts: SnapshotOptions & {
+        as: 'dataURL';
+    }): Promise<string>;
     private _ensureAudioContext;
     init(options?: MovieOptions): Promise<void>;
     gotoFrame(frame: number, force?: boolean): Promise<void>;

package/dist/index.cjs

@@ -1449,6 +1449,21 @@ function startWhenRunning(ctx, start, gesture) {
 }
 var GESTURES = ["pointerdown", "mousedown", "touchend", "keydown"];
 
+// src/core/poster.ts
+function normalizePoster(poster, duration, frameRate) {
+  if (poster === void 0 || poster === null) return { seconds: null, frame: null };
+  if (typeof poster !== "number" || !Number.isFinite(poster)) {
+    console.warn(`pixi-effects: movie.init({ poster }): ${JSON.stringify(poster)} is not a time in seconds; ignored`);
+    return { seconds: null, frame: null };
+  }
+  let seconds = poster < 0 ? Math.max(0, duration + poster) : poster;
+  if (seconds > duration) {
+    console.warn(`pixi-effects: movie.init({ poster }): the poster time ${poster} s is past the end of the movie (${duration} s); using the last frame`);
+    seconds = duration;
+  }
+  return { seconds, frame: Math.round(seconds * frameRate) };
+}
+
 // src/core/Movie.ts
 PIXI.extensions.add(PIXI.CullerPlugin);
 gsap.gsap.registerPlugin(PixiPlugin.PixiPlugin);
@@ -1462,6 +1477,11 @@ var Movie = class {
   audioSource = null;
   gainNode = null;
   _cancelAudioStart = null;
+  /** The poster time in seconds (`movie.init({ poster })`), or null. */
+  poster = null;
+  _posterFrame = null;
+  /** The canvas shows the poster picture while the playhead is still at frame 0 (like `<video poster>`): the first seek or play replaces it. */
+  _atPoster = false;
   /** > 0 while the movie moves its own playhead (playback, render, snapshot, contactSheet): those are not the seeks `seeking` / `seeked` report. */
   _quiet = 0;
   _volume = 1;
@@ -1505,6 +1525,36 @@ var Movie = class {
   get isReady() {
     return this._initState === "ready";
   }
+  /** The poster time as a frame number, or null. */
+  get posterFrame() {
+    return this._posterFrame;
+  }
+  /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */
+  async _showPoster() {
+    if (this._posterFrame === null || !this.timeline) return;
+    const back = this.currentFrame;
+    this.currentFrame = this._posterFrame;
+    try {
+      this.timeline.time(this._posterFrame / this.frameRate);
+      await this._awaitVideoFrames();
+      this._updateSpace();
+      this._renderNow();
+    } finally {
+      this.currentFrame = back;
+    }
+    this._atPoster = true;
+  }
+  async posterImage(opts = {}) {
+    this._requireReady("posterImage");
+    const back = this.currentFrame, wasAtPoster = this._atPoster;
+    try {
+      return await this.snapshot(this._posterFrame ?? 0, opts);
+    } finally {
+      this.currentFrame = back;
+      if (wasAtPoster) await this._showPoster();
+      else await this._quietly(() => this.gotoFrame(back, true));
+    }
+  }
   _ensureAudioContext() {
     if (!this._audioContext) {
       const Ctx = window.AudioContext ?? window.webkitAudioContext;
@@ -1513,7 +1563,7 @@ var Movie = class {
     return this._audioContext;
   }
   async init(options = {}) {
-    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition"]);
+    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster"]);
     this._initState = "pending";
     try {
       this.width = options.width ?? 1920;
@@ -1521,6 +1571,9 @@ var Movie = class {
       this.duration = options.duration ?? 10;
       this.frameRate = options.frameRate ?? 30;
       this.totalFrames = Math.round(this.duration * this.frameRate);
+      const poster = normalizePoster(options.poster, this.duration, this.frameRate);
+      this.poster = poster.seconds;
+      this._posterFrame = poster.frame;
       this.background = options.background ?? "#000000";
       this.timeline = gsap.gsap.timeline({ paused: true, defaults: { ease: "none" } });
       this.timeline.add(gsap.gsap.to({}, { duration: this.duration }));
@@ -1584,6 +1637,7 @@ var Movie = class {
       this._updateSpace();
       this._renderNow();
       this._initState = "ready";
+      if (this._posterFrame !== null) await this._showPoster();
       this.emit("ready");
     } catch (err) {
       try {
@@ -1597,7 +1651,7 @@ var Movie = class {
   }
   async gotoFrame(frame, force = false) {
     if (this._initState !== "ready") return;
-    if (!force && this.currentFrame === frame) return;
+    if (!force && !this._atPoster && this.currentFrame === frame) return;
     if (this._quiet > 0) return this._goto(frame);
     const target = Math.max(0, Math.min(frame, this.totalFrames));
     this.emit("seeking", { frame: target, totalFrames: this.totalFrames });
@@ -1617,6 +1671,7 @@ var Movie = class {
     this.emit("error", { where, message: error instanceof Error ? error.message : String(error), error });
   }
   async _goto(frame) {
+    this._atPoster = false;
     this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
     this.timeline.time(this.currentFrame / this.frameRate);
     await this._awaitVideoFrames();
@@ -1658,7 +1713,7 @@ var Movie = class {
     const g = sheet.getContext("2d");
     g.fillStyle = "#10131c";
     g.fillRect(0, 0, L.width, L.height);
-    const back = this.currentFrame;
+    const back = this.currentFrame, wasAtPoster = this._atPoster;
     try {
       for (let i = 0; i < frames.length; i++) {
         const f = frames[i];
@@ -1671,7 +1726,8 @@ var Movie = class {
         g.fillText(`frame ${f}  \xB7  ${(f / this.frameRate).toFixed(2)}s`, x + 8, y + LABEL_H / 2);
       }
     } finally {
-      await this._quietly(() => this.gotoFrame(back, true));
+      if (wasAtPoster) await this._showPoster();
+      else await this._quietly(() => this.gotoFrame(back, true));
     }
     return encodeCanvas(sheet, "image/png", opts.as ?? "blob");
   }