@pixodesk/svg-animator-web 1.0.30 → 1.0.35

package/README.md

@@ -1,5 +1,7 @@
 # animator-web
 
+> 📖 Full user guide: [docs/library/web-player.md](../../docs/library/web-player.md) · [all docs](../../README.md#documentation)
+
 [![CI](https://github.com/pixodesk/pixodesk-svg-animator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/pixodesk/pixodesk-svg-animator/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -65,11 +67,11 @@ const animator = createAnimator({
 });
 
 // Or from an already-loaded document object
-const animator = createAnimator({ data: animationDoc, container: '#container' });
+const fromObject = createAnimator({ data: animationDoc, container: '#container' });
 
 animator.play();
 animator.pause();
-animator.setCurrentTime(500);   // seek to 500ms
+animator.setCurrentTime(500);   // jump to 0.5 s from the start
 animator.setPlaybackRate(2);    // 2x speed (-1 plays in reverse)
 animator.finish();              // jump to end
 animator.destroy();             // cleanup
@@ -86,6 +88,24 @@ animator.destroy();             // cleanup
 | `container` | `string \| Element`       | CSS selector or element to render the SVG into      |
 | `callbacks` | `PxAnimatorCallbacksConfig` | Lifecycle callbacks (see below)                   |
 | `adapter`   | `PxPlatformAdapter`       | Custom attribute-writer for frame-loop rendering (advanced) |
+| `config`    | `object \| string`        | Per-instance playback override, deep-merged over the document's `animator` block — same shape as the file; `null` at a slot deletes that key. A JSON string is accepted too |
+| `resetDocDefaults` | `boolean`          | Ignore the document's playback settings and start from the player's defaults, with `config` on top |
+| `duration` · `delay` | `number`        | Shortcuts for `config.timeline.duration` / `.delay` (ms) |
+| `iterations` | `number \| 'infinite'`   | Shortcut for `config.timeline.iterations` |
+| `startOn`   | `StartOn`                 | Shortcut for `config.timeline.trigger.startOn` |
+
+The document plays the way it was designed with no configuration at all; `config` is for when
+one page needs it to play differently — the same file mounted twice at two speeds, or a file
+that autostarts everywhere except inside your own transport UI:
+
+```js
+const animator = createAnimator({
+  src: '/animation.json',
+  container: '#box',
+  config: { timeline: { iterations: 'infinite', trigger: { startOn: 'programmatic' } } },
+});
+animator.play();
+```
 
 It returns a `PxAnimatorAPI`:
 
@@ -97,7 +117,7 @@ It returns a `PxAnimatorAPI`:
 | `finish()`              | Jump to the end                                                   |
 | `setPlaybackRate(rate)` | Change speed (1 = normal, 2 = double, -1 = reverse)               |
 | `getCurrentTime()`      | Current time in ms                                                |
-| `setCurrentTime(ms)`    | Seek to a specific time                                           |
+| `setCurrentTime(ms)`    | Jump to a point in the animation, in milliseconds from its start |
 | `isPlaying()`           | Whether the animation is currently playing                        |
 | `isReady()`             | Whether the document has loaded (relevant for URL-based creation) |
 | `getRootElement()`      | The rendered SVG DOM element                                      |
@@ -119,30 +139,30 @@ createAnimator({
 });
 ```
 
-### Engine modes
+### Engines
 
-`animator.mode` selects the playback engine:
+`animator.timeline.engine` selects how the animated attributes get updated:
 
-- `'auto'` (default) — try the Web Animations API, fall back to `requestAnimationFrame`.
-- `'waapi'` — Web Animations API only.
-- `'frames'` — `requestAnimationFrame` only; honours `animator.frameRate`. Required for path morphing.
+- `'auto'` (default) — the browser where it can (Web Animations API; its ScrollTimeline for scroll-driven documents), the player's frame loop where it must.
+- `'native'` — the browser only (Web Animations API).
+- `'js'` — the player's `requestAnimationFrame` loop only; honours `timeline.frameRate`. Required for path morphing in Safari < 18.5.
 
 ### Document format & effects
 
 The `doc` passed to `createAnimator` is a `PxAnimatedSvgDocument` (`type: 'svg'`), the
 same shape as the JSON export. It comes in two modes:
 
-- **Mode A** — has `children`: the player renders the SVG tree and animates it.
-- **Mode B** — no `children`: the player animates a pre-existing SVG DOM, mapping
+- **Self-contained document** — has `children`: the player renders the SVG tree and animates it.
+- **Bind-by-id document** — no `children`: the player animates a pre-existing SVG DOM, mapping
   element ids to animation specs via `animator.animateById`.
 
 Elements may also carry a `node.effects` bucket (structural effects such as
 `transformBy`, `repeater`, `maskedBy`, `strokeTrim`, `clone`, `fillGradient` /
-`strokeGradient`, `textAlongPath`). This player materialises and removes them at
+`strokeGradient`, `textPath`). This player materialises and removes them at
 runtime before any other normalisation.
 
-See the [file-format reference](../../README.md#file-formats) and the
-[Player effects](../../README.md#player-effects-nodeeffects) section in the root
-README for the full schema and examples. The wire types live in
-[`PxAnimatorTypes.ts`](src/PxAnimatorTypes.ts).
+See the [JSON format reference](../../docs/format/README.md#json-format-reference) and
+[Player effects](../../docs/format/README.md#player-effects) for the full schema and
+examples (compact printable schema: [SCHEMA.md](../../SCHEMA.md)). The wire
+types live in [`PxAnimatorTypes.ts`](../svg-animator-core/src/format/PxAnimatorTypes.ts).