@pixodesk/svg-animator-core 1.0.43 → 1.0.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -60,7 +60,7 @@ runtime crash on a non-browser platform.
60
60
  | **Text** | `materializeGlyphText`, `layoutGlyphTextChars`, `extendedPathForBrowser` |
61
61
  | **Node helpers** | `toDomProps`, `sanitizeAttributeValue`, `generateNewIds` |
62
62
  | **Playback engine** | `createAdapterAnimator` + the `PxPlatformAdapter` interface |
63
- | **Wire enums** | `PxTimelineEngine` / `PxTimelineEngineSetting`, `PxStartOn`, `PxOutAction`, `PxFinishAction`, `PxFillMode`, `PxPlaybackDirection`, `PxScrollKind`, `PxScrollAxis`, `PxScrollSource`, `PxScrollPhase`, `PxPinAlign`, `PxAlongPathMode`, `PxLoopRepeatAt`, `PxLoopDirection`, `PxStrokeTrimSubPaths`, `PxMaskType`, `PxCloneWithout`, `PxUnits`, `PxGradientType`, `PxGradientSpreadMethod`, `PxPathOverflow`, `PxLengthAdjust`, `PxTextPathMethod`, `PxTextPathSpacing` — every two-or-more-way wire selector is a named enum, not a bare string. Each is a const namespace AND the string type derived from it under the same name, so `PxStartOn.click` and `startOn?: PxStartOn` come from one import |
63
+ | **Wire enums** | `PxTimelineEngine` / `PxTimelineEngineSetting`, `PxTriggerStart`, `PxOffScreenAction`, `PxMouseOutAction`, `PxFinishAction`, `PxFillMode`, `PxPlaybackDirection`, `PxScrollKind`, `PxScrollAxis`, `PxScrollSource`, `PxScrollPhase`, `PxPinAlign`, `PxAlongPathMode`, `PxLoopRepeatAt`, `PxLoopDirection`, `PxStrokeTrimSubPaths`, `PxMaskType`, `PxCloneWithout`, `PxUnits`, `PxGradientType`, `PxGradientSpreadMethod`, `PxPathOverflow`, `PxLengthAdjust`, `PxTextPathMethod`, `PxTextPathSpacing` — every two-or-more-way wire selector is a named enum, not a bare string. Each is a const namespace AND the string type derived from it under the same name, so `PxTriggerStart.click` and `start?: PxTriggerStart` come from one import |
64
64
 
65
65
  ### Validating a document
66
66
 
@@ -311,10 +311,10 @@ declare const PX_WIRE_BASELINE_VERSION = "1.1";
311
311
  /**
312
312
  * Every `b` step from {@link PX_WIRE_BASELINE_VERSION} to {@link PX_WIRE_SCHEMA_VERSION}.
313
313
  *
314
- * EMPTY IS CORRECT TODAY: 1.1 is the baseline and nothing has moved since. It exists now because
315
- * the guard spec keys off it — bump `PX_WIRE_SCHEMA_VERSION` without adding the matching step
316
- * and the suite fails naming the gap. That is the whole point: the last three renames shipped
317
- * because nothing forced anyone to say they had happened.
314
+ * One step so far: the 1.2 trigger block. The guard spec keys off this table — bump
315
+ * `PX_WIRE_SCHEMA_VERSION` without adding the matching step and the suite fails naming the gap.
316
+ * That is the whole point: the last three renames shipped because nothing forced anyone to say
317
+ * they had happened.
318
318
  * @public @advanced
319
319
  */
320
320
  declare const PX_WIRE_STEPS: ReadonlyArray<PxWireVersionStep>;
@@ -404,24 +404,36 @@ type PxPlaybackDirection = typeof PxPlaybackDirection[keyof typeof PxPlaybackDir
404
404
  declare const PX_ANIM_SRC_ATTR_NAME = "data-px-animation-src";
405
405
  /** @internal */
406
406
  declare const PX_ANIM_ATTR_NAME = "_px_animator";
407
- /** `trigger.startOn` — what starts the animation. `programmatic` waits for `play()`. @public */
408
- declare const PxStartOn: {
407
+ /** `trigger.start` — what starts the animation. `none` waits for `play()`.
408
+ *
409
+ * There is no `scrollIntoView` member: visibility is not a trigger but a permission, and it is
410
+ * governed by `offScreen` + `visibilityThreshold` whatever starts the animation. `start: 'load'`
411
+ * behind the default gate is what `startOn: 'scrollIntoView'` used to mean. @public */
412
+ declare const PxTriggerStart: {
409
413
  readonly load: "load";
410
414
  readonly mouseOver: "mouseOver";
411
415
  readonly click: "click";
412
- readonly scrollIntoView: "scrollIntoView";
413
- readonly programmatic: "programmatic";
416
+ readonly none: "none";
414
417
  };
415
- type PxStartOn = typeof PxStartOn[keyof typeof PxStartOn];
416
- /** `trigger.outAction` — what happens when the trigger condition stops holding. @public */
417
- declare const PxOutAction: {
418
+ type PxTriggerStart = typeof PxTriggerStart[keyof typeof PxTriggerStart];
419
+ /** `trigger.offScreen` — what happens while none of the graphic is on screen. No `reverse`:
420
+ * nobody can watch an animation play backwards off screen. @public */
421
+ declare const PxOffScreenAction: {
422
+ readonly pause: "pause";
423
+ readonly continue: "continue";
424
+ readonly reset: "reset";
425
+ };
426
+ type PxOffScreenAction = typeof PxOffScreenAction[keyof typeof PxOffScreenAction];
427
+ /** `trigger.mouseOut` — what happens when the pointer leaves. Read only when
428
+ * `start` is `mouseOver`. @public */
429
+ declare const PxMouseOutAction: {
418
430
  readonly continue: "continue";
419
431
  readonly pause: "pause";
420
432
  readonly reset: "reset";
421
433
  readonly reverse: "reverse";
422
434
  };
423
- type PxOutAction = typeof PxOutAction[keyof typeof PxOutAction];
424
- /** `trigger.finishAction` — what happens after a NATURAL finish. @public */
435
+ type PxMouseOutAction = typeof PxMouseOutAction[keyof typeof PxMouseOutAction];
436
+ /** `trigger.finish` — what happens after a NATURAL finish. @public */
425
437
  declare const PxFinishAction: {
426
438
  readonly hold: "hold";
427
439
  readonly reset: "reset";
@@ -519,21 +531,27 @@ declare function mayUseNativeScrollTimeline(engine: PxTimelineEngineSetting | un
519
531
  * THE TRIGGER DEFAULTS — what a missing `trigger` field means. One table, declared by
520
532
  * `PxTriggerSchema` and applied by {@link resolveTrigger}, which every player calls (the web's
521
533
  * `setupAnimationTriggers`, the React Native component) — so a file behaves the same everywhere:
522
- * - `startOn` 'load' — a document is designed to play
523
- * - `outAction` 'continue' — leaving the trigger does not interrupt playback
524
- * - `scrollIntoViewThreshold` 0 — any visible pixel counts
534
+ * - `start` 'load' — a document is designed to play
535
+ * - `offScreen` 'pause' — an animation nobody can see does not run
536
+ * - `mouseOut` 'continue' — leaving the element does not interrupt playback
537
+ * - `visibilityThreshold` 0.5 — half of it must be on screen before it may run
538
+ * - `visibilityDebounce` 150 — and stay that way this long, so a fast scroll past starts nothing
525
539
  * @public @advanced
526
540
  */
527
541
  declare const PX_TRIGGER_DEFAULTS: {
528
- readonly startOn: "load";
529
- readonly outAction: "continue";
530
- readonly scrollIntoViewThreshold: 0;
542
+ readonly start: "load";
543
+ readonly offScreen: "pause";
544
+ readonly mouseOut: "continue";
545
+ readonly visibilityThreshold: 0.5;
546
+ readonly visibilityDebounce: 150;
531
547
  };
532
548
  /** A trigger with every default filled in. @public @advanced */
533
549
  interface PxResolvedTrigger {
534
- readonly startOn: NonNullable<PxTrigger['startOn']>;
535
- readonly outAction: NonNullable<PxTrigger['outAction']>;
536
- readonly scrollIntoViewThreshold: number;
550
+ readonly start: NonNullable<PxTrigger['start']>;
551
+ readonly offScreen: NonNullable<PxTrigger['offScreen']>;
552
+ readonly mouseOut: NonNullable<PxTrigger['mouseOut']>;
553
+ readonly visibilityThreshold: number;
554
+ readonly visibilityDebounce: number;
537
555
  }
538
556
  /** Which props drive playback. `apiRef` is deliberately NOT a mode: the handle is filled in
539
557
  * every mode, so passing it alone leaves the document's own trigger in charge. * @public
@@ -568,7 +586,7 @@ interface PxControlProps {
568
586
  play?: boolean;
569
587
  /** Hold the current frame; set it back to `false` to resume. */
570
588
  pause?: boolean;
571
- /** Start the way the document says — its own `startOn` / `outAction` trigger. */
589
+ /** Start the way the document says — its own `trigger` block. */
572
590
  autoplay?: boolean;
573
591
  }
574
592
  /** The chosen mode plus any conflict warnings — ready-made sentences, so three components
@@ -597,7 +615,7 @@ interface PxResolvedControlMode {
597
615
  declare function resolveControlMode(props: PxControlProps): PxResolvedControlMode;
598
616
  /**
599
617
  * True when the component must take the document's trigger over, by forcing
600
- * `startOn: 'programmatic'` into its config patch.
618
+ * `start: 'none'` into its config patch.
601
619
  *
602
620
  * Every mode except `autoplay` — INCLUDING `static`. A component given no control props at all
603
621
  * must not start on its own: `<PixodeskSvgAnimator doc={…} />` renders the first frame and waits.
@@ -605,7 +623,7 @@ declare function resolveControlMode(props: PxControlProps): PxResolvedControlMod
605
623
  * @public
606
624
  */
607
625
  declare function controlModeTakesOverTrigger(mode: PxControlMode): boolean;
608
- /** A document's trigger with the defaults filled in. (`finishAction` is not a start/stop decision:
626
+ /** A document's trigger with the defaults filled in. (`finish` is not a start/stop decision:
609
627
  * it reaches the engines as the runtime view's `resetOnFinish`.) * @public @advanced
610
628
  */
611
629
  declare function resolveTrigger(trigger: PxTrigger | undefined): PxResolvedTrigger;
@@ -1470,16 +1488,20 @@ declare const PxElementAnimationSchema: PxSchema<string | Record<string, {} & {
1470
1488
  type PxElementAnimation = PxInfer<typeof PxElementAnimationSchema>;
1471
1489
  /** @public @advanced */
1472
1490
  declare const PxTriggerSchema: PxSchema<{} & {
1473
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
1474
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
1475
- finishAction?: "reset" | "hold" | undefined;
1476
- scrollIntoViewThreshold?: number | undefined;
1491
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
1492
+ offScreen?: "continue" | "pause" | "reset" | undefined;
1493
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
1494
+ finish?: "reset" | "hold" | undefined;
1495
+ visibilityThreshold?: number | undefined;
1496
+ visibilityDebounce?: number | undefined;
1477
1497
  }, false> & {
1478
1498
  readonly _shape: {
1479
- startOn: PxSchema<"load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined, true>;
1480
- outAction: PxSchema<"reverse" | "continue" | "pause" | "reset" | undefined, true>;
1481
- finishAction: PxSchema<"reset" | "hold" | undefined, true>;
1482
- scrollIntoViewThreshold: PxSchema<number | undefined, true>;
1499
+ start: PxSchema<"none" | "mouseOver" | "load" | "click" | undefined, true>;
1500
+ offScreen: PxSchema<"continue" | "pause" | "reset" | undefined, true>;
1501
+ mouseOut: PxSchema<"reverse" | "continue" | "pause" | "reset" | undefined, true>;
1502
+ finish: PxSchema<"reset" | "hold" | undefined, true>;
1503
+ visibilityThreshold: PxSchema<number | undefined, true>;
1504
+ visibilityDebounce: PxSchema<number | undefined, true>;
1483
1505
  };
1484
1506
  };
1485
1507
  /** Defines when and how an animation should be triggered. @public */
@@ -1701,14 +1723,16 @@ declare const PxTimelineSchema: PxSchema<({} & {
1701
1723
  frameRate?: number | undefined;
1702
1724
  duration?: number | undefined;
1703
1725
  trigger?: ({} & {
1704
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
1705
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
1706
- finishAction?: "reset" | "hold" | undefined;
1707
- scrollIntoViewThreshold?: number | undefined;
1726
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
1727
+ offScreen?: "continue" | "pause" | "reset" | undefined;
1728
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
1729
+ finish?: "reset" | "hold" | undefined;
1730
+ visibilityThreshold?: number | undefined;
1731
+ visibilityDebounce?: number | undefined;
1708
1732
  }) | undefined;
1709
1733
  delay?: number | undefined;
1710
1734
  iterations?: number | "infinite" | undefined;
1711
- fillMode?: "forwards" | "backwards" | "both" | "none" | undefined;
1735
+ fillMode?: "none" | "forwards" | "backwards" | "both" | undefined;
1712
1736
  direction?: "reverse" | "normal" | "alternate" | "alternate-reverse" | undefined;
1713
1737
  }) | ({
1714
1738
  type: "scroll";
@@ -1827,7 +1851,7 @@ interface _PxAnimatorConfig {
1827
1851
  *
1828
1852
  * The wire spells this as `timeline.type` ('time' — or absent — vs 'scroll'/'view');
1829
1853
  * `flattenAnimatorTimeline` folds it into this field for the engines.
1830
- * Distinct from `trigger.startOn`, which says what STARTS the animation: one
1854
+ * Distinct from `trigger.start`, which says what STARTS the animation: one
1831
1855
  * names the beginning, this one names what moves the playhead afterwards.
1832
1856
  * Design: app `svgeditor/animation/scroll-timeline.design.md`.
1833
1857
  */
@@ -1888,14 +1912,16 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
1888
1912
  frameRate?: number | undefined;
1889
1913
  duration?: number | undefined;
1890
1914
  trigger?: ({} & {
1891
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
1892
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
1893
- finishAction?: "reset" | "hold" | undefined;
1894
- scrollIntoViewThreshold?: number | undefined;
1915
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
1916
+ offScreen?: "continue" | "pause" | "reset" | undefined;
1917
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
1918
+ finish?: "reset" | "hold" | undefined;
1919
+ visibilityThreshold?: number | undefined;
1920
+ visibilityDebounce?: number | undefined;
1895
1921
  }) | undefined;
1896
1922
  delay?: number | undefined;
1897
1923
  iterations?: number | "infinite" | undefined;
1898
- fillMode?: "forwards" | "backwards" | "both" | "none" | undefined;
1924
+ fillMode?: "none" | "forwards" | "backwards" | "both" | undefined;
1899
1925
  direction?: "reverse" | "normal" | "alternate" | "alternate-reverse" | undefined;
1900
1926
  }) | ({
1901
1927
  type: "scroll";
@@ -2010,14 +2036,16 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
2010
2036
  frameRate?: number | undefined;
2011
2037
  duration?: number | undefined;
2012
2038
  trigger?: ({} & {
2013
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
2014
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
2015
- finishAction?: "reset" | "hold" | undefined;
2016
- scrollIntoViewThreshold?: number | undefined;
2039
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
2040
+ offScreen?: "continue" | "pause" | "reset" | undefined;
2041
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
2042
+ finish?: "reset" | "hold" | undefined;
2043
+ visibilityThreshold?: number | undefined;
2044
+ visibilityDebounce?: number | undefined;
2017
2045
  }) | undefined;
2018
2046
  delay?: number | undefined;
2019
2047
  iterations?: number | "infinite" | undefined;
2020
- fillMode?: "forwards" | "backwards" | "both" | "none" | undefined;
2048
+ fillMode?: "none" | "forwards" | "backwards" | "both" | undefined;
2021
2049
  direction?: "reverse" | "normal" | "alternate" | "alternate-reverse" | undefined;
2022
2050
  }) | ({
2023
2051
  type: "scroll";
@@ -8088,14 +8116,16 @@ declare const PxSvgNodeRootSchema: PxSchema<{} & {
8088
8116
  frameRate?: number | undefined;
8089
8117
  duration?: number | undefined;
8090
8118
  trigger?: ({} & {
8091
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
8092
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
8093
- finishAction?: "reset" | "hold" | undefined;
8094
- scrollIntoViewThreshold?: number | undefined;
8119
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
8120
+ offScreen?: "continue" | "pause" | "reset" | undefined;
8121
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
8122
+ finish?: "reset" | "hold" | undefined;
8123
+ visibilityThreshold?: number | undefined;
8124
+ visibilityDebounce?: number | undefined;
8095
8125
  }) | undefined;
8096
8126
  delay?: number | undefined;
8097
8127
  iterations?: number | "infinite" | undefined;
8098
- fillMode?: "forwards" | "backwards" | "both" | "none" | undefined;
8128
+ fillMode?: "none" | "forwards" | "backwards" | "both" | undefined;
8099
8129
  direction?: "reverse" | "normal" | "alternate" | "alternate-reverse" | undefined;
8100
8130
  }) | ({
8101
8131
  type: "scroll";
@@ -8215,14 +8245,16 @@ declare const PxSvgNodeRootSchema: PxSchema<{} & {
8215
8245
  frameRate?: number | undefined;
8216
8246
  duration?: number | undefined;
8217
8247
  trigger?: ({} & {
8218
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
8219
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
8220
- finishAction?: "reset" | "hold" | undefined;
8221
- scrollIntoViewThreshold?: number | undefined;
8248
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
8249
+ offScreen?: "continue" | "pause" | "reset" | undefined;
8250
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
8251
+ finish?: "reset" | "hold" | undefined;
8252
+ visibilityThreshold?: number | undefined;
8253
+ visibilityDebounce?: number | undefined;
8222
8254
  }) | undefined;
8223
8255
  delay?: number | undefined;
8224
8256
  iterations?: number | "infinite" | undefined;
8225
- fillMode?: "forwards" | "backwards" | "both" | "none" | undefined;
8257
+ fillMode?: "none" | "forwards" | "backwards" | "both" | undefined;
8226
8258
  direction?: "reverse" | "normal" | "alternate" | "alternate-reverse" | undefined;
8227
8259
  }) | ({
8228
8260
  type: "scroll";
@@ -8368,14 +8400,16 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
8368
8400
  frameRate?: number | undefined;
8369
8401
  duration?: number | undefined;
8370
8402
  trigger?: ({} & {
8371
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
8372
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
8373
- finishAction?: "reset" | "hold" | undefined;
8374
- scrollIntoViewThreshold?: number | undefined;
8403
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
8404
+ offScreen?: "continue" | "pause" | "reset" | undefined;
8405
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
8406
+ finish?: "reset" | "hold" | undefined;
8407
+ visibilityThreshold?: number | undefined;
8408
+ visibilityDebounce?: number | undefined;
8375
8409
  }) | undefined;
8376
8410
  delay?: number | undefined;
8377
8411
  iterations?: number | "infinite" | undefined;
8378
- fillMode?: "forwards" | "backwards" | "both" | "none" | undefined;
8412
+ fillMode?: "none" | "forwards" | "backwards" | "both" | undefined;
8379
8413
  direction?: "reverse" | "normal" | "alternate" | "alternate-reverse" | undefined;
8380
8414
  }) | ({
8381
8415
  type: "scroll";
@@ -9582,14 +9616,16 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
9582
9616
  frameRate?: number | undefined;
9583
9617
  duration?: number | undefined;
9584
9618
  trigger?: ({} & {
9585
- startOn?: "load" | "mouseOver" | "click" | "scrollIntoView" | "programmatic" | undefined;
9586
- outAction?: "reverse" | "continue" | "pause" | "reset" | undefined;
9587
- finishAction?: "reset" | "hold" | undefined;
9588
- scrollIntoViewThreshold?: number | undefined;
9619
+ start?: "none" | "mouseOver" | "load" | "click" | undefined;
9620
+ offScreen?: "continue" | "pause" | "reset" | undefined;
9621
+ mouseOut?: "reverse" | "continue" | "pause" | "reset" | undefined;
9622
+ finish?: "reset" | "hold" | undefined;
9623
+ visibilityThreshold?: number | undefined;
9624
+ visibilityDebounce?: number | undefined;
9589
9625
  }) | undefined;
9590
9626
  delay?: number | undefined;
9591
9627
  iterations?: number | "infinite" | undefined;
9592
- fillMode?: "forwards" | "backwards" | "both" | "none" | undefined;
9628
+ fillMode?: "none" | "forwards" | "backwards" | "both" | undefined;
9593
9629
  direction?: "reverse" | "normal" | "alternate" | "alternate-reverse" | undefined;
9594
9630
  }) | ({
9595
9631
  type: "scroll";
@@ -11025,27 +11061,6 @@ declare const PX_LOOP_JUMP_SHIFT_MS = 1;
11025
11061
  * @internal
11026
11062
  */
11027
11063
  declare function interpolateValue(propName: string, a: any, b: any, t: number): any;
11028
- /**
11029
- * TRANSFORM PRECEDENCE (review §0.4/§1.6) — CSS's own composition rule, applied at READ:
11030
- * a static `transform` on the element composes UNDER the animated transform, instead of
11031
- * being silently clobbered by it. Implemented as a keyframe-value MERGE during
11032
- * normalization, so both engines (and every consumer downstream) see complete parts:
11033
- *
11034
- * 1. `animate.transform` with PARTIAL parts records — every keyframe value (and the
11035
- * base `value`) inherits the static parts it does not set:
11036
- * static `{rotate: 45}` + kf `{translate: [80, 0]}` → kf `{rotate: 45, translate: [80, 0]}`.
11037
- * 2. ONE individual channel (`translate` / `rotate` / `scale` / `skew`) and no
11038
- * `transform` channel — the channel is REWRITTEN as a unified `transform` channel
11039
- * whose values carry the static parts: the rect stays rotated 45° AND slides.
11040
- *
11041
- * The static transform may be a parts record or an attribute string (parsed by the
11042
- * conservative {@link parseTransformParts} — unparseable strings skip the merge).
11043
- * NOT merged (documented limitations): several individual channels animated at once
11044
- * (they still last-write-wins against each other), and an individual channel next to an
11045
- * animated `transform` (the `transform` channel wins, as before).
11046
- * @internal
11047
- */
11048
- declare function mergeStaticTransformIntoAnimDef(animDef: PxAnimationDefinition, staticTransform: unknown): PxAnimationDefinition;
11049
11064
  /**
11050
11065
  * Normalizes a PxAnimatedSvgDocument to a PxAnimatorConfig for the animation engines.
11051
11066
  * This is the main entry point for converting the new API format to internal format.
@@ -11100,6 +11115,27 @@ interface PxMaterializeAllOptions {
11100
11115
  }
11101
11116
  /** @public @advanced */
11102
11117
  declare function materializeAllInTree(doc: PxAnimatedSvgDocument, engine: PxTimelineEngine, options?: PxMaterializeAllOptions): PxAnimatedSvgDocument;
11118
+ /**
11119
+ * The document exactly as the web player RENDERS it: materialized for the engine the document
11120
+ * resolves to, then with fresh ids.
11121
+ *
11122
+ * For adapters that build the DOM themselves (React, Vue). They must render THIS rather than
11123
+ * the raw document — `effects` only become the `<radialGradient>`/`<mask>`/wrapper nodes the
11124
+ * shapes point at during materialization. Rendering the raw document drops all of it, and a
11125
+ * document whose paint comes from `effects` alone renders as an empty canvas.
11126
+ *
11127
+ * - **Order matters.** Ids are regenerated AFTER materializing, because materialization mints
11128
+ * its def ids from a counter that starts at zero on every call — two instances on one page
11129
+ * would otherwise share them, and `url(#…)` resolves document-wide to the first match.
11130
+ * - **Safe to hand on to `createAnimator`.** Materialization consumes `node.effects` and
11131
+ * flattens loops, so the player's own pass over the result changes nothing, and the ids it
11132
+ * binds to are the ids that were rendered.
11133
+ *
11134
+ * The web player's container path does the same two steps inline (it only regenerates ids
11135
+ * when it owns the render); this is that sequence, named, so the adapters cannot drift from it.
11136
+ * @internal
11137
+ */
11138
+ declare function prepareDocumentForRender(doc: PxAnimatedSvgDocument): PxAnimatedSvgDocument;
11103
11139
 
11104
11140
  /**
11105
11141
  * A document's schema findings. The pre-2026-09 FLAT animator spelling is NOT a category of its
@@ -11123,4 +11159,4 @@ declare function diagnoseDocument(doc: unknown): PxDocumentDiagnosis;
11123
11159
  */
11124
11160
  declare function reportDocumentDiagnostics(doc: unknown, where: string): void;
11125
11161
 
11126
- export { PxLoopRepeatAt as $, type PxDefinitions as A, PxDefinitionsSchema as B, type PxDiagnostic as C, PxDiagnosticCode as D, PxDiagnosticKind as E, type PxDiagnostics as F, type PxDiagnosticsConfig as G, type PxEffects as H, PxEffectsSchema as I, type PxElementAnimation as J, PxElementAnimationSchema as K, PxFillGradientEffectSchema as L, PxFillMode as M, PxFinishAction as N, type PxGlyph as O, type PxAnimatedSvgDocument as P, type PxGlyphFont as Q, PxGradientSpreadMethod as R, PxGradientStopSchema as S, PxGradientType as T, type PxInfer as U, type PxKeyframe as V, PxKeyframeSchema as W, PxKeyframeValueSchema as X, PxLengthAdjust as Y, type PxLoop as Z, PxLoopDirection as _, type PxEngineCallbacks as a, formatWireVersion as a$, PxLoopSchema as a0, PxMaskType as a1, PxMaskedByEffectSchema as a2, PxNodeBaseSchema as a3, PxNodeSchema as a4, PxOutAction as a5, PxPathOverflow as a6, PxPinAlign as a7, type PxPlaybackApi as a8, PxPlaybackDirection as a9, PxTimelineEngineSetting as aA, PxTimelineSchema as aB, PxTransformByEffectSchema as aC, type PxTransformParts as aD, PxTransformPartsSchema as aE, type PxTransformValue as aF, PxTransformValueSchema as aG, type PxTrigger as aH, PxTriggerSchema as aI, PxUnits as aJ, type PxValidationContext as aK, type PxVec2 as aL, type PxWireConversionOptions as aM, type PxWireConversionResult as aN, PxWireStepKind as aO, type PxWireVersion as aP, PxWireVersionRelation as aQ, type PxWireVersionStep as aR, applyWireSteps as aS, calcAnimationValues as aT, compareWireVersion as aU, controlModeTakesOverTrigger as aV, convertWireDocument as aW, describeSchema as aX, diagnoseDocument as aY, downgradeWireDocument as aZ, flattenAnimatorTimeline as a_, type PxPropertyAnimation as aa, PxPropertyAnimationSchema as ab, type PxRemoveIndex as ac, PxRepeaterEffectSchema as ad, PxRetimeEffectSchema as ae, type PxSchema as af, type PxSchemaDesc as ag, type PxScroll as ah, PxScrollAxis as ai, PxScrollKind as aj, PxScrollPhase as ak, type PxScrollRangePoint as al, PxScrollRangePointSchema as am, PxScrollRangeSchema as an, PxScrollSchema as ao, PxScrollSource as ap, PxStrokeTrimEffectSchema as aq, PxStrokeTrimSubPaths as ar, type PxSvgNode as as, PxSvgNodeRootSchema as at, PxTextEffectSchema as au, PxTextPathEffectSchema as av, PxTextPathMethod as aw, PxTextPathSpacing as ax, type PxTimeline as ay, PxTimelineEngine as az, type PxAnimatorApi as b, generateNewIds as b0, getAnimatorConfig as b1, getBindings as b2, getChildren as b3, getDefinitions as b4, isNativeForced as b5, isPxDocument as b6, isValidPxDocument as b7, materializeAllInTree as b8, mayUseNativeScrollTimeline as b9, deepClone as bA, generateUniqueId as bB, interpolateValue as bC, keyframeEasing as bD, keyframeValue as bE, materializeMotionPathInPropAnim as bF, mergeStaticTransformIntoAnimDef as bG, reportDocumentDiagnostics as bH, sanitizeAttributeValue as bI, nestAnimatorTimeline as ba, normalizeBindings as bb, parseWireVersion as bc, px as bd, readWireVersion as be, resolveControlMode as bf, resolveTimelineEngine as bg, resolveTrigger as bh, schemaKeys as bi, toDomProps as bj, validateDocument as bk, validateNodeEffects as bl, wireVersionAdvice as bm, type PxAnimatable as bn, PX_ANIM_ATTR_NAME as bo, PX_ANIM_SRC_ATTR_NAME as bp, PX_CSS_ONLY_STYLE_PROPS as bq, PX_DISALLOWED_SVG_TAGS_LOWER as br, PX_LOOP_JUMP_SHIFT_MS as bs, PX_TEXT_CONTENT_ATTR as bt, PX_UNKNOWN_KEY_ERROR as bu, type PxAnyKeyframe as bv, type PxMaterializeAllOptions as bw, type PxNormalizedKeyframe as bx, type PxNormalizedPropertyAnimation as by, createDiagnostics as bz, type PxAnimatorConfig as c, PxStartOn as d, type PxNode as e, PX_TRANSFORM_PART_KEYS as f, PX_TRIGGER_DEFAULTS as g, PX_WIRE_BASELINE_VERSION as h, PX_WIRE_STEPS as i, PX_WIRE_VERSION as j, PX_WIRE_VERSION_KEY as k, PxAlongPathMode as l, PxAnimatedSvgDocumentSchema as m, type PxAnimationDefinition as n, type PxAnimatorCallbacks as o, PxAnimatorConfigSchema as p, type PxAnimatorHandle as q, PxAttrValueSchema as r, type PxBezierPath as s, PxBezierPathSchema as t, type PxBinding as u, PxClipPathEffectSchema as v, PxCloneEffectSchema as w, PxCloneWithout as x, PxControlMode as y, type PxControlProps as z };
11162
+ export { PxLoopRepeatAt as $, type PxDefinitions as A, PxDefinitionsSchema as B, type PxDiagnostic as C, PxDiagnosticCode as D, PxDiagnosticKind as E, type PxDiagnostics as F, type PxDiagnosticsConfig as G, type PxEffects as H, PxEffectsSchema as I, type PxElementAnimation as J, PxElementAnimationSchema as K, PxFillGradientEffectSchema as L, PxFillMode as M, PxFinishAction as N, type PxGlyph as O, type PxAnimatedSvgDocument as P, type PxGlyphFont as Q, PxGradientSpreadMethod as R, PxGradientStopSchema as S, PxGradientType as T, type PxInfer as U, type PxKeyframe as V, PxKeyframeSchema as W, PxKeyframeValueSchema as X, PxLengthAdjust as Y, type PxLoop as Z, PxLoopDirection as _, type PxEngineCallbacks as a, flattenAnimatorTimeline as a$, PxLoopSchema as a0, PxMaskType as a1, PxMaskedByEffectSchema as a2, PxMouseOutAction as a3, PxNodeBaseSchema as a4, PxNodeSchema as a5, PxOffScreenAction as a6, PxPathOverflow as a7, PxPinAlign as a8, type PxPlaybackApi as a9, PxTimelineEngine as aA, PxTimelineEngineSetting as aB, PxTimelineSchema as aC, PxTransformByEffectSchema as aD, type PxTransformParts as aE, PxTransformPartsSchema as aF, type PxTransformValue as aG, PxTransformValueSchema as aH, type PxTrigger as aI, PxTriggerSchema as aJ, PxUnits as aK, type PxValidationContext as aL, type PxVec2 as aM, type PxWireConversionOptions as aN, type PxWireConversionResult as aO, PxWireStepKind as aP, type PxWireVersion as aQ, PxWireVersionRelation as aR, type PxWireVersionStep as aS, applyWireSteps as aT, calcAnimationValues as aU, compareWireVersion as aV, controlModeTakesOverTrigger as aW, convertWireDocument as aX, describeSchema as aY, diagnoseDocument as aZ, downgradeWireDocument as a_, PxPlaybackDirection as aa, type PxPropertyAnimation as ab, PxPropertyAnimationSchema as ac, type PxRemoveIndex as ad, PxRepeaterEffectSchema as ae, PxRetimeEffectSchema as af, type PxSchema as ag, type PxSchemaDesc as ah, type PxScroll as ai, PxScrollAxis as aj, PxScrollKind as ak, PxScrollPhase as al, type PxScrollRangePoint as am, PxScrollRangePointSchema as an, PxScrollRangeSchema as ao, PxScrollSchema as ap, PxScrollSource as aq, PxStrokeTrimEffectSchema as ar, PxStrokeTrimSubPaths as as, type PxSvgNode as at, PxSvgNodeRootSchema as au, PxTextEffectSchema as av, PxTextPathEffectSchema as aw, PxTextPathMethod as ax, PxTextPathSpacing as ay, type PxTimeline as az, type PxAnimatorApi as b, formatWireVersion as b0, generateNewIds as b1, getAnimatorConfig as b2, getBindings as b3, getChildren as b4, getDefinitions as b5, isNativeForced as b6, isPxDocument as b7, isValidPxDocument as b8, materializeAllInTree as b9, createDiagnostics as bA, deepClone as bB, generateUniqueId as bC, interpolateValue as bD, keyframeEasing as bE, keyframeValue as bF, materializeMotionPathInPropAnim as bG, prepareDocumentForRender as bH, reportDocumentDiagnostics as bI, sanitizeAttributeValue as bJ, mayUseNativeScrollTimeline as ba, nestAnimatorTimeline as bb, normalizeBindings as bc, parseWireVersion as bd, px as be, readWireVersion as bf, resolveControlMode as bg, resolveTimelineEngine as bh, resolveTrigger as bi, schemaKeys as bj, toDomProps as bk, validateDocument as bl, validateNodeEffects as bm, wireVersionAdvice as bn, type PxAnimatable as bo, PX_ANIM_ATTR_NAME as bp, PX_ANIM_SRC_ATTR_NAME as bq, PX_CSS_ONLY_STYLE_PROPS as br, PX_DISALLOWED_SVG_TAGS_LOWER as bs, PX_LOOP_JUMP_SHIFT_MS as bt, PX_TEXT_CONTENT_ATTR as bu, PX_UNKNOWN_KEY_ERROR as bv, type PxAnyKeyframe as bw, type PxMaterializeAllOptions as bx, type PxNormalizedKeyframe as by, type PxNormalizedPropertyAnimation as bz, type PxAnimatorConfig as c, PxTriggerStart as d, type PxNode as e, PX_TRANSFORM_PART_KEYS as f, PX_TRIGGER_DEFAULTS as g, PX_WIRE_BASELINE_VERSION as h, PX_WIRE_STEPS as i, PX_WIRE_VERSION as j, PX_WIRE_VERSION_KEY as k, PxAlongPathMode as l, PxAnimatedSvgDocumentSchema as m, type PxAnimationDefinition as n, type PxAnimatorCallbacks as o, PxAnimatorConfigSchema as p, type PxAnimatorHandle as q, PxAttrValueSchema as r, type PxBezierPath as s, PxBezierPathSchema as t, type PxBinding as u, PxClipPathEffectSchema as v, PxCloneEffectSchema as w, PxCloneWithout as x, PxControlMode as y, type PxControlProps as z };