@pixodesk/svg-animator-web 1.0.34 → 1.0.39

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
-export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, JsMode, 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, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
+import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxPlaybackOverrideProps, PxComponentCallbacks, PxAnimatedSvgDocument, PxPlatformAdapter, PxTrigger, PxDiagnostics, PxNode, PxDefs, PxAnimatorCallbacksConfig } from '@pixodesk/svg-animator-core';
+export { ApplyResult, BASELINE_PLAYER_VERSION, COLOR_ATTR_NAMES, DEFAULT_DURATION_MS, ExtendPathOpts, ExtendedPath, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterializeOpts, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterializeAllOptions, MotionPathMaterializationOptions, MotionPathSample, PLAYER_WIRE_STEPS, PLAYER_WIRE_VERSION, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_PLAYER_SCHEMA_VERSION, PX_TRANSFORM_PART_KEYS, PX_TRIGGER_DEFAULTS, PathPoint, PathSampler, PlayerConversionResult, PxAlongPathMode, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigMergeResult, PxAnimatorConfigPatch, PxAnimatorConfigSchema, PxAnimatorConfigShortcuts, PxAnimatorHandle, PxAnyKeyframe, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxClipPathEffectSchema, PxCloneEffect, PxCloneEffectSchema, PxCloneWithout, PxComponentCallbacks, PxControlMode, PxControlProps, PxCreateElement, PxDefs, PxDefsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxDocumentDiagnosis, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxFillMode, PxFinishAction, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLengthAdjust, PxLoop, PxLoopDirection, PxLoopRepeatAt, PxLoopSchema, PxMaskType, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxNormalizedKeyframe, PxOutAction, PxPathOverflow, PxPinAlign, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverrideProps, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxResolvedControlMode, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxScrollAxis, PxScrollKind, PxScrollPhase, PxScrollRangePointSchema, PxScrollRangeSchema, PxScrollSchema, PxScrollSource, PxStartOn, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxStrokeTrimSubPaths, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTextPathMethod, PxTextPathSpacing, PxTimelineEngine, PxTimelineEngineExtra, PxTimelinePatch, PxTimelinePinSchema, PxTimelineSchema, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxUnits, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, TRANSFORM_FN_NAMES, Vec2, WIRE_VERSION_KEY, WireConversionConfig, WireDowngradeConfig, WireDowngradeResult, WireStepKind, WireVersion, WireVersionRelation, WireVersionStep, applyAnimatorConfig, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, compareWireVersion, controlModeTakesOverTrigger, convertPlayerDocument, createBasicFrameLoopAnimator, createDiagnostics, createPathSampler, describeSchema, diagnoseDocument, diffInEffect, downgradePlayerDocument, evaluateMotionPathSegment, extendedPathForBrowser, foldTimelineOverride, formatWireVersion, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materializeAllInTree, materializeAnimatedUseInstances, materializeGlyphText, materializeGlyphTextAlongPath, materializeGlyphTextHorizontal, materializeInternalLoopsInPropAnim, materializeInternalLoopsInTree, materializeMotionPathInPropAnim, materializeMotionPathsInTree, mergeAnimatorConfig, getNormalizedBindings as normalizeDocument, parseWireVersion, progressToTimeMs, propAnimIsMotionPath, px, readWireVersion, resolveControlMode, resolveTrigger, schemaKeys, shiftAnimatable, timeToProgress, toRGBA, validateDocument, validateNodeEffects, versionAdvice, visualModelAt } from '@pixodesk/svg-animator-core';
 
 /**
- * DOM specialisations of the platform-neutral animator API types.
+ * DOM specializations 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.
  */
@@ -12,39 +12,36 @@ 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` /
+ * These live here rather than in `PxAnimator.ts` on purpose: that module used to end with a
+ * top-level `if (typeof window !== 'undefined')` block publishing `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 —
+ * importing ANY symbol from `PxAnimator.ts` pulled 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.
+ *
+ * That block is gone (API review §4) and the package now declares `"sideEffects": false`, but
+ * keeping these here costs nothing and removes the trap for good.
  */
-/** 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.
+ * Key under which `createAnimator` options carry the inline animation document. The editor
+ * writes it into every exported SVG+JS — `createAnimator({"doc": …})` — so it is part of the
+ * export format, which is why it is a named constant and not a literal.
  */
-declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element): PxAnimatorAPI;
+declare const PX_ANIMATOR_DOC_KEY = "doc";
 
-interface PxAnimatorOptions {
-    /** URL to fetch the animation document from. Provide either this or `data`, not both. */
+/**
+ * Everything `createAnimator` takes. The playback override (`timeline`, `resetTimeline` and the
+ * four shortcuts) and the callbacks are core's shared shapes — the SAME names, inline, as the
+ * React, Vue and React Native components take (review §9) — so only what is web-specific is
+ * declared here.
+ */
+interface PxAnimatorOptions extends PxPlaybackOverrideProps, PxComponentCallbacks {
+    /** URL to fetch the animation document from. Provide either this or `doc`, not both. */
     src?: string;
-    /** Inline animation document object. Provide either this or `src`, not both. */
-    data?: PxAnimatedSvgDocument;
-    /** Platform adapter for frame-loop rendering. */
+    /** The animation document, inline (see SCHEMA.md). Provide either this or `src`, not both. */
+    doc?: PxAnimatedSvgDocument;
+    /** ○ A custom render target for the frame-loop engine (`PxPlatformAdapter`); omit for the DOM. */
     adapter?: PxPlatformAdapter;
-    /** Callback functions for animation lifecycle events. */
-    callbacks?: PxAnimatorCallbacksConfig;
     /** CSS selector or element to render the SVG into. */
     container?: string | Element;
 }
@@ -52,7 +49,7 @@ interface PxAnimatorOptions {
  * 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.doc The animation document, inline.
  * @param options.container CSS selector or element to render the SVG into.
  * @returns A PxAnimatorAPI instance to programmatically control the animation.
  */
@@ -61,7 +58,36 @@ 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;
+/**
+ * Everything `createAnimator` takes except the three the tag supplies (`src`, `container`) or
+ * forbids (`data`): callbacks, the diagnostics channel, a playback override and its shortcuts.
+ */
+type PxTagAnimatorOptions = Omit<PxAnimatorOptions, 'src' | 'doc' | 'container'>;
+/**
+ * Scan the page for `<div data-px-animation-src="animation.json">` and create one player per
+ * match, rendered into that element and stored on it. Safe to call repeatedly: elements that
+ * already carry a player are skipped.
+ *
+ * `options` applies to EVERY player this call creates (review §15) — the same callbacks, the
+ * same override. Omit it for the zero-config path.
+ */
+declare function loadTagAnimators(options?: PxTagAnimatorOptions): void;
+
+/**
+ * Options accepted by the pre-rendered entry points — a subset of `PxAnimatorOptions`: the
+ * document, an optional adapter, and the callbacks INLINE under the same names every surface
+ * uses (review §9).
+ */
+interface PxPrerenderedOptions extends PxComponentCallbacks {
+    /**
+     * The animation document. For a pre-rendered SVG this carries `animator.definitions`
+     * and `animator.animateById` only — no `children`, because the elements are already
+     * in the DOM.
+     */
+    doc: PxAnimatedSvgDocument;
+    /** ○ A custom render target for the frame-loop engine; omit for the DOM. */
+    adapter?: PxPlatformAdapter;
+}
 
 /**
  * Sets up event-based triggers for an animation.
@@ -71,7 +97,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.
@@ -79,21 +105,25 @@ 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.
  */
-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.
  */
-declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
+declare function renderNode(node: PxNode, defs?: PxDefs, diag?: PxDiagnostics): Element | null;
 
 /**
  * Creates an animator instance that uses a requestAnimationFrame loop for animations.
@@ -117,7 +147,7 @@ declare function createFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter?: P
  * @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.
  */
-/** `driver: 'native'` payload (see PxScrollDriver.createNativeScrollTimeline): the
+/** 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;
@@ -126,4 +156,4 @@ interface PxWebApiScrollTimeline {
 }
 declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean, scrollTimeline?: PxWebApiScrollTimeline): PxAnimatorAPI | null;
 
-export { PX_ANIMATOR_DATA_KEY, type PxAnimatorAPI, type PxAnimatorOptions, type PxBasicAnimatorAPI, createAnimator, createAnimatorImpl, createFrameLoopAnimator, createWebApiAnimator, loadTagAnimators, renderNode, setupAnimationTriggers };
+export { PX_ANIMATOR_DOC_KEY, type PxAnimatorAPI, type PxAnimatorOptions, type PxBasicAnimatorAPI, type PxPrerenderedOptions, type PxTagAnimatorOptions, createAnimator, createFrameLoopAnimator, createWebApiAnimator, loadTagAnimators, renderNode, setupAnimationTriggers };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
-export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, JsMode, 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, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
+import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxPlaybackOverrideProps, PxComponentCallbacks, PxAnimatedSvgDocument, PxPlatformAdapter, PxTrigger, PxDiagnostics, PxNode, PxDefs, PxAnimatorCallbacksConfig } from '@pixodesk/svg-animator-core';
+export { ApplyResult, BASELINE_PLAYER_VERSION, COLOR_ATTR_NAMES, DEFAULT_DURATION_MS, ExtendPathOpts, ExtendedPath, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterializeOpts, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterializeAllOptions, MotionPathMaterializationOptions, MotionPathSample, PLAYER_WIRE_STEPS, PLAYER_WIRE_VERSION, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_PLAYER_SCHEMA_VERSION, PX_TRANSFORM_PART_KEYS, PX_TRIGGER_DEFAULTS, PathPoint, PathSampler, PlayerConversionResult, PxAlongPathMode, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigMergeResult, PxAnimatorConfigPatch, PxAnimatorConfigSchema, PxAnimatorConfigShortcuts, PxAnimatorHandle, PxAnyKeyframe, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxClipPathEffectSchema, PxCloneEffect, PxCloneEffectSchema, PxCloneWithout, PxComponentCallbacks, PxControlMode, PxControlProps, PxCreateElement, PxDefs, PxDefsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxDocumentDiagnosis, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxFillMode, PxFinishAction, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLengthAdjust, PxLoop, PxLoopDirection, PxLoopRepeatAt, PxLoopSchema, PxMaskType, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxNormalizedKeyframe, PxOutAction, PxPathOverflow, PxPinAlign, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverrideProps, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxResolvedControlMode, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxScrollAxis, PxScrollKind, PxScrollPhase, PxScrollRangePointSchema, PxScrollRangeSchema, PxScrollSchema, PxScrollSource, PxStartOn, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxStrokeTrimSubPaths, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTextPathMethod, PxTextPathSpacing, PxTimelineEngine, PxTimelineEngineExtra, PxTimelinePatch, PxTimelinePinSchema, PxTimelineSchema, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxUnits, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, TRANSFORM_FN_NAMES, Vec2, WIRE_VERSION_KEY, WireConversionConfig, WireDowngradeConfig, WireDowngradeResult, WireStepKind, WireVersion, WireVersionRelation, WireVersionStep, applyAnimatorConfig, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, compareWireVersion, controlModeTakesOverTrigger, convertPlayerDocument, createBasicFrameLoopAnimator, createDiagnostics, createPathSampler, describeSchema, diagnoseDocument, diffInEffect, downgradePlayerDocument, evaluateMotionPathSegment, extendedPathForBrowser, foldTimelineOverride, formatWireVersion, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materializeAllInTree, materializeAnimatedUseInstances, materializeGlyphText, materializeGlyphTextAlongPath, materializeGlyphTextHorizontal, materializeInternalLoopsInPropAnim, materializeInternalLoopsInTree, materializeMotionPathInPropAnim, materializeMotionPathsInTree, mergeAnimatorConfig, getNormalizedBindings as normalizeDocument, parseWireVersion, progressToTimeMs, propAnimIsMotionPath, px, readWireVersion, resolveControlMode, resolveTrigger, schemaKeys, shiftAnimatable, timeToProgress, toRGBA, validateDocument, validateNodeEffects, versionAdvice, visualModelAt } from '@pixodesk/svg-animator-core';
 
 /**
- * DOM specialisations of the platform-neutral animator API types.
+ * DOM specializations 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.
  */
@@ -12,39 +12,36 @@ 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` /
+ * These live here rather than in `PxAnimator.ts` on purpose: that module used to end with a
+ * top-level `if (typeof window !== 'undefined')` block publishing `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 —
+ * importing ANY symbol from `PxAnimator.ts` pulled 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.
+ *
+ * That block is gone (API review §4) and the package now declares `"sideEffects": false`, but
+ * keeping these here costs nothing and removes the trap for good.
  */
-/** 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.
+ * Key under which `createAnimator` options carry the inline animation document. The editor
+ * writes it into every exported SVG+JS — `createAnimator({"doc": …})` — so it is part of the
+ * export format, which is why it is a named constant and not a literal.
  */
-declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element): PxAnimatorAPI;
+declare const PX_ANIMATOR_DOC_KEY = "doc";
 
-interface PxAnimatorOptions {
-    /** URL to fetch the animation document from. Provide either this or `data`, not both. */
+/**
+ * Everything `createAnimator` takes. The playback override (`timeline`, `resetTimeline` and the
+ * four shortcuts) and the callbacks are core's shared shapes — the SAME names, inline, as the
+ * React, Vue and React Native components take (review §9) — so only what is web-specific is
+ * declared here.
+ */
+interface PxAnimatorOptions extends PxPlaybackOverrideProps, PxComponentCallbacks {
+    /** URL to fetch the animation document from. Provide either this or `doc`, not both. */
     src?: string;
-    /** Inline animation document object. Provide either this or `src`, not both. */
-    data?: PxAnimatedSvgDocument;
-    /** Platform adapter for frame-loop rendering. */
+    /** The animation document, inline (see SCHEMA.md). Provide either this or `src`, not both. */
+    doc?: PxAnimatedSvgDocument;
+    /** ○ A custom render target for the frame-loop engine (`PxPlatformAdapter`); omit for the DOM. */
     adapter?: PxPlatformAdapter;
-    /** Callback functions for animation lifecycle events. */
-    callbacks?: PxAnimatorCallbacksConfig;
     /** CSS selector or element to render the SVG into. */
     container?: string | Element;
 }
@@ -52,7 +49,7 @@ interface PxAnimatorOptions {
  * 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.doc The animation document, inline.
  * @param options.container CSS selector or element to render the SVG into.
  * @returns A PxAnimatorAPI instance to programmatically control the animation.
  */
@@ -61,7 +58,36 @@ 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;
+/**
+ * Everything `createAnimator` takes except the three the tag supplies (`src`, `container`) or
+ * forbids (`data`): callbacks, the diagnostics channel, a playback override and its shortcuts.
+ */
+type PxTagAnimatorOptions = Omit<PxAnimatorOptions, 'src' | 'doc' | 'container'>;
+/**
+ * Scan the page for `<div data-px-animation-src="animation.json">` and create one player per
+ * match, rendered into that element and stored on it. Safe to call repeatedly: elements that
+ * already carry a player are skipped.
+ *
+ * `options` applies to EVERY player this call creates (review §15) — the same callbacks, the
+ * same override. Omit it for the zero-config path.
+ */
+declare function loadTagAnimators(options?: PxTagAnimatorOptions): void;
+
+/**
+ * Options accepted by the pre-rendered entry points — a subset of `PxAnimatorOptions`: the
+ * document, an optional adapter, and the callbacks INLINE under the same names every surface
+ * uses (review §9).
+ */
+interface PxPrerenderedOptions extends PxComponentCallbacks {
+    /**
+     * The animation document. For a pre-rendered SVG this carries `animator.definitions`
+     * and `animator.animateById` only — no `children`, because the elements are already
+     * in the DOM.
+     */
+    doc: PxAnimatedSvgDocument;
+    /** ○ A custom render target for the frame-loop engine; omit for the DOM. */
+    adapter?: PxPlatformAdapter;
+}
 
 /**
  * Sets up event-based triggers for an animation.
@@ -71,7 +97,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.
@@ -79,21 +105,25 @@ 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.
  */
-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.
  */
-declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
+declare function renderNode(node: PxNode, defs?: PxDefs, diag?: PxDiagnostics): Element | null;
 
 /**
  * Creates an animator instance that uses a requestAnimationFrame loop for animations.
@@ -117,7 +147,7 @@ declare function createFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter?: P
  * @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.
  */
-/** `driver: 'native'` payload (see PxScrollDriver.createNativeScrollTimeline): the
+/** 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;
@@ -126,4 +156,4 @@ interface PxWebApiScrollTimeline {
 }
 declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean, scrollTimeline?: PxWebApiScrollTimeline): PxAnimatorAPI | null;
 
-export { PX_ANIMATOR_DATA_KEY, type PxAnimatorAPI, type PxAnimatorOptions, type PxBasicAnimatorAPI, createAnimator, createAnimatorImpl, createFrameLoopAnimator, createWebApiAnimator, loadTagAnimators, renderNode, setupAnimationTriggers };
+export { PX_ANIMATOR_DOC_KEY, type PxAnimatorAPI, type PxAnimatorOptions, type PxBasicAnimatorAPI, type PxPrerenderedOptions, type PxTagAnimatorOptions, createAnimator, createFrameLoopAnimator, createWebApiAnimator, loadTagAnimators, renderNode, setupAnimationTriggers };