pixi-effects 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.0
+
+**Changed**
+
+- A mask with no `at` of its own now starts and ends with the layer it masks, so its keyframes are measured from that layer's start (as `docs/dsl.md` always said: "shares its lifetime"). An explicit mask `at` is still composition time. **Migration:** a mask reveal that used `at: 0` on a layer that appears later now plays when the layer appears (before, it had finished long before). Give the mask an explicit `at` to keep the old timing.
+- An `audio` layer with `loop: true` and no `duration` lasts until the composition ends (it used to stop after one clip length). Without `loop` and without `duration` it lasts as long as its clip, so a one-shot sound effect needs no `duration`.
+
+**Fixed**
+
+- **Volume keyframes** behaved unlike every other keyframe: a `to` ramped from the end of the previous keyframe, so the documented fade-out `{ at: -2, to: { volume: 0 }, duration: 2 }` faded the music across the whole piece, and `set` ramped towards its time instead of jumping. Each change now holds the current value until its own start, and keyframes apply in time order.
+- A `set` keyframe (text `{value}` counter and fill, image tint, shape style) stayed applied after seeking back before it.
+- **A shape could be missing after a jump seek** (contact sheet, snapshot, scrubbing): geometry was drawn only while rendering, after the culler had measured the previous frame's bounds, so a rect growing from `width: 0` at the left edge was culled. Shapes now redraw before the cull.
+- `threeD` layers whose size changes (a growing shape, text) no longer make Pixi warn "destroyed while still bound": the render texture is resized in place.
+- Text `style` words (`stroke: { join: 'round' }`, named colours, `textBaseline`, `whiteSpace`) were parsed as expressions and warned.
+- `movie.inspect` judges overlaps on what is visible (cut to the canvas and the layer's mask), so a ticker parked off the canvas is not reported, and does not report the two scenes of a running transition.
+- The same "keyframe starts after the layer ends" warning, printed once per layer by a loop, is summarised after three.
+- `docs/dsl.md` contradicted itself on whether text content can change (it can, through `{value}`).
+
+**Added**
+
+- `blendMode: 'normal' | 'add' | 'screen' | 'multiply'` on every layer (a composition's children inherit it): glows and light leaks that add up.
+- A new `sfx-swoosh.mp3` in `examples/_assets` (an airy band-pass noise sweep, 0.55 s, stereo) replacing the old one.
+- `examples/gallery`: 30 portfolio pieces written as plain data by three AI models, with a showcase page, and the stumble notes that fed these fixes. `ai/reference/pitfalls.md` items 32–48.
+
 ## 0.3.0
 
 **Breaking**

package/README.md

@@ -1,8 +1,8 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.3.0`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.3.0` changed keyframe `at` to be relative to the layer).
+> **Status**: experimental — current release `0.4.0`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.4.0` makes a mask share its layer's lifetime, `0.3.0` made keyframe `at` relative to the layer).
 
-**[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
+**[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 30 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/).
 
@@ -35,8 +35,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.3.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.3.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.4.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.4.0/dist/Controller.js"
   }
 }
 </script>
@@ -47,7 +47,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.3.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.4.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.
 >
@@ -63,7 +63,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.3.0/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.4.0/dist/three.js"
   }
 }
 </script>

package/ai/SKILL.md

@@ -28,7 +28,9 @@ You describe a video as a tree of plain objects; the library plays it in a canva
 - **`audio` shorter than its layer goes silent** — add `loop: true`.
 - **Masks live in the parent's coordinates and don't follow the masked layer.** **`filterArea` is in the layer's own coordinates.**
 - **2.5D needs `threeD: true`** on each layer plus a `{ type: 'camera' }` layer; camera props go in `initial`/keyframes; keep every `z` below the camera distance (≈ 989 at 720p, fov 40); under a dolly zoom only `z = 0` stays fixed.
-- **Built in:** `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`. **Not in the DSL (hand-roll, recipes exist or loops are easy):** other per-frame curves, per-letter text animators (one layer per letter), blend modes, particle emitters, group/parent layers.
+- **Built in:** `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`. **Not in the DSL (hand-roll, recipes exist or loops are easy):** arc / progress-ring and stroke draw-on, text that changes over time (other than `{value}`), other per-frame curves and jitter, per-letter text animators (one layer per letter), particle emitters, group/parent layers.
+- **Blend modes:** `blendMode: 'add' | 'screen' | 'multiply'` on any layer (glows, light leaks).
+- **One `Movie` per page.** A sound effect needs no `duration` (it lasts as long as its clip). Seeking is safe: counters, colours and growing shapes are right after any jump.
 
 ## Layout sanity (the cheap bugs a screenshot catches)
 

package/ai/reference/cheatsheet.md

@@ -36,24 +36,25 @@ name, at, duration,
 initial: { ...props applied before any keyframe },
 keyframes: [ { at, duration, ease, set | to | from | (from + to), repeat?, yoyo?, repeatDelay? } ],
 filters: [ { type: 'chromaKey', keyColor, threshold, smoothing, spill } | { type: 'custom', name, filter: <Pixi Filter> } ],
-mask: <a layer spec>, maskInverted,
+mask: <a layer spec>, maskInverted,   // a mask with no `at` of its own starts and ends with the layer it masks (its keyframes count from that layer's start); an explicit mask `at` is composition time
 filterArea: { x, y, width, height }   // in the layer's OWN coordinates; lets blur/glow draw past the layer's bounds
 threeD: true                          // opt into 2.5D (see below)
+blendMode: 'normal' | 'add' | 'screen' | 'multiply'   // add / screen brighten (glows, light leaks: overlapping halos add up); on a composition its children inherit the mode
 ```
 
 Animatable props (`initial` / keyframes): `x y alpha rotation scale scaleX scaleY pivotX pivotY anchorX anchorY skewX skewY tint width height visible autoAlpha`, plus for shapes their style/geometry, for text `fill`, for audio `volume`, for 3D `z rotationX rotationY`, filter params as `'filters.<name>.<param>'`, three objects as `'three.<obj>.<path>'`.
 
-Keyframe kinds: `set` (jump), `to` (animate to), `from` (animate from), `from`+`to`. `repeat` (finite extra plays), `yoyo`, `repeatDelay` loop any of them (endless repeats are not allowed). `ease` = any GSAP ease (`'none'`, `'power2.out'`, `'expo.out'`, `'back.out(1.7)'`, `'elastic.out(1,0.5)'`, `'sine.inOut'`, `'bounce.out'`…). Default ease is linear.
+Keyframe kinds: `set` (jump at `at`; undone when you seek back), `to` (animate to), `from` (animate from), `from`+`to`. `from` / `from+to` show their start value from the layer's start, so a delayed fade-in needs no `initial.alpha`. `repeat` (finite extra plays), `yoyo`, `repeatDelay` loop any of them (endless repeats are not allowed). `ease` = any GSAP ease (`'none'`, `'power2.out'`, `'expo.out'`, `'back.out(1.7)'`, `'elastic.out(1,0.5)'`, `'sine.inOut'`, `'bounce.out'`…). Default ease is linear.
 
 ## Layer types
 
-**text** — `text`, `style` (any PixiJS TextStyle field: `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding`; expressions OK for numbers), `colorSpace`. Default anchor is **top-left**; use `anchorX/anchorY: 0.5` to centre on `x,y`. A text layer has one animatable number, `value`, printed where the text contains `{value}` (`text: '{value} users'`, `initial: { value: 0 }`, keyframe `to: { value: 2480 }`; `format: { decimals, grouping }`) — that is how counters work. Other content cannot change over time.
+**text** — `text`, `style` (any PixiJS TextStyle field: `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding`; expressions OK for numbers), `colorSpace`. Default anchor is **top-left**; use `anchorX/anchorY: 0.5` to centre on `x,y`. A text layer has one animatable number, `value`, printed where the text contains `{value}` (`text: '{value} users'`, `initial: { value: 0 }`, keyframe `to: { value: 2480 }`; `format: { decimals, grouping }`) — that is how counters work. Other content cannot change over time. Multi-line text is centre-aligned by default (`style.align: 'left'` to change).
 
 **image** — `asset`, `tint`, `colorSpace: 'rgb'|'oklab'|'oklch'`. Default anchor top-left; natural size = `w`,`h`.
 
 **video** — `asset`, `loop`, `audio`, `volume`; `initial: { scale: 'cover' }`.
 
-**audio** — `asset`, `loop`, `volume`; fade with volume keyframes. **A file shorter than the layer goes silent unless `loop: true`.**
+**audio** — `asset`, `loop`, `volume`; fade with volume keyframes (`{ at: -2, to: { volume: 0 }, duration: 2 }` fades the last 2 s). **Omit `duration` for a one-shot sound effect: it lasts exactly as long as its clip.** With `loop: true` and no `duration` it lasts until the composition ends. An explicit `duration` longer than the clip goes silent after the clip unless `loop: true`.
 
 **shape** — `shape: 'rect' | 'circle' | 'ellipse' | 'line' | 'polygon' | 'path'`:
 
@@ -68,7 +69,7 @@ Keyframe kinds: `set` (jump), `to` (animate to), `from` (animate from), `from`+`
 
 Style (`initial` / keyframes): `fillColor fillAlpha strokeColor strokeAlpha strokeWidth`; `colorSpace: 'oklab'|'oklch'` for clean colour tweens. rect/circle/ellipse are **centred on `x,y` by default** (`anchorX/anchorY` default 0.5): for a bar growing from its base use `anchorY: 1` (or `anchorX: 0` for left-to-right). **`fillGradient`** (top level or `initial`; instead of `fillColor`): `{ type?: 'linear'|'radial', stops: [[0, '#000'], [1, 'rgba(0,0,0,.6)']], angle? /* linear, deg, 90 = top→bottom */, center?, innerRadius?, radius? /* radial, 0–1 of bounds */ }` — stops may have alpha, so a radial transparent→dark is a vignette.
 
-**composition** — `width height duration sequences transitions`. With `threeD: true` it is a **card**: its children are drawn into one texture and move / rotate in depth together. Children use the composition's local coordinates and times. Position/rotate/scale it as a unit; to rotate/scale about its centre set `pivotX/pivotY` to the centre and `x/y` to where that point should sit.
+**composition** — `width height duration sequences transitions`. With `threeD: true` it is a **card**: its children are drawn into one texture (content outside its `width × height` is clipped: size it for a soft shadow too) and move / rotate in depth together. Children use the composition's local coordinates and times. Position/rotate/scale it as a unit; to rotate/scale about its centre set `pivotX/pivotY` to the centre and `x/y` to where that point should sit.
 
 **camera** (2.5D) — props in `initial`/keyframes: `x y z lookAtX lookAtY lookAtZ fov` (defaults: centred, looking at the z = 0 plane, `fov` 40, `z` auto = `(H/2)/tan(fov/2)` ≈ 989 at 720p). Never on the camera object itself. An orbit is `orbit()`; by hand: `x = cx + R·sin θ`, `z = R·cos θ`, `R = (H/2)/tan(fov/2)`, `lookAt` = the centre at `z = 0`.
 

package/ai/reference/pitfalls.md

@@ -1,6 +1,6 @@
 # pixi-effects pitfalls — what actually went wrong
 
-Collected by having fresh AI sessions build six different pieces (kinetic type, news lower-third, slideshow, 2.5D showcase, three.js title, data-driven bar chart) from the docs alone. Each entry is a real stumble. **Status**: `fixed` = the library now handles or warns; `docs` = nothing can catch it, so remember it; `hand-roll` = the DSL has no feature, see the workaround.
+Collected by having fresh AI sessions build pieces from the docs alone: first six (kinetic type, news lower-third, slideshow, 2.5D showcase, three.js title, bar chart), then a portfolio of 16 more (items 32 and up), made by three different models. Each entry is a real stumble. **Status**: `fixed` = the library now handles or warns; `docs` = nothing can catch it, so remember it; `hand-roll` = the DSL has no feature, see the workaround.
 
 A good habit that catches most of these: after `init`, read `window.__logs` (see `ai/template.html`) — every pixi-effects warning says what to change.
 
@@ -10,7 +10,7 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 2. **A layer's own `at` and a transition's `at` are composition time** (seconds from the parent composition's start). Only keyframes are layer-local.
 3. **Layers are hidden, not removed, after `[at, at+duration)`** and keep their last values. Z-order is array order (later = on top). To switch scenes, stack scenes with `at`/`duration`, each starting with an opaque full-screen rect. *(docs)*
 4. **Transitions need overlapping lifespans.** Both layers must be alive for the whole window: scene `i` starts at `i·(L−T)`, the transition's `at` is the next scene's start, total = `n·(L−T)+T`. A scene that ends while the transition is still running leaves a gap. *(docs)*
-5. **Audio shorter than its layer goes silent** — `bgm.mp3` is 6 s. Add `loop: true` or shorten the layer. *(fixed: warns)* Volume fades: `volume: 0` + `{ at: 0, to: { volume: v }, duration: 2 }` + `{ at: -2, to: { volume: 0 }, duration: 2 }`.
+5. **Audio length.** Omit `duration` on a one-shot sound effect: the layer lasts exactly as long as its clip (pop 0.13 s, click 0.1 s, chime 0.6 s, swoosh 0.55 s; nothing to measure). `loop: true` with no `duration` lasts until the composition ends. An explicit `duration` longer than the clip goes silent after the clip unless `loop: true` (`bgm.mp3` is 6 s) and warns. Volume fades work like any keyframe: `volume: 0` + `{ at: 0, to: { volume: v }, duration: 2 }` + `{ at: -2, to: { volume: 0 }, duration: 2 }` (the last 2 s only; `set` is a jump). *(fixed: volume keyframes used to ramp from the previous keyframe's end, so the music faded across the whole piece)*
 6. **Snap times to the frame grid (`Math.round(t*30)/30`) when two things must stay locked** (a bar and its label). Drive both from one JS easing function with per-frame `set` keyframes rather than mixing a tween with computed positions. *(docs)*
 7. **Pick eases on purpose.** `expo.in` stays tiny until the very end (a "flood" circle never reaches the corners — use a bigger radius and `power2.in`). A zoom transition with `power2.out` looks like a cut because the incoming scene is nearly opaque after 40 %. Default is linear. *(docs)*
 8. **`render()` runs in roughly real time** (6 s of 720p ≈ 6 s). Listen to `movie.on('progress', e => e.progress)` (0–100). *(docs)*
@@ -20,7 +20,7 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 9. **Defaults differ by type.** rect/circle/ellipse are centred on `x,y`; text and image are top-left; a composition has no anchor — use `pivotX/pivotY` and set `x,y` to where the pivot should land. For a bar growing from its base use `anchorY: 1` (or `anchorX: 0`). *(docs)*
 10. **Shape geometry may be at the top level or in `initial`** (`width height radius anchorX …`). *(fixed: `initial` used to be silently ignored)*
 11. **Angles are degrees** — `rotation`, `skew*`, `rotationX/Y` — and `rotation: -0.2` is almost no rotation. *(docs)*
-12. **Text**: anchor 0.5 centres the line *box*, not the cap height (nudge underlines by ~`0.46·size`). Arial Black is ~0.8·size wide per glyph, monospace ~0.6·size; leave ~7 % for hold-scale. `style` accepts any PixiJS TextStyle field: `letterSpacing`, `wordWrap` + `wordWrapWidth`, `lineHeight`, `stroke`, `dropShadow`, `padding`. A glow (`dropShadow` with `blur`) is clipped unless `padding ≥ 2·blur`. *(docs)*
+12. **Text**: anchor 0.5 centres the line *box*, not the cap height (an underline under serif or italic text needs ~`0.9·size` below the centre: `0.46·size` touches the descenders of a g or y). Arial Black is ~0.8·size wide per glyph, monospace ~0.6·size; leave ~7 % for hold-scale. `style` accepts any PixiJS TextStyle field: `letterSpacing`, `wordWrap` + `wordWrapWidth`, `lineHeight`, `stroke`, `dropShadow`, `padding`. A glow (`dropShadow` with `blur`) is clipped unless `padding ≥ 2·blur`. *(docs)*
 13. **`w` / `h` in expressions** are the layer's own size. For text they now describe the styled text (`x: '-w'` scrolls a marquee fully out). *(fixed)*
 14. **Masks live in the parent's coordinate space and do not follow the masked layer.** Reveal by growing the mask's `width` from a fixed edge (`anchorX: 0`); exit by tweening `x` and `width` together; slide the content separately. *(docs)*
 15. **`line` / `polygon` / `path` use plain canvas coordinates** when you give no `x,y` (they used to be drawn around (0,0)); with `x,y` those place the shape's centre. Stroke colour and width go in `initial`. A background pill must be sized from its text (~0.58 × fontSize per glyph + padding): `inspect` does not check text against shapes. *(fixed)*
@@ -52,3 +52,24 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 30b. **Unknown option names now warn** (`contactSheet({ cols: 2 })` → did you mean `columns`; `init({ fps })` → `frameRate`). Layer names show up in `inspect` paths, so give layers a `name`. `inspect` ignores faint (alpha < 0.3) layers and text whose x / y is animated (tickers), so a scrolling marquee is not reported as cut off. Pixi may print `[BindGroup] … destroyed while still bound` warnings at `movie.destroy()`: harmless (playback and seeking never warn). *(docs)*
 30c. **Look with the built-in tools, not OS screenshots**: `await movie.contactSheet({ count: 6, as: 'dataURL' })` returns one labelled image of the whole animation; `await movie.inspect(frame)` returns every layer's canvas bounds and `issues`. If you do use a browser tool, `screenshot` needs an **absolute path**, macOS `sed -i` needs `''`, and a static server may redirect `/x.html` → `/x` and drop `?query`. Keep the template's `try/catch` around `init` so failures land in `window.__logs`. Check ≥ 5 timestamps including mid-transition. *(fixed: tools built in)*
 31. **Check audio without rendering by decoding the render**: `const b = await movie.render({format:'mp4'})` then `new OfflineAudioContext(...).decodeAudioData(await b.arrayBuffer())` and measure RMS over time. `movie.audioBuffer` holds the mix. *(docs)*
+
+## Round 2 — found by building 16 portfolio pieces (examples/gallery)
+
+32. **Seeking is safe now** *(fixed)*: a `set` keyframe (counter value, text fill, image tint, shape style) is undone when you seek back before it, and shapes are redrawn before they are culled, so a rect growing from `width: 0` at the left edge draws after any jump seek (contact sheet, snapshot, scrubbing, export). The old workarounds (`width: 0.01`, a one-frame `to` instead of `set`) are not needed.
+33. **A mask starts and ends with the layer it masks** *(fixed)*, so its keyframes count from that layer's start. A mask with an explicit `at` keeps composition time. Before, a mask `at: 0` reveal had finished before a layer that appeared at 8 s, and the layer stayed invisible without any warning.
+34. **`from` and `from+to` show their start value from the LAYER's start**, not from the keyframe's `at` (GSAP behaviour): a delayed fade-in `{ at: 2, from: { alpha: 0 }, to: { alpha: 1 } }` needs no `initial.alpha`. To keep the current value until `at` and then jump, use `set`. *(docs)*
+35. **One `Movie` per page.** Creating a second Movie (for an isolated repro) and destroying it breaks the first (`null.clear`). Reload instead. *(docs)*
+36. **Multi-line text is centre-aligned by default** (`style.align: 'left'` for left-aligned paragraphs). *(docs)*
+37. **A `threeD` composition (a card) clips its children at its own width × height.** Size the card for its soft shadow too. A growing `threeD` shape or text is fine: its texture is resized in place (it used to warn "destroyed while still bound"). *(docs / fixed)*
+38. **Under an orbit the side the camera swings toward becomes the NEAR side**: a "far" card at `z: −200` can be drawn bigger than 1× on that side and run off the frame (`inspect` only checks text). Pull those cards inward / lower `z`, and check a frame at the extreme of the sweep. After `orbit()` ends the default camera returns, so to hold the final pose add a camera layer that starts there. Near particles balloon under a dolly zoom: cap particle `z` at about +150, or one becomes a fake full stop. *(docs)*
+39. **`fillGradient` stops span the whole unmasked shape**, not the visible part: under a mask, place the stops for the visible fraction (e.g. 0.64→1). A translucent shape over near-black reads as grey: put the alpha in the gradient stops. *(docs)*
+40. **Rotate a polygon / path about a chosen point** by wrapping it in a `composition` with `pivotX/pivotY` (its centre is otherwise the bounds centre). *(docs)*
+41. **Glow a whole set of layers** by putting them in one `composition` with a blur filter and `filterArea` (only a composition carries a filter for its children): wide enough for the blur, and the set is built once, so the extra copy is just a second group. *(docs)*
+42. **Transition looks:** the default `dissolve` reads as a hard black-and-white camouflage and `scale: 220` as static; `scale: 90, smoothing: 0.5` is a soft film dissolve. The default edge softness of `iris` (0.02) and `wipe` blurs flat graphics at 720p: `smoothing: 0.004`–`0.01` gives a clean edge. *(docs)*
+43. **Layers built in a loop need their z-order planned**: anything pushed to the array after the loop is drawn over what the loop made (rings crossed over a header). Keyframes on different properties of one layer may overlap in time. Keep a subject in the upper ~60 % of a source image if a caption will sit under it (`inspect` does not look at picture content). *(docs)*
+44. **`{value}` has no number padding**: a clock or timecode cannot show `:05`. Keep the value in a range that always has the same digit count, or split digits into two counters. *(hand-roll)*
+45. **The same mistake in a loop warns once**: the warning "keyframe starts after the layer ends" is summarised after three layers. The usual cause is an off-by-one (`f <= frames` instead of `f < frames`) that puts the last sample exactly at the layer's end. *(fixed)*
+46. **Still not in the DSL (hand-roll; round-two notes have workarounds):** arc / progress-ring primitive and stroke draw-on / trim path (use a growing rect mask for a one-direction reveal, tick marks, or pre-drawn arcs shown one per frame), text content that changes over time (only `{value}`), per-frame jitter (film grain = seeded `set` keyframes on an oversized image), particle emitters, per-letter / per-line text split (measure with `canvas.measureText` using Pixi's font string), shared masks, `zIndex`.
+46b. **Blend modes exist now** (`blendMode: 'add' | 'screen' | 'multiply'` on any layer, threeD layers and compositions included; a composition's children inherit it). Additive white cores no longer read grey on a coloured background. *(fixed)*
+47. **Browser tooling:** the `agent-browser` daemon is shared, so a `contactSheet` can come back from another session: after saving an image, look at it and confirm it is YOUR piece. In zsh a variable holding `agent-browser --session x` is not split into words (use a small wrapper script). `inspect` now clips overlaps to the visible area and ignores the two scenes of a running transition; it still does not compare text with picture content or shapes.
+48. **A composition's `alpha` is applied to each child separately, not to the flattened group** (measured: two overlapping opaque circles in a composition at `alpha: 0.5` show the lower one through the upper one in the overlap). Fading a group that has overlapping children therefore shows the overlap; fade the children themselves, or keep overlapping parts out of the group. Expressions have no way to read a sibling's size: measure text with `canvas.measureText` (the font string Pixi uses) and compute pill widths in JS. *(docs)*

package/ai/template.html

@@ -33,9 +33,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.3.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.3.0/dist/Controller.js",
-      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.3.0/dist/three.js",
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.4.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.4.0/dist/Controller.js",
+      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.4.0/dist/three.js",
       "three":                   "https://esm.sh/three@0.178.0"
     }
   }

package/dist/{Base-Ba4Ta4ap.d.ts → Base-5R7C5pHR.d.cts}

@@ -1,5 +1,5 @@
 import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
-import { S as SequenceSpec, C as CompositionShape, t as AudioDescriptor } from './types-3c8Vymgw.js';
+import { S as SequenceSpec, C as CompositionShape, t as AudioDescriptor } from './types-CRE9WKd4.cjs';
 import { gsap } from 'gsap';
 
 /**
@@ -86,6 +86,12 @@ declare abstract class Sequence {
      * project their `threeD` layers; everything else has nothing to do.
      */
     updateSpace(_t: number, _host: SpaceHost): void;
+    /**
+     * Runs once per rendered frame, after the timeline seek and before the cull. Layers whose drawn
+     * geometry follows tweened state (shapes) redraw here, so the culler measures where the layer is NOW
+     * and not where it was drawn at the previous render.
+     */
+    syncFrame(): void;
     destroy(): void;
 }
 

package/dist/{Base-BDw6dKRB.d.cts → Base-DhY9oMxr.d.ts}

@@ -1,5 +1,5 @@
 import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
-import { S as SequenceSpec, C as CompositionShape, t as AudioDescriptor } from './types-3c8Vymgw.cjs';
+import { S as SequenceSpec, C as CompositionShape, t as AudioDescriptor } from './types-CRE9WKd4.js';
 import { gsap } from 'gsap';
 
 /**
@@ -86,6 +86,12 @@ declare abstract class Sequence {
      * project their `threeD` layers; everything else has nothing to do.
      */
     updateSpace(_t: number, _host: SpaceHost): void;
+    /**
+     * Runs once per rendered frame, after the timeline seek and before the cull. Layers whose drawn
+     * geometry follows tweened state (shapes) redraw here, so the culler measures where the layer is NOW
+     * and not where it was drawn at the previous render.
+     */
+    syncFrame(): void;
     destroy(): void;
 }
 

package/dist/Composition-D7RCAGEA.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+var chunkQGBOC5YL_cjs = require('./chunk-QGBOC5YL.cjs');
+require('./chunk-6BQ6IEW2.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunkQGBOC5YL_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-D7RCAGEA.cjs.map
+//# sourceMappingURL=Composition-D7RCAGEA.cjs.map

package/dist/{Composition-6FDH5OPM.cjs.map → Composition-D7RCAGEA.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-6FDH5OPM.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-D7RCAGEA.cjs"}

package/dist/Composition-RGTRZ2JX.js

@@ -0,0 +1,4 @@
+export { CompositionSequence } from './chunk-A574IA4F.js';
+import './chunk-ZQX7WIYL.js';
+//# sourceMappingURL=Composition-RGTRZ2JX.js.map
+//# sourceMappingURL=Composition-RGTRZ2JX.js.map

package/dist/{Composition-FEYAUMFI.js.map → Composition-RGTRZ2JX.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-FEYAUMFI.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-RGTRZ2JX.js"}

package/dist/Controller.d.cts

@@ -1,7 +1,7 @@
-import { M as Movie } from './Movie-W8ISiEBB.cjs';
+import { M as Movie } from './Movie-CghFXprP.cjs';
 import 'pixi.js';
 import 'gsap';
-import './types-3c8Vymgw.cjs';
+import './types-CRE9WKd4.cjs';
 
 declare function formatTime(seconds: number): string;
 declare function frameToPercent(frame: number, totalFrames: number): number;

package/dist/Controller.d.ts

@@ -1,7 +1,7 @@
-import { M as Movie } from './Movie-DMpaT67V.js';
+import { M as Movie } from './Movie-DRZtIGU7.js';
 import 'pixi.js';
 import 'gsap';
-import './types-3c8Vymgw.js';
+import './types-CRE9WKd4.js';
 
 declare function formatTime(seconds: number): string;
 declare function frameToPercent(frame: number, totalFrames: number): number;

package/dist/{Movie-W8ISiEBB.d.cts → Movie-CghFXprP.d.cts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { A as AssetSpec, g as CompositionSpec } from './types-3c8Vymgw.cjs';
+import { A as AssetSpec, g as CompositionSpec } from './types-CRE9WKd4.cjs';
 
 interface Rect {
     x: number;

package/dist/{Movie-DMpaT67V.d.ts → Movie-DRZtIGU7.d.ts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { A as AssetSpec, g as CompositionSpec } from './types-3c8Vymgw.js';
+import { A as AssetSpec, g as CompositionSpec } from './types-CRE9WKd4.js';
 
 interface Rect {
     x: number;

package/dist/{chunk-SIRVULFF.cjs → chunk-6BQ6IEW2.cjs}

@@ -798,6 +798,14 @@ var Sequence = class {
    */
   updateSpace(_t, _host) {
   }
+  /**
+   * Runs once per rendered frame, after the timeline seek and before the cull. Layers whose drawn
+   * geometry follows tweened state (shapes) redraw here, so the culler measures where the layer is NOW
+   * and not where it was drawn at the previous render.
+   */
+  syncFrame() {
+    this.maskSequence?.syncFrame();
+  }
   destroy() {
     this.maskSequence?.destroy();
     this.maskSequence = null;
@@ -834,11 +842,16 @@ function lintTiming(spec, parentDuration, warn = defaultWarn) {
     const kat = kf.at ?? 0;
     if (kat >= duration) {
       warn(
-        `pixi-effects: ${who}: keyframes[${i}] starts at ${kat}s, after the layer ends (duration ${duration}s), so it never plays. Keyframe \`at\` is measured from the start of this layer, not from the start of the composition.`
+        `pixi-effects: ${who}: keyframes[${i}] starts at ${kat}s, after the layer ends (duration ${duration}s), so it never plays. Keyframe \`at\` is measured from the start of this layer, not from the start of the composition.`,
+        "late-keyframe"
       );
     }
   });
 }
+function summarizeWarnings(messages, shown = 3) {
+  if (messages.length <= shown) return messages;
+  return [...messages.slice(0, shown), `pixi-effects: ${messages.length - shown} more layers with the same problem (the same loop or helper is probably building them): fix the ones above and these go away.`];
+}
 function lintText(spec, warn = defaultWarn) {
   if (spec.type !== "text") return;
   if (collectPropKeys(spec).has("value") && !(spec.text ?? "").includes("{value}")) {
@@ -1013,6 +1026,27 @@ var CameraSequence = class extends Sequence {
   }
 };
 
+// src/core/revertibleSet.ts
+function revertibleSet(timeline, at, read, write, value) {
+  let p = 0;
+  let before;
+  const proxy = {
+    get p() {
+      return p;
+    },
+    set p(next) {
+      if (next >= 1 && p < 1) {
+        before = read();
+        write(value);
+      } else if (next < 1 && p >= 1) {
+        write(before);
+      }
+      p = next;
+    }
+  };
+  timeline.set(proxy, { p: 1 }, at);
+}
+
 // src/expr/colorInterp.ts
 function buildColorInterp(from, to, space) {
   const fromRGBA = parseToRGBA(from);
@@ -1203,9 +1237,10 @@ var ImageSequence = class extends Sequence {
       const toTint = kf.to?.tint;
       const setTint = kf.set?.tint;
       if (setTint !== void 0) {
-        timeline.call(() => {
-          this.target.tint = setTint;
-        }, [], at);
+        const sprite = this.target;
+        revertibleSet(timeline, at, () => sprite.tint, (c) => {
+          sprite.tint = c;
+        }, setTint);
       }
       if (toTint !== void 0) {
         tweenColor(
@@ -1252,7 +1287,21 @@ function stripKeysInKeyframe(kf, keys) {
     from: stripKeys(kf.from, keys)
   };
 }
-var STYLE_OPAQUE_KEYS = ["fontFamily", "fill", "align", "fontStyle", "fontWeight"];
+var STYLE_OPAQUE_KEYS = [
+  "fontFamily",
+  "fill",
+  "align",
+  "fontStyle",
+  "fontWeight",
+  "fontVariant",
+  "textBaseline",
+  "whiteSpace",
+  "lineJoin",
+  "join",
+  "cap",
+  "color",
+  "stroke"
+];
 function formatValue(v, f) {
   const fixed = v.toFixed(Math.max(0, Math.floor(f?.decimals ?? 0)));
   if (!f?.grouping) return fixed;
@@ -1367,10 +1416,10 @@ function bindValueKeyframes(timeline, state, refresh, keyframes, parentDuration,
     const loop = loopVars(kf);
     if (setV !== void 0) {
       const v = resolveNumber(setV, scope);
-      timeline.call(() => {
-        state.value = v;
+      revertibleSet(timeline, at, () => state.value, (n) => {
+        state.value = n;
         refresh();
-      }, [], at);
+      }, v);
     }
     if (toV !== void 0 && fromV !== void 0) {
       timeline.fromTo(
@@ -1399,10 +1448,10 @@ function bindFillKeyframes(timeline, text, keyframes, parentDuration, offset, co
     const fromFill = pickFill(kf.from);
     const toFill = pickFill(kf.to);
     if (setFill !== void 0) {
-      timeline.call(() => {
-        state.fill = setFill;
+      revertibleSet(timeline, at, () => state.fill, (c) => {
+        state.fill = c;
         writeFill();
-      }, [], at);
+      }, setFill);
     }
     if (toFill !== void 0) {
       tweenColor(
@@ -1433,7 +1482,8 @@ var AudioSequence = class extends Sequence {
     const data = await pixi_js.Assets.get(this.spec.asset);
     this._audioBuffer = data.audioBuffer;
     if (this.duration === void 0) {
-      this.duration = this.spec.duration ?? data.duration ?? this.root.duration;
+      const rest = Math.max(0, (this.parent?.duration ?? this.root.duration) - this.at);
+      this.duration = this.spec.duration ?? (this.spec.loop ? rest : data.duration) ?? this.root.duration;
     }
     if (!this.spec.loop && data.duration !== void 0 && this.duration > data.duration + 0.05) {
       console.warn(
@@ -1449,21 +1499,32 @@ var AudioSequence = class extends Sequence {
     const initialVolume = this.spec.volume ?? 1;
     const volumeKeyframes = [];
     const dur = this.duration;
-    for (const raw of this.spec.keyframes ?? []) {
-      const kf = normalizeKeyframe(raw, dur);
-      const set = kf.set;
-      const to = kf.to;
-      const from = kf.from;
-      if (kf.kind === "set" && set && "volume" in set) {
-        volumeKeyframes.push({ time: baseTime + this.at + kf.at, value: set.volume });
-      } else if (kf.kind === "to" && to && "volume" in to) {
-        volumeKeyframes.push({ time: baseTime + this.at + kf.at + kf.duration, value: to.volume });
-      } else if (kf.kind === "fromTo" && to && "volume" in to) {
-        volumeKeyframes.push({ time: baseTime + this.at + kf.at, value: from?.volume ?? initialVolume });
-        volumeKeyframes.push({ time: baseTime + this.at + kf.at + kf.duration, value: to.volume });
-      } else if (kf.kind === "from" && from && "volume" in from) {
-        volumeKeyframes.push({ time: baseTime + this.at + kf.at, value: from.volume });
-        volumeKeyframes.push({ time: baseTime + this.at + kf.at + kf.duration, value: initialVolume });
+    const t0 = baseTime + this.at;
+    const keyframes = (this.spec.keyframes ?? []).map((raw) => normalizeKeyframe(raw, dur)).filter((kf) => [kf.set, kf.to, kf.from].some((p) => p && "volume" in p)).sort((x, y) => x.at - y.at);
+    let current = initialVolume;
+    const point = (time, value) => {
+      volumeKeyframes.push({ time, value });
+    };
+    for (const kf of keyframes) {
+      const start = t0 + kf.at;
+      const end = start + kf.duration;
+      const set = kf.set?.volume;
+      const to = kf.to?.volume;
+      const from = kf.from?.volume;
+      point(start, current);
+      if (kf.kind === "set" && set !== void 0) {
+        point(start, set);
+        current = set;
+      } else if (kf.kind === "to" && to !== void 0) {
+        point(end, to);
+        current = to;
+      } else if (kf.kind === "fromTo" && to !== void 0) {
+        point(start, from ?? current);
+        point(end, to);
+        current = to;
+      } else if (kf.kind === "from" && from !== void 0) {
+        point(start, from);
+        point(end, current);
       }
     }
     out.push({
@@ -1761,12 +1822,32 @@ var ShapeSequence = class extends Sequence {
       if (init.y === void 0) graphics.y = cy;
     }
     graphics.onRender = () => {
-      graphics.clear();
-      this._drawGeometry(graphics);
-      applyState(graphics, this._state);
+      if (this._fresh) {
+        this._fresh = false;
+        return;
+      }
+      this._redraw();
     };
     this.buildFilters();
   }
+  _fresh = false;
+  _redraw() {
+    const graphics = this.target;
+    graphics.clear();
+    this._drawGeometry(graphics);
+    applyState(graphics, this._state);
+  }
+  /**
+   * Draw from the tweened `_state` before the culler runs. The culler measures the geometry as last
+   * drawn; a layer drawn only inside `onRender` is culled on stale bounds (a rect growing from
+   * `width: 0` at the left edge was skipped after a jump seek, and one frame late in playback).
+   */
+  syncFrame() {
+    super.syncFrame();
+    if (!this.target?.renderable) return;
+    this._redraw();
+    this._fresh = true;
+  }
   bindTimeline(timeline, offset = 0) {
     if (!this.target) return;
     const scope = this.scope();
@@ -1930,9 +2011,10 @@ function bindLiveKeyframes(timeline, state, liveKeys, keyframes, parentDuration,
       if (live) {
         for (const [k, v] of Object.entries(live)) {
           const resolved = resolveLiveValue(k, v, scope);
-          timeline.call(() => {
-            state[k] = resolved;
-          }, [], at);
+          const live2 = state;
+          revertibleSet(timeline, at, () => live2[k], (v2) => {
+            live2[k] = v2;
+          }, resolved);
         }
       }
     }
@@ -1991,7 +2073,7 @@ function numOrZero(v, scope) {
 var _CompositionSequence = null;
 async function getCompositionSequence() {
   if (!_CompositionSequence) {
-    _CompositionSequence = (await import('./Composition-6FDH5OPM.cjs')).CompositionSequence;
+    _CompositionSequence = (await import('./Composition-D7RCAGEA.cjs')).CompositionSequence;
   }
   return _CompositionSequence;
 }
@@ -2045,5 +2127,6 @@ exports.lintTiming = lintTiming;
 exports.projectLayer = projectLayer;
 exports.registerSequenceType = registerSequenceType;
 exports.resolveAt = resolveAt;
-//# sourceMappingURL=chunk-SIRVULFF.cjs.map
-//# sourceMappingURL=chunk-SIRVULFF.cjs.map
+exports.summarizeWarnings = summarizeWarnings;
+//# sourceMappingURL=chunk-6BQ6IEW2.cjs.map
+//# sourceMappingURL=chunk-6BQ6IEW2.cjs.map