@pixodesk/svg-animator-web 1.0.35 → 1.0.40

package/dist/index.d.cts

@@ -1,92 +1,22 @@
-import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxAnimatorConfigPatch, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
-export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterialiseAllOptions, MotionPathMaterialisationOptions, MotionPathSample, OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, PathPoint, PathSampler, PlaybackDirection, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigMergeResult, PxAnimatorConfigPatch, PxAnimatorConfigSchema, PxAnimatorConfigShortcuts, PxAnyKeyframe, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCloneWithout, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopDirection, PxLoopRepeatAt, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxNormalisedKeyframe, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxStrokeTrimSubPaths, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTimelineEngine, PxTimelineEngineExtra, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyAnimatorConfig, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, foldAnimatorConfigShortcuts, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, mergeAnimatorConfig, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateDocument, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
+import { P as PxAnimatorAPI } from './internal-BmFv1B6H.cjs';
+export { a as PX_ANIMATOR_DOC_KEY, b as PxAnimatorOptions, c as PxBasicAnimatorAPI, d as PxInternalAnimatorOptions, e as PxTagAnimatorOptions, f as createAnimator, l as loadTagAnimators } from './internal-BmFv1B6H.cjs';
+import { PxAnimatorCallbacks, PxAnimatedSvgDocument, PxTrigger, PxDiagnostics, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
+export { PxAnimatedSvgDocument, PxAnimatorCallbacks, PxAnimatorConfig, PxAnimatorConfigSchema, PxBinding, PxDefs, PxDefsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxEngineCallbacks, PxFillMode, PxInfer, PxNode, PxNodeBase, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverrideProps, PxSchema, PxScrollSchema, PxStartOn, PxSvgNode, PxSvgNodeExtra, PxTimelineEngineExtra, PxTimelinePatch, PxTrigger, PxTriggerSchema, PxValidationContext, createBasicFrameLoopAnimator, generateNewIds, getNormalizedProps, px, validateDocument } from '@pixodesk/svg-animator-core';
 
 /**
- * DOM specialisations of the platform-neutral animator API types.
- * `getRootElement()` returns a DOM `Element` on the web — these aliases keep
- * the historical (pre-core-extraction) signatures for web consumers.
+ * Options accepted by the pre-rendered entry points — a subset of `PxAnimatorOptions`: the
+ * document and the callbacks INLINE under the same names every surface uses (review §9). No
+ * `adapter`: a pre-rendered SVG is by definition already in the DOM (review §25.14).
+ * @public
  */
-type PxBasicAnimatorAPI = PxBasicAnimatorAPI$1<Element>;
-type PxAnimatorAPI = PxAnimatorAPI$1<Element>;
-
-/**
- * Wire keys shared by every entry point.
- *
- * These live here rather than in `PxAnimator.ts` on purpose: that module ends with a
- * top-level `if (typeof window !== 'undefined')` block that publishes `createAnimator` /
- * `loadTagAnimators` as globals. A module-level side effect cannot be tree-shaken, so
- * importing ANY symbol from `PxAnimator.ts` pulls the entire full player in with it —
- * which silently made the pre-rendered builds the same size as the full one until this
- * constant was moved out. See PRERENDERED-PLAYER-BUILDS.md.
- */
-/** Key under which `createAnimator` options carry an inline animation document. */
-declare const PX_ANIMATOR_DATA_KEY = "data";
-
-/**
- * Creates an animator instance from an AnimatedSvgDocument.
- *
- * This function serves as the main entry point for the animation library. It automatically
- * chooses the best animation engine available ('waapi' or 'frames') or can be
- * forced to use a specific one.
- *
- * @param doc The animated SVG document.
- * @param callbacks Optional object with callback functions for animation lifecycle events (play, pause, finish, etc.).
- * @param containerElement Optional selector or element to render the SVG into.
- * @returns An PxAnimatorAPI instance to programmatically control the animation.
- */
-declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element, config?: PxAnimatorConfigPatch, resetDocDefaults?: boolean): PxAnimatorAPI;
-
-interface PxAnimatorOptions {
-    /** URL to fetch the animation document from. Provide either this or `data`, not both. */
-    src?: string;
-    /** Inline animation document object. Provide either this or `src`, not both. */
-    data?: PxAnimatedSvgDocument;
-    /** Platform adapter for frame-loop rendering. */
-    adapter?: PxPlatformAdapter;
-    /** Callback functions for animation lifecycle events. */
-    callbacks?: PxAnimatorCallbacksConfig;
-    /** CSS selector or element to render the SVG into. */
-    container?: string | Element;
+interface PxPrerenderedOptions extends PxAnimatorCallbacks {
     /**
-     * Per-instance override of the document's `animator` config — the same shape as
-     * `animator` in SCHEMA.md, deep-merged over what the document says, so one file can play
-     * twice on a page with different timing. `null` at any slot DELETES that key, which is
-     * how you restore a default that absence means.
-     *
-     * Also accepts a JSON STRING of the same object. Strings are immune to property mangling,
-     * so that form survives a build that renames object keys (see docs/library/minification.md).
+     * The animation document. For a pre-rendered SVG this carries `animator.definitions`
+     * and `animator.bindings` only — no `children`, because the elements are already
+     * in the DOM.
      */
-    config?: PxAnimatorConfigPatch | string;
-    /**
-     * Ignore the document's own playback settings and start from the player's defaults, with
-     * `config` applied on top. The lookup tables (`definitions`, `animateById`) are kept
-     * either way — resetting those would leave the animation with nothing to animate.
-     */
-    resetDocDefaults?: boolean;
-    /** Shortcut for `config.timeline.duration` (ms). Wins over the same key inside `config`. */
-    duration?: number;
-    /** Shortcut for `config.timeline.delay` (ms). */
-    delay?: number;
-    /** Shortcut for `config.timeline.iterations`. */
-    iterations?: number | 'infinite';
-    /** Shortcut for `config.timeline.trigger.startOn`. Typed from the WIRE, so it includes
-     *  `'programmatic'` — the value that says "nothing starts this but a `play()` call". */
-    startOn?: PxTrigger['startOn'];
+    doc: PxAnimatedSvgDocument;
 }
-/**
- * Creates an animator instance to control SVG animations.
- *
- * @param options.src URL to fetch the animation document from.
- * @param options.data Inline animation document object.
- * @param options.container CSS selector or element to render the SVG into.
- * @returns A PxAnimatorAPI instance to programmatically control the animation.
- */
-declare function createAnimator(options: PxAnimatorOptions): PxAnimatorAPI;
-/**
- * Scan and load for tags, e.g.
- *  <div data-px-animation-src="animation.json"></div>
- */
-declare function loadTagAnimators(): void;
 
 /**
  * Sets up event-based triggers for an animation.
@@ -96,7 +26,7 @@ declare function loadTagAnimators(): void;
  * or visibility changes.
  *
  * ### Trigger Options (startOn):
- * - 'load': Starts after the page loads.
+ * - 'load' (default): Starts after the page loads.
  * - 'mouseOver': Starts on mouse enter.
  * - 'click': Toggles play/end action on click.
  * - 'scrollIntoView': Starts when the element scrolls into the viewport.
@@ -104,51 +34,26 @@ declare function loadTagAnimators(): void;
  *
  * ### End Action Options (outAction):
  * Defines behavior when the trigger condition ends (e.g., mouse leave).
- * - 'continue': Animation continues playing.
+ * - 'continue' (default): Animation continues playing.
  * - 'pause': Pauses the animation.
  * - 'reset': Cancels the animation, resetting it to the start.
  * - 'reverse': Reverses the animation playback.
  *
  * @param {!PxAnimatorAPI} api The animator API instance to control.
- * @param {!PxTrigger} config The trigger configuration object.
- * @returns {!PxAnimatorAPI} The same animator API instance, for chaining.
+ * @param {!PxTrigger} config The trigger configuration object. Only `startOn`, `outAction` and
+ *   `scrollIntoViewThreshold` are read here; `finishAction` belongs to the PLAYER (what happens
+ *   after a natural end), not to the trigger wiring.
+ * @returns A disposer that detaches every listener and observer this call attached (review §14).
+ *   `createAnimator` ties it to `destroy()`. Call it yourself before re-arming an element you
+ *   wired by hand — otherwise the old listeners stay live next to the new ones.
+ * @public
  */
-declare function setupAnimationTriggers(api: PxAnimatorAPI, config: PxTrigger): PxAnimatorAPI;
+declare function setupAnimationTriggers(api: PxAnimatorAPI, config: PxTrigger, diag?: PxDiagnostics): () => void;
 
 /**
  * Renders a PxNode tree to DOM elements.
+ * @public @advanced
  */
-declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
-
-/**
- * Creates an animator instance that uses a requestAnimationFrame loop for animations.
- * This is the browser DOM-specific version.
- *
- * @param {PxAnimatorCallbacksConfig=} callbacks Optional lifecycle callbacks.
- * @param {Element=} rootElement Optional pre-rendered root element.
- * @returns {PxAnimatorAPI} A PxAnimatorAPI instance.
- */
-declare function createFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null): PxAnimatorAPI;
-
-/**
- * Creates an animator instance that uses the native Web Animations API.
- *
- * This is the preferred, more performant animator. It will return null if the
- * animation configuration contains properties not supported by the browser's
- * Web Animations API implementation, unless forceEvenIfHasUnsupportedAttrs is true.
- *
- * @param callbacks Optional lifecycle callbacks.
- * @param rootElement Root element.
- * @param forceEvenIfHasUnsupportedAttrs If true, an animator will be created even if some CSS properties are not supported.
- * @returns An PxAnimatorAPI instance, or null if unsupported features are used and not forced.
- */
-/** Native scroll-timeline payload (`timeline.engine: 'native'` / `auto`; see PxScrollDriver.createNativeScrollTimeline): the
- *  browser-native timeline every Animation attaches to, plus optional range offsets. */
-interface PxWebApiScrollTimeline {
-    timeline: AnimationTimeline;
-    rangeStart?: Record<string, unknown>;
-    rangeEnd?: Record<string, unknown>;
-}
-declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean, scrollTimeline?: PxWebApiScrollTimeline): PxAnimatorAPI | null;
+declare function renderNode(node: PxNode, defs?: PxDefs, diag?: PxDiagnostics): Element | null;
 
-export { PX_ANIMATOR_DATA_KEY, type PxAnimatorAPI, type PxAnimatorOptions, type PxBasicAnimatorAPI, createAnimator, createAnimatorImpl, createFrameLoopAnimator, createWebApiAnimator, loadTagAnimators, renderNode, setupAnimationTriggers };
+export { PxAnimatorAPI, type PxPrerenderedOptions, renderNode, setupAnimationTriggers };

package/dist/index.d.ts

@@ -1,92 +1,22 @@
-import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxAnimatorConfigPatch, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
-export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterialiseAllOptions, MotionPathMaterialisationOptions, MotionPathSample, OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, PathPoint, PathSampler, PlaybackDirection, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigMergeResult, PxAnimatorConfigPatch, PxAnimatorConfigSchema, PxAnimatorConfigShortcuts, PxAnyKeyframe, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCloneWithout, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopDirection, PxLoopRepeatAt, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxNormalisedKeyframe, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxStrokeTrimSubPaths, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTimelineEngine, PxTimelineEngineExtra, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyAnimatorConfig, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, foldAnimatorConfigShortcuts, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, mergeAnimatorConfig, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateDocument, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
+import { P as PxAnimatorAPI } from './internal-BmFv1B6H.js';
+export { a as PX_ANIMATOR_DOC_KEY, b as PxAnimatorOptions, c as PxBasicAnimatorAPI, d as PxInternalAnimatorOptions, e as PxTagAnimatorOptions, f as createAnimator, l as loadTagAnimators } from './internal-BmFv1B6H.js';
+import { PxAnimatorCallbacks, PxAnimatedSvgDocument, PxTrigger, PxDiagnostics, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
+export { PxAnimatedSvgDocument, PxAnimatorCallbacks, PxAnimatorConfig, PxAnimatorConfigSchema, PxBinding, PxDefs, PxDefsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxEngineCallbacks, PxFillMode, PxInfer, PxNode, PxNodeBase, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverrideProps, PxSchema, PxScrollSchema, PxStartOn, PxSvgNode, PxSvgNodeExtra, PxTimelineEngineExtra, PxTimelinePatch, PxTrigger, PxTriggerSchema, PxValidationContext, createBasicFrameLoopAnimator, generateNewIds, getNormalizedProps, px, validateDocument } from '@pixodesk/svg-animator-core';
 
 /**
- * DOM specialisations of the platform-neutral animator API types.
- * `getRootElement()` returns a DOM `Element` on the web — these aliases keep
- * the historical (pre-core-extraction) signatures for web consumers.
+ * Options accepted by the pre-rendered entry points — a subset of `PxAnimatorOptions`: the
+ * document and the callbacks INLINE under the same names every surface uses (review §9). No
+ * `adapter`: a pre-rendered SVG is by definition already in the DOM (review §25.14).
+ * @public
  */
-type PxBasicAnimatorAPI = PxBasicAnimatorAPI$1<Element>;
-type PxAnimatorAPI = PxAnimatorAPI$1<Element>;
-
-/**
- * Wire keys shared by every entry point.
- *
- * These live here rather than in `PxAnimator.ts` on purpose: that module ends with a
- * top-level `if (typeof window !== 'undefined')` block that publishes `createAnimator` /
- * `loadTagAnimators` as globals. A module-level side effect cannot be tree-shaken, so
- * importing ANY symbol from `PxAnimator.ts` pulls the entire full player in with it —
- * which silently made the pre-rendered builds the same size as the full one until this
- * constant was moved out. See PRERENDERED-PLAYER-BUILDS.md.
- */
-/** Key under which `createAnimator` options carry an inline animation document. */
-declare const PX_ANIMATOR_DATA_KEY = "data";
-
-/**
- * Creates an animator instance from an AnimatedSvgDocument.
- *
- * This function serves as the main entry point for the animation library. It automatically
- * chooses the best animation engine available ('waapi' or 'frames') or can be
- * forced to use a specific one.
- *
- * @param doc The animated SVG document.
- * @param callbacks Optional object with callback functions for animation lifecycle events (play, pause, finish, etc.).
- * @param containerElement Optional selector or element to render the SVG into.
- * @returns An PxAnimatorAPI instance to programmatically control the animation.
- */
-declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element, config?: PxAnimatorConfigPatch, resetDocDefaults?: boolean): PxAnimatorAPI;
-
-interface PxAnimatorOptions {
-    /** URL to fetch the animation document from. Provide either this or `data`, not both. */
-    src?: string;
-    /** Inline animation document object. Provide either this or `src`, not both. */
-    data?: PxAnimatedSvgDocument;
-    /** Platform adapter for frame-loop rendering. */
-    adapter?: PxPlatformAdapter;
-    /** Callback functions for animation lifecycle events. */
-    callbacks?: PxAnimatorCallbacksConfig;
-    /** CSS selector or element to render the SVG into. */
-    container?: string | Element;
+interface PxPrerenderedOptions extends PxAnimatorCallbacks {
     /**
-     * Per-instance override of the document's `animator` config — the same shape as
-     * `animator` in SCHEMA.md, deep-merged over what the document says, so one file can play
-     * twice on a page with different timing. `null` at any slot DELETES that key, which is
-     * how you restore a default that absence means.
-     *
-     * Also accepts a JSON STRING of the same object. Strings are immune to property mangling,
-     * so that form survives a build that renames object keys (see docs/library/minification.md).
+     * The animation document. For a pre-rendered SVG this carries `animator.definitions`
+     * and `animator.bindings` only — no `children`, because the elements are already
+     * in the DOM.
      */
-    config?: PxAnimatorConfigPatch | string;
-    /**
-     * Ignore the document's own playback settings and start from the player's defaults, with
-     * `config` applied on top. The lookup tables (`definitions`, `animateById`) are kept
-     * either way — resetting those would leave the animation with nothing to animate.
-     */
-    resetDocDefaults?: boolean;
-    /** Shortcut for `config.timeline.duration` (ms). Wins over the same key inside `config`. */
-    duration?: number;
-    /** Shortcut for `config.timeline.delay` (ms). */
-    delay?: number;
-    /** Shortcut for `config.timeline.iterations`. */
-    iterations?: number | 'infinite';
-    /** Shortcut for `config.timeline.trigger.startOn`. Typed from the WIRE, so it includes
-     *  `'programmatic'` — the value that says "nothing starts this but a `play()` call". */
-    startOn?: PxTrigger['startOn'];
+    doc: PxAnimatedSvgDocument;
 }
-/**
- * Creates an animator instance to control SVG animations.
- *
- * @param options.src URL to fetch the animation document from.
- * @param options.data Inline animation document object.
- * @param options.container CSS selector or element to render the SVG into.
- * @returns A PxAnimatorAPI instance to programmatically control the animation.
- */
-declare function createAnimator(options: PxAnimatorOptions): PxAnimatorAPI;
-/**
- * Scan and load for tags, e.g.
- *  <div data-px-animation-src="animation.json"></div>
- */
-declare function loadTagAnimators(): void;
 
 /**
  * Sets up event-based triggers for an animation.
@@ -96,7 +26,7 @@ declare function loadTagAnimators(): void;
  * or visibility changes.
  *
  * ### Trigger Options (startOn):
- * - 'load': Starts after the page loads.
+ * - 'load' (default): Starts after the page loads.
  * - 'mouseOver': Starts on mouse enter.
  * - 'click': Toggles play/end action on click.
  * - 'scrollIntoView': Starts when the element scrolls into the viewport.
@@ -104,51 +34,26 @@ declare function loadTagAnimators(): void;
  *
  * ### End Action Options (outAction):
  * Defines behavior when the trigger condition ends (e.g., mouse leave).
- * - 'continue': Animation continues playing.
+ * - 'continue' (default): Animation continues playing.
  * - 'pause': Pauses the animation.
  * - 'reset': Cancels the animation, resetting it to the start.
  * - 'reverse': Reverses the animation playback.
  *
  * @param {!PxAnimatorAPI} api The animator API instance to control.
- * @param {!PxTrigger} config The trigger configuration object.
- * @returns {!PxAnimatorAPI} The same animator API instance, for chaining.
+ * @param {!PxTrigger} config The trigger configuration object. Only `startOn`, `outAction` and
+ *   `scrollIntoViewThreshold` are read here; `finishAction` belongs to the PLAYER (what happens
+ *   after a natural end), not to the trigger wiring.
+ * @returns A disposer that detaches every listener and observer this call attached (review §14).
+ *   `createAnimator` ties it to `destroy()`. Call it yourself before re-arming an element you
+ *   wired by hand — otherwise the old listeners stay live next to the new ones.
+ * @public
  */
-declare function setupAnimationTriggers(api: PxAnimatorAPI, config: PxTrigger): PxAnimatorAPI;
+declare function setupAnimationTriggers(api: PxAnimatorAPI, config: PxTrigger, diag?: PxDiagnostics): () => void;
 
 /**
  * Renders a PxNode tree to DOM elements.
+ * @public @advanced
  */
-declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
-
-/**
- * Creates an animator instance that uses a requestAnimationFrame loop for animations.
- * This is the browser DOM-specific version.
- *
- * @param {PxAnimatorCallbacksConfig=} callbacks Optional lifecycle callbacks.
- * @param {Element=} rootElement Optional pre-rendered root element.
- * @returns {PxAnimatorAPI} A PxAnimatorAPI instance.
- */
-declare function createFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null): PxAnimatorAPI;
-
-/**
- * Creates an animator instance that uses the native Web Animations API.
- *
- * This is the preferred, more performant animator. It will return null if the
- * animation configuration contains properties not supported by the browser's
- * Web Animations API implementation, unless forceEvenIfHasUnsupportedAttrs is true.
- *
- * @param callbacks Optional lifecycle callbacks.
- * @param rootElement Root element.
- * @param forceEvenIfHasUnsupportedAttrs If true, an animator will be created even if some CSS properties are not supported.
- * @returns An PxAnimatorAPI instance, or null if unsupported features are used and not forced.
- */
-/** Native scroll-timeline payload (`timeline.engine: 'native'` / `auto`; see PxScrollDriver.createNativeScrollTimeline): the
- *  browser-native timeline every Animation attaches to, plus optional range offsets. */
-interface PxWebApiScrollTimeline {
-    timeline: AnimationTimeline;
-    rangeStart?: Record<string, unknown>;
-    rangeEnd?: Record<string, unknown>;
-}
-declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean, scrollTimeline?: PxWebApiScrollTimeline): PxAnimatorAPI | null;
+declare function renderNode(node: PxNode, defs?: PxDefs, diag?: PxDiagnostics): Element | null;
 
-export { PX_ANIMATOR_DATA_KEY, type PxAnimatorAPI, type PxAnimatorOptions, type PxBasicAnimatorAPI, createAnimator, createAnimatorImpl, createFrameLoopAnimator, createWebApiAnimator, loadTagAnimators, renderNode, setupAnimationTriggers };
+export { PxAnimatorAPI, type PxPrerenderedOptions, renderNode, setupAnimationTriggers };