pixi-effects 0.5.0 → 0.6.0

package/dist/three.cjs

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

package/dist/three.d.cts

@@ -1,6 +1,6 @@
-import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-7VtTEKUW.cjs';
+import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-DrW9QeKU.cjs';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-DnRAxroQ.cjs';
+import { S as Sequence, P as PathRouters } from './Base-4vNLl4tH.cjs';
 import 'pixi.js';
 import 'gsap';
 

package/dist/three.d.ts

@@ -1,6 +1,6 @@
-import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-7VtTEKUW.js';
+import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-DrW9QeKU.js';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-CPSFBkPm.js';
+import { S as Sequence, P as PathRouters } from './Base-CD4AoT5-.js';
 import 'pixi.js';
 import 'gsap';
 

package/dist/three.js

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

package/dist/{types-7VtTEKUW.d.cts → types-DrW9QeKU.d.cts}

@@ -212,6 +212,10 @@ interface TextSequenceSpec extends SequenceCommon {
      * 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`.
+     *
+     * The text can change over time: a keyframe `set: { text: 'Two' }` swaps the string at that time (and back when
+     * you seek back; a string cannot be tweened). `visibleChars` is a number that shows only the first N characters
+     * (a typewriter): `initial: { visibleChars: 0 }`, keyframe `to: { visibleChars: 20 }`. It starts at 0 once it is animated.
      */
     text?: string;
     /** How `{value}` is printed: `decimals` (default 0) and thousands `grouping` (default false). */
@@ -336,6 +340,18 @@ interface GradientSpec {
     /** radial: outer radius where the last stop applies, 0–1. Default 0.5. */
     radius?: number;
 }
+/**
+ * Stroke trim (draw-on): the part of the outline that is stroked, as fractions 0–1 of its length. Animate `trimEnd`
+ * from 0 to 1 to draw a line / path / outline on; animate both for a travelling dash. The outline of a rect starts at
+ * its top-left and goes clockwise, of a circle / ellipse at 12 o'clock and goes clockwise; a polygon's closing edge counts.
+ * The fill is not trimmed. Not for `arc` (animate its `endAngle`).
+ */
+interface Trimmable {
+    /** Where the stroke starts, 0–1 of the outline. Default 0. Animatable. */
+    trimStart?: PropValue;
+    /** Where the stroke ends, 0–1 of the outline. Default 1. Animatable. */
+    trimEnd?: PropValue;
+}
 interface ShapeBase extends SequenceCommon {
     type: 'shape';
     /** Fill with a gradient instead of `fillColor` (top level or in `initial`). */
@@ -358,7 +374,7 @@ interface ShapeBase extends SequenceCommon {
     /** How stroke corners join: `'miter'` (default; sharp points can poke out), `'round'` or `'bevel'`. Top level or in `initial`. */
     strokeJoin?: 'miter' | 'round' | 'bevel';
 }
-interface RectShapeSpec extends ShapeBase {
+interface RectShapeSpec extends ShapeBase, Trimmable {
     shape: 'rect';
     width: PropValue;
     height: PropValue;
@@ -373,14 +389,14 @@ interface RectShapeSpec extends ShapeBase {
     anchorX?: PropValue;
     anchorY?: PropValue;
 }
-interface CircleShapeSpec extends ShapeBase {
+interface CircleShapeSpec extends ShapeBase, Trimmable {
     shape: 'circle';
     radius: PropValue;
     /** See RectShapeSpec.anchorX. Default 0.5 (centre). */
     anchorX?: PropValue;
     anchorY?: PropValue;
 }
-interface EllipseShapeSpec extends ShapeBase {
+interface EllipseShapeSpec extends ShapeBase, Trimmable {
     shape: 'ellipse';
     radiusX: PropValue;
     radiusY: PropValue;
@@ -404,20 +420,20 @@ interface ArcShapeSpec extends ShapeBase {
     /** Degrees. Default 360. Animatable. */
     endAngle?: PropValue;
 }
-interface LineShapeSpec extends ShapeBase {
+interface LineShapeSpec extends ShapeBase, Trimmable {
     shape: 'line';
     /** Line endpoints relative to the shape's local origin. */
     from: [PropValue, PropValue];
     to: [PropValue, PropValue];
 }
-interface PolygonShapeSpec extends ShapeBase {
+interface PolygonShapeSpec extends ShapeBase, Trimmable {
     shape: 'polygon';
     /** Vertices in local space. The path is auto-closed. */
     points: Array<[PropValue, PropValue]>;
     /** When true, draw an open polyline instead of a closed polygon. Default false. */
     open?: boolean;
 }
-interface PathShapeSpec extends ShapeBase {
+interface PathShapeSpec extends ShapeBase, Trimmable {
     shape: 'path';
     /** SVG path data (`d` attribute). Goes through PIXI's GraphicsContext.svg(). */
     d: string;

package/dist/{types-7VtTEKUW.d.ts → types-DrW9QeKU.d.ts}

@@ -212,6 +212,10 @@ interface TextSequenceSpec extends SequenceCommon {
      * 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`.
+     *
+     * The text can change over time: a keyframe `set: { text: 'Two' }` swaps the string at that time (and back when
+     * you seek back; a string cannot be tweened). `visibleChars` is a number that shows only the first N characters
+     * (a typewriter): `initial: { visibleChars: 0 }`, keyframe `to: { visibleChars: 20 }`. It starts at 0 once it is animated.
      */
     text?: string;
     /** How `{value}` is printed: `decimals` (default 0) and thousands `grouping` (default false). */
@@ -336,6 +340,18 @@ interface GradientSpec {
     /** radial: outer radius where the last stop applies, 0–1. Default 0.5. */
     radius?: number;
 }
+/**
+ * Stroke trim (draw-on): the part of the outline that is stroked, as fractions 0–1 of its length. Animate `trimEnd`
+ * from 0 to 1 to draw a line / path / outline on; animate both for a travelling dash. The outline of a rect starts at
+ * its top-left and goes clockwise, of a circle / ellipse at 12 o'clock and goes clockwise; a polygon's closing edge counts.
+ * The fill is not trimmed. Not for `arc` (animate its `endAngle`).
+ */
+interface Trimmable {
+    /** Where the stroke starts, 0–1 of the outline. Default 0. Animatable. */
+    trimStart?: PropValue;
+    /** Where the stroke ends, 0–1 of the outline. Default 1. Animatable. */
+    trimEnd?: PropValue;
+}
 interface ShapeBase extends SequenceCommon {
     type: 'shape';
     /** Fill with a gradient instead of `fillColor` (top level or in `initial`). */
@@ -358,7 +374,7 @@ interface ShapeBase extends SequenceCommon {
     /** How stroke corners join: `'miter'` (default; sharp points can poke out), `'round'` or `'bevel'`. Top level or in `initial`. */
     strokeJoin?: 'miter' | 'round' | 'bevel';
 }
-interface RectShapeSpec extends ShapeBase {
+interface RectShapeSpec extends ShapeBase, Trimmable {
     shape: 'rect';
     width: PropValue;
     height: PropValue;
@@ -373,14 +389,14 @@ interface RectShapeSpec extends ShapeBase {
     anchorX?: PropValue;
     anchorY?: PropValue;
 }
-interface CircleShapeSpec extends ShapeBase {
+interface CircleShapeSpec extends ShapeBase, Trimmable {
     shape: 'circle';
     radius: PropValue;
     /** See RectShapeSpec.anchorX. Default 0.5 (centre). */
     anchorX?: PropValue;
     anchorY?: PropValue;
 }
-interface EllipseShapeSpec extends ShapeBase {
+interface EllipseShapeSpec extends ShapeBase, Trimmable {
     shape: 'ellipse';
     radiusX: PropValue;
     radiusY: PropValue;
@@ -404,20 +420,20 @@ interface ArcShapeSpec extends ShapeBase {
     /** Degrees. Default 360. Animatable. */
     endAngle?: PropValue;
 }
-interface LineShapeSpec extends ShapeBase {
+interface LineShapeSpec extends ShapeBase, Trimmable {
     shape: 'line';
     /** Line endpoints relative to the shape's local origin. */
     from: [PropValue, PropValue];
     to: [PropValue, PropValue];
 }
-interface PolygonShapeSpec extends ShapeBase {
+interface PolygonShapeSpec extends ShapeBase, Trimmable {
     shape: 'polygon';
     /** Vertices in local space. The path is auto-closed. */
     points: Array<[PropValue, PropValue]>;
     /** When true, draw an open polyline instead of a closed polygon. Default false. */
     open?: boolean;
 }
-interface PathShapeSpec extends ShapeBase {
+interface PathShapeSpec extends ShapeBase, Trimmable {
     shape: 'path';
     /** SVG path data (`d` attribute). Goes through PIXI's GraphicsContext.svg(). */
     d: string;

package/docs/api.md

@@ -182,6 +182,7 @@ movie.off(event, fn): this
 | ----------- | ------------------------------------------------- | ----------------------------------------------------- |
 | `'ready'`   | none                                              | once, after `init()` resolves                         |
 | `'frame'`   | `{ frame: number; totalFrames: number }`          | every `gotoFrame` (so once per playback frame too)    |
+| `'play'`    | none                                              | when `play()` actually transitions from paused        |
 | `'pause'`   | none                                              | when `pause()` actually transitions from playing      |
 | `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
 

package/docs/dsl.md

@@ -71,7 +71,7 @@ A layer is **not removed** when its lifespan `[at, at + duration)` ends: it is o
 
 ### `text`
 
-Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content cannot change over time, with one exception: a `{value}` placeholder in `text` prints an animatable number (`text: '{value} users'`, `initial: { value: 0 }`, a keyframe `to: { value: 2480 }`; `format: { decimals, grouping }`) — that is how counters work. Any other change of wording is a second layer (stack layers with `at` / `duration`). Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
+Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content can change over time (see *Changing text* below): a `{value}` placeholder prints an animatable number (counters), a keyframe `set: { text: '…' }` swaps the string, and `visibleChars` types it out. Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
 
 ```ts
 {
@@ -103,6 +103,17 @@ The text's `fill` is also animatable via keyframes (under the `to`/`from`/`set`
 }
 ```
 
+#### Changing text: `set: { text }` and `visibleChars`
+
+A keyframe `set: { text: 'Two' }` swaps the string at that time (layer-local `at`, undone when you seek back; a string cannot be tweened, so `to` / `from` with `text` warn). A countdown is one layer:
+
+```ts
+{ type: 'text', text: '3', duration: 4, style: { fontSize: 150 }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+  keyframes: [{ at: 1, set: { text: '2' } }, { at: 2, set: { text: '1' } }, { at: 3, set: { text: 'Go!' } }] }
+```
+
+`visibleChars` is a number that shows only the first N characters (counted as you see them: an emoji is one): a typewriter. `initial: { visibleChars: 0 }` and a keyframe `to: { visibleChars: 30 }, duration: 2.4, ease: 'none'` types 30 characters over 2.4 s (it starts at 0 as soon as it is animated). Use a left-aligned layer (`anchorX: 0`, `style.align: 'left'`) so the text grows to the right instead of re-centring each letter; the layer's `w` / `h` are those of the whole text. `set: { text }` and `visibleChars` combine (swap the string, `set: { visibleChars: 0 }`, type it again), and so does a `{value}` placeholder in the string.
+
 #### Counters (`{value}`)
 
 A text layer has one animatable number, `value`, printed wherever the text contains `{value}`. Animate it with the normal keyframes (any ease, `from`/`to`/`set`, `repeat`):
@@ -250,13 +261,13 @@ Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `p
 
 | `shape`   | Required props                           | Optional               |
 |-----------|------------------------------------------|------------------------|
-| `rect`    | `width`, `height`                        | `cornerRadius`         |
-| `circle`  | `radius`                                 | —                      |
-| `ellipse` | `radiusX`, `radiusY`                     | —                      |
+| `rect`    | `width`, `height`                        | `cornerRadius`, `trimStart`, `trimEnd` |
+| `circle`  | `radius`                                 | `trimStart`, `trimEnd` |
+| `ellipse` | `radiusX`, `radiusY`                     | `trimStart`, `trimEnd` |
 | `arc`     | `radius`                                 | `innerRadius`, `startAngle` (0), `endAngle` (360) |
-| `line`    | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | — |
-| `polygon` | `points: [[x,y], …]`                     | `open` (default false) |
-| `path`    | `d` (SVG path data)                      | —                      |
+| `line`    | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | `trimStart`, `trimEnd` |
+| `polygon` | `points: [[x,y], …]`                     | `open` (default false), `trimStart`, `trimEnd` |
+| `path`    | `d` (SVG path data)                      | `trimStart`, `trimEnd` |
 
 **`arc`** is an arc around its local origin (the centre). Angles are in **degrees: 0° is 3 o'clock and positive is clockwise**, so a progress ring starts at `startAngle: -90` (12 o'clock) and animates `endAngle` from `-90` to `270`. With a stroke and no fill it is an open arc line (`strokeCap: 'round'` for rounded ends); with a fill it is a sector (a pie slice), and with `innerRadius` a ring segment (a donut slice). A sweep of 360° or more is a full circle; `endAngle < startAngle` sweeps counter-clockwise. `radius`, `innerRadius`, `startAngle` and `endAngle` are all animatable.
 
@@ -266,6 +277,14 @@ Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `p
   keyframes: [{ at: 0, to: { endAngle: 270 }, duration: 2, ease: 'power3.out' }] }   // a progress ring filling clockwise from the top
 ```
 
+**Draw-on (`trimStart` / `trimEnd`).** On every shape except `arc`, `trimStart` and `trimEnd` (0–1, default 0 and 1, both animatable) are the part of the outline that is stroked, as fractions of its length. Animate `trimEnd` from 0 to 1 to draw a line, border or SVG path on; animate `trimStart` after it to wipe it off the same way; animate both for a travelling dash. A rect's outline starts at its top-left and goes clockwise, a circle / ellipse's at 12 o'clock and goes clockwise, a polygon's includes its closing edge, and a path's several sub-paths count as one length in order. **The fill is not trimmed** (the whole shape stays filled): fade `fillAlpha` in after the draw-on. Use `strokeCap: 'round'` for a friendly end. For `arc`, animate `endAngle` instead (a `trim…` on an arc warns).
+
+```ts
+{ type: 'shape', shape: 'path', d: 'M 0 50 L 45 95 L 130 0', trimEnd: 0, strokeCap: 'round', strokeJoin: 'round',
+  initial: { x: 1040, y: 270, strokeColor: '#7bd88f', strokeWidth: 16 },
+  keyframes: [{ at: 0, to: { trimEnd: 1 }, duration: 1, ease: 'power2.inOut' }] }   // a check mark drawing itself
+```
+
 `strokeCap` (`'butt'`, `'round'`, `'square'`) and `strokeJoin` (`'miter'`, `'round'`, `'bevel'`) work on every shape, at the top level or in `initial`; they are not animated. Sharp corners (the apex of an M in outlined text, a thin polygon) poke out with the default `miter` join: use `'round'`.
 
 **Style** is set on `initial` and animatable via keyframes:

package/llms-full.txt

@@ -104,7 +104,7 @@ Keyframe kinds: `set` (jump at `at`; undone when you seek back), `to` (animate t
 
 ## 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, pad /* zero-pad the whole part: pad 2 → 05 */ }`) — that is how counters work. Other content cannot change over time. Multi-line text is centre-aligned by default (`style.align: 'left'` to change).
+**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, pad /* zero-pad the whole part: pad 2 → 05 */ }`) — that is how counters work. **Changing text:** a keyframe `set: { text: 'Two' }` swaps the string at that time (undone on seek back; `to` / `from` cannot tween a string); `visibleChars` (number, first N characters; starts at 0 once animated) is a typewriter: `to: { visibleChars: 30 }, duration: 2.4, ease: 'none'` — use `anchorX: 0` + `style.align: 'left'` so it grows rightward. 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`.
 
@@ -125,6 +125,8 @@ Keyframe kinds: `set` (jump at `at`; undone when you seek back), `to` (animate t
 | polygon | `points: [[x,y],…]  open` — canvas coordinates like `line` |
 | path | `d` (SVG path data) — canvas coordinates like `line` |
 
+**Draw-on:** every shape but `arc` has `trimStart` / `trimEnd` (0–1 of the outline, default 0 / 1, animatable): `trimEnd: 0` + keyframe `to: { trimEnd: 1 }` draws a line / border / path on; `trimStart` 0 → 1 after it wipes it off; both = a travelling dash. The fill is NOT trimmed. Rect outline starts top-left, circle / ellipse at 12 o'clock, both clockwise. Use `strokeCap: 'round'`.
+
 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. Stroke ends and corners: `strokeCap: 'butt'|'round'|'square'`, `strokeJoin: 'miter'|'round'|'bevel'` (top level or in `initial`; not animated — `round` keeps sharp corners like an M from poking out).
 
 **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; a plain 2D composition does not clip, but is skipped when its whole rectangle is off screen) 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.
@@ -269,6 +271,7 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 50. **An image (or video) works as a mask, `maskInverted` included** *(fixed)*: PIXI hides a sprite mask with `renderable = false` and the lifespan toggles used to switch it back on, so the mask picture was drawn over the layer (a white disc) and `maskInverted` looked ignored. Use the picture's alpha (or red channel) as the shape: an opaque word or logo on a transparent canvas image is a text-shaped mask with real glyph edges. A `text` layer also works as a mask (cut to its glyphs; measured with a heavy sans `I`). *(docs / fixed)*
 51. **Arcs and rings are `shape: 'arc'`** (`radius`, `innerRadius`, `startAngle`, `endAngle`, degrees; 0° = 3 o'clock, clockwise). A progress ring is an arc with `startAngle: -90` and an animated `endAngle` (−90 → 270); `strokeCap: 'round'` rounds BOTH ends. Fill it for a pie slice, add `innerRadius` for a donut slice (a 120-polygon donut is no longer needed). Style (`strokeColor`, `strokeWidth`, `fillColor`) goes in `initial`; `strokeCap` / `strokeJoin` may be top level. *(fixed)*
 52. **Measure and split text with `measureText` / `splitText`, not by hand.** `splitText(text, style, { by, x, y, align })` returns each piece's x / y / width in the renderer's own font metrics (kerning kept; verified: a whole line vs the same line in per-letter layers differs only by anti-aliasing). The pieces are for text layers with the default top-left anchor and the same `style`. Load a web font before measuring (`await document.fonts.load('24px "Name"')`) or the fallback font's widths are used. Size a pill from `measureText(...).width + padding` instead of `0.58 × fontSize × length`. *(fixed)*
+53. **Draw-on and typewriter need no masks or per-letter layers.** `trimStart` / `trimEnd` (0–1 of the outline, animatable, every shape but `arc`) draw a stroke on: `trimEnd: 0` plus a keyframe `to: { trimEnd: 1 }`. The fill is not trimmed, so fade `fillAlpha` in afterwards; use `strokeCap: 'round'`. Text changes over time with `set: { text }` (swap at a time) and `visibleChars` (typewriter; left-align it so it grows rightward). A `to: { text }` cannot tween a string and warns. *(fixed)*
 
 
 <!-- ===== ai/reference/recipes.md ===== -->
@@ -527,7 +530,7 @@ return [
 
 ## Slideshow with transitions and background music
 
-Scene `i` starts at `i × (L − T)` and overlaps the next by the transition length `T`; the transition's `at` is the next scene's start; total = `n × (L − T) + T`. Transitions and `kenBurns` combine freely. Captions are top-level layers (transitions never touch layers they do not name); keep them above the bottom ~60 px. `bgm.mp3` is only 6 s: **`loop: true`** or it falls silent.
+Scene `i` starts at `i × (L − T)` and overlaps the next by the transition length `T`; the transition's `at` is the next scene's start; total = `n × (L − T) + T`. Transitions and `kenBurns` combine freely. Captions are top-level layers (transitions never touch layers they do not name); keep them above the bottom ~60 px. A music file shorter than the movie (`bgm.mp3` is a 16 s loop) needs **`loop: true`** or it falls silent.
 
 ```js
 // @recipe slideshow
@@ -647,6 +650,41 @@ return [
 
 ---
 
+## Draw a line, border or check mark on, and type text out
+
+`trimEnd` 0 → 1 strokes a shape's outline on (`trimStart` 0 → 1 afterwards wipes it off); the fill is NOT trimmed, so fade `fillAlpha` in once the outline is done. A rect's outline starts top-left and goes clockwise, a circle's at 12 o'clock. `strokeCap: 'round'` rounds the ends. For text, `visibleChars` types it out and `set: { text }` swaps the string at a time.
+
+```js
+// @recipe draw-on-and-type
+const ACCENT = '#ffd166', TEAL = '#4cc9f0', GREEN = '#7bd88f';
+const drawOn = (at, duration = 1.2) => ({ at, to: { trimEnd: 1 }, duration, ease: 'power2.inOut' });
+return [
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0a0e1a' } },
+  // an underline that draws itself
+  { type: 'shape', shape: 'line', from: [340, 120], to: [940, 120], trimEnd: 0, strokeCap: 'round',
+    initial: { strokeColor: ACCENT, strokeWidth: 6 }, keyframes: [drawOn(0.2, 1)] },
+  // a card border (clockwise from the top-left), then its fill fades in
+  { type: 'shape', shape: 'rect', width: 360, height: 200, cornerRadius: 28, trimEnd: 0, strokeJoin: 'round',
+    initial: { x: 400, y: 360, strokeColor: TEAL, strokeWidth: 8, fillColor: TEAL, fillAlpha: 0 },
+    keyframes: [drawOn(0.6, 1.4), { at: 2, to: { fillAlpha: 0.2 }, duration: 0.6 }] },
+  // an SVG check mark
+  { type: 'shape', shape: 'path', d: 'M 0 50 L 45 95 L 130 0', trimEnd: 0, strokeCap: 'round', strokeJoin: 'round',
+    initial: { x: 880, y: 360, strokeColor: GREEN, strokeWidth: 16 }, keyframes: [drawOn(1.8, 0.9)] },
+  // a typewriter: left-aligned so it grows rightward; 30 characters over 2.4 s
+  { type: 'text', text: 'No mask, no per-letter layers.', at: 3, duration: 5,
+    style: { fontSize: 40, fill: '#e8eefc', fontFamily: 'ui-monospace, Menlo, monospace' },
+    initial: { x: 120, y: 560, anchorX: 0, anchorY: 0.5, visibleChars: 0 },
+    keyframes: [{ at: 0, to: { visibleChars: 30 }, duration: 2.4, ease: 'none' }] },
+  // a countdown: one layer whose string changes
+  { type: 'text', text: '3', at: 3, duration: 5,
+    style: { fontSize: 150, fontWeight: '900', fill: ACCENT },
+    initial: { x: 1060, y: 540, anchorX: 0.5, anchorY: 0.5 },
+    keyframes: [{ at: 1, set: { text: '2' } }, { at: 2, set: { text: '1' } }, { at: 3, set: { text: 'Go!' } }] },
+];
+```
+
+---
+
 ## Letters and words that animate one by one (`splitText`)
 
 Text content cannot change, so a per-letter or per-word effect is one text layer per piece. `splitText(text, style, { by: 'chars' | 'words' | 'lines', x, y, align })` measures the text with the renderer's own font metrics (kerning kept) and returns each piece's `text`, `x`, `y`, `width`, `index` and `line`: put them straight into the layers. Use the same `style` for the whole text and each piece, and a web font must be loaded first. `measureText(text, style)` gives `{ width, height, lines }` for sizing pills and underlines.
@@ -842,7 +880,7 @@ A layer is **not removed** when its lifespan `[at, at + duration)` ends: it is o
 
 ### `text`
 
-Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content cannot change over time, with one exception: a `{value}` placeholder in `text` prints an animatable number (`text: '{value} users'`, `initial: { value: 0 }`, a keyframe `to: { value: 2480 }`; `format: { decimals, grouping }`) — that is how counters work. Any other change of wording is a second layer (stack layers with `at` / `duration`). Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
+Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content can change over time (see *Changing text* below): a `{value}` placeholder prints an animatable number (counters), a keyframe `set: { text: '…' }` swaps the string, and `visibleChars` types it out. Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
 
 ```ts
 {
@@ -874,6 +912,17 @@ The text's `fill` is also animatable via keyframes (under the `to`/`from`/`set`
 }
 ```
 
+#### Changing text: `set: { text }` and `visibleChars`
+
+A keyframe `set: { text: 'Two' }` swaps the string at that time (layer-local `at`, undone when you seek back; a string cannot be tweened, so `to` / `from` with `text` warn). A countdown is one layer:
+
+```ts
+{ type: 'text', text: '3', duration: 4, style: { fontSize: 150 }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+  keyframes: [{ at: 1, set: { text: '2' } }, { at: 2, set: { text: '1' } }, { at: 3, set: { text: 'Go!' } }] }
+```
+
+`visibleChars` is a number that shows only the first N characters (counted as you see them: an emoji is one): a typewriter. `initial: { visibleChars: 0 }` and a keyframe `to: { visibleChars: 30 }, duration: 2.4, ease: 'none'` types 30 characters over 2.4 s (it starts at 0 as soon as it is animated). Use a left-aligned layer (`anchorX: 0`, `style.align: 'left'`) so the text grows to the right instead of re-centring each letter; the layer's `w` / `h` are those of the whole text. `set: { text }` and `visibleChars` combine (swap the string, `set: { visibleChars: 0 }`, type it again), and so does a `{value}` placeholder in the string.
+
 #### Counters (`{value}`)
 
 A text layer has one animatable number, `value`, printed wherever the text contains `{value}`. Animate it with the normal keyframes (any ease, `from`/`to`/`set`, `repeat`):
@@ -1021,13 +1070,13 @@ Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `p
 
 | `shape`   | Required props                           | Optional               |
 |-----------|------------------------------------------|------------------------|
-| `rect`    | `width`, `height`                        | `cornerRadius`         |
-| `circle`  | `radius`                                 | —                      |
-| `ellipse` | `radiusX`, `radiusY`                     | —                      |
+| `rect`    | `width`, `height`                        | `cornerRadius`, `trimStart`, `trimEnd` |
+| `circle`  | `radius`                                 | `trimStart`, `trimEnd` |
+| `ellipse` | `radiusX`, `radiusY`                     | `trimStart`, `trimEnd` |
 | `arc`     | `radius`                                 | `innerRadius`, `startAngle` (0), `endAngle` (360) |
-| `line`    | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | — |
-| `polygon` | `points: [[x,y], …]`                     | `open` (default false) |
-| `path`    | `d` (SVG path data)                      | —                      |
+| `line`    | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | `trimStart`, `trimEnd` |
+| `polygon` | `points: [[x,y], …]`                     | `open` (default false), `trimStart`, `trimEnd` |
+| `path`    | `d` (SVG path data)                      | `trimStart`, `trimEnd` |
 
 **`arc`** is an arc around its local origin (the centre). Angles are in **degrees: 0° is 3 o'clock and positive is clockwise**, so a progress ring starts at `startAngle: -90` (12 o'clock) and animates `endAngle` from `-90` to `270`. With a stroke and no fill it is an open arc line (`strokeCap: 'round'` for rounded ends); with a fill it is a sector (a pie slice), and with `innerRadius` a ring segment (a donut slice). A sweep of 360° or more is a full circle; `endAngle < startAngle` sweeps counter-clockwise. `radius`, `innerRadius`, `startAngle` and `endAngle` are all animatable.
 
@@ -1037,6 +1086,14 @@ Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `p
   keyframes: [{ at: 0, to: { endAngle: 270 }, duration: 2, ease: 'power3.out' }] }   // a progress ring filling clockwise from the top
 ```
 
+**Draw-on (`trimStart` / `trimEnd`).** On every shape except `arc`, `trimStart` and `trimEnd` (0–1, default 0 and 1, both animatable) are the part of the outline that is stroked, as fractions of its length. Animate `trimEnd` from 0 to 1 to draw a line, border or SVG path on; animate `trimStart` after it to wipe it off the same way; animate both for a travelling dash. A rect's outline starts at its top-left and goes clockwise, a circle / ellipse's at 12 o'clock and goes clockwise, a polygon's includes its closing edge, and a path's several sub-paths count as one length in order. **The fill is not trimmed** (the whole shape stays filled): fade `fillAlpha` in after the draw-on. Use `strokeCap: 'round'` for a friendly end. For `arc`, animate `endAngle` instead (a `trim…` on an arc warns).
+
+```ts
+{ type: 'shape', shape: 'path', d: 'M 0 50 L 45 95 L 130 0', trimEnd: 0, strokeCap: 'round', strokeJoin: 'round',
+  initial: { x: 1040, y: 270, strokeColor: '#7bd88f', strokeWidth: 16 },
+  keyframes: [{ at: 0, to: { trimEnd: 1 }, duration: 1, ease: 'power2.inOut' }] }   // a check mark drawing itself
+```
+
 `strokeCap` (`'butt'`, `'round'`, `'square'`) and `strokeJoin` (`'miter'`, `'round'`, `'bevel'`) work on every shape, at the top level or in `initial`; they are not animated. Sharp corners (the apex of an M in outlined text, a thin polygon) poke out with the default `miter` join: use `'round'`.
 
 **Style** is set on `initial` and animatable via keyframes:
@@ -2026,6 +2083,7 @@ movie.off(event, fn): this
 | ----------- | ------------------------------------------------- | ----------------------------------------------------- |
 | `'ready'`   | none                                              | once, after `init()` resolves                         |
 | `'frame'`   | `{ frame: number; totalFrames: number }`          | every `gotoFrame` (so once per playback frame too)    |
+| `'play'`    | none                                              | when `play()` actually transitions from paused        |
 | `'pause'`   | none                                              | when `pause()` actually transitions from playing      |
 | `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixi-effects",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Declarative composition and video rendering for the web. Built on PixiJS v8.",
   "type": "module",
   "exports": {

package/dist/Composition-63EXHNJJ.cjs

@@ -1,13 +0,0 @@
-'use strict';
-
-var chunk23M5QTWW_cjs = require('./chunk-23M5QTWW.cjs');
-require('./chunk-2RR43OIN.cjs');
-
-
-
-Object.defineProperty(exports, "CompositionSequence", {
-  enumerable: true,
-  get: function () { return chunk23M5QTWW_cjs.CompositionSequence; }
-});
-//# sourceMappingURL=Composition-63EXHNJJ.cjs.map
-//# sourceMappingURL=Composition-63EXHNJJ.cjs.map

package/dist/Composition-TUCRSMJU.js

@@ -1,4 +0,0 @@
-export { CompositionSequence } from './chunk-5Q5XZG7Z.js';
-import './chunk-UBPZLGLU.js';
-//# sourceMappingURL=Composition-TUCRSMJU.js.map
-//# sourceMappingURL=Composition-TUCRSMJU.js.map