@pixodesk/svg-animator-web 1.0.35 → 1.0.39

package/dist/index.prerendered.umd.js

@@ -50,7 +50,7 @@ var PixodeskAnimator = (() => {
   // src/index.prerendered.ts
   var index_prerendered_exports = {};
   __export(index_prerendered_exports, {
-    PX_ANIMATOR_DATA_KEY: () => PX_ANIMATOR_DATA_KEY,
+    PX_ANIMATOR_DOC_KEY: () => PX_ANIMATOR_DOC_KEY,
     createAnimator: () => createPrerenderedAnimator,
     setupAnimationTriggers: () => setupAnimationTriggers
   });
@@ -285,7 +285,7 @@ var PixodeskAnimator = (() => {
     }
     return void 0;
   }
-  var COLOUR_ATTR_NAMES = /* @__PURE__ */ new Set(["color", "fill", "flood-color", "lighting-color", "stop-color", "stroke"]);
+  var COLOR_ATTR_NAMES = /* @__PURE__ */ new Set(["color", "fill", "flood-color", "lighting-color", "stop-color", "stroke"]);
   var TRANSFORM_FN_NAMES = /* @__PURE__ */ new Set(["translate", "rotate", "scale", "skew"]);
   var PCT_BASED_ATTR_NAMES = /* @__PURE__ */ new Set(["offset-distance", "offsetDistance"]);
   function composeTransformParts(parts, opts) {
@@ -650,6 +650,7 @@ var PixodeskAnimator = (() => {
       return false;
     }
   };
+  var UNION_MEMBER_ERROR_LIMIT = 4;
   var Union = class extends Base {
     constructor(schemas, defaultVal) {
       super();
@@ -668,7 +669,35 @@ var PixodeskAnimator = (() => {
       var _a;
       const probe = ctx && { errors: [], warnings: [], strict: ctx.strict };
       if (this.schemas.some((s) => s.isValid(raw, probe, path ? [...path] : void 0))) return true;
-      ctx == null ? void 0 : ctx.errors.push(pathStr(path != null ? path : []) + ": no union member matched for value " + ((_a = JSON.stringify(raw)) != null ? _a : "").slice(0, 240));
+      if (!ctx) return false;
+      const base = pathStr(path != null ? path : []);
+      ctx.errors.push(base + ": no union member matched for value " + ((_a = JSON.stringify(raw)) != null ? _a : "").slice(0, 240));
+      let best;
+      let bestDepth = -1;
+      const leafExpectations = [];
+      for (const member of this.schemas) {
+        const sink = { errors: [], warnings: [], strict: ctx.strict };
+        member.isValid(raw, sink, path ? [...path] : void 0);
+        if (!sink.errors.length) continue;
+        const depth = Math.max(...sink.errors.map((e) => e.slice(0, e.indexOf(":")).length));
+        if (depth > bestDepth || depth === bestDepth && best && sink.errors.length < best.length) {
+          bestDepth = depth;
+          best = sink.errors;
+        }
+        if (depth <= base.length) {
+          for (const e of sink.errors) {
+            const m = /: expected (.+?), got /.exec(e);
+            if (m && !leafExpectations.includes(m[1])) leafExpectations.push(m[1]);
+          }
+        }
+      }
+      if (best && bestDepth > base.length) {
+        for (const e of best.slice(0, UNION_MEMBER_ERROR_LIMIT)) {
+          if (!ctx.errors.includes(e)) ctx.errors.push(e);
+        }
+      } else if (leafExpectations.length) {
+        ctx.errors.push(base + ": expected " + leafExpectations.join(" | "));
+      }
       return false;
     }
     _canSanitize(raw) {
@@ -1020,6 +1049,76 @@ var PixodeskAnimator = (() => {
   };
 
   // ../svg-animator-core/src/format/PxAnimatorConstants.ts
+  var PxFillMode = {
+    forwards: "forwards",
+    backwards: "backwards",
+    both: "both",
+    none: "none"
+  };
+  var PxPlaybackDirection = {
+    normal: "normal",
+    reverse: "reverse",
+    alternate: "alternate",
+    alternateReverse: "alternate-reverse"
+  };
+  var PxStartOn = {
+    load: "load",
+    mouseOver: "mouseOver",
+    click: "click",
+    scrollIntoView: "scrollIntoView",
+    programmatic: "programmatic"
+  };
+  var PxOutAction = {
+    continue: "continue",
+    pause: "pause",
+    reset: "reset",
+    reverse: "reverse"
+  };
+  var PxFinishAction = {
+    hold: "hold",
+    reset: "reset"
+  };
+  var PxScrollKind = {
+    view: "view",
+    scroll: "scroll"
+  };
+  var PxScrollAxis = {
+    block: "block",
+    inline: "inline",
+    x: "x",
+    y: "y"
+  };
+  var PxScrollSource = {
+    nearest: "nearest",
+    root: "root"
+  };
+  var PxPinAlign = {
+    top: "top",
+    center: "center",
+    bottom: "bottom"
+  };
+  var PxScrollPhase = {
+    cover: "cover",
+    contain: "contain",
+    entry: "entry",
+    exit: "exit",
+    entryCrossing: "entry-crossing",
+    exitCrossing: "exit-crossing"
+  };
+  var PxAlongPathMode = {
+    sampled: "sampled",
+    offsetPath: "offsetPath"
+  };
+  var PX_TIMELINE_SHARED_KEYS = ["duration", "iterations", "engine", "frameRate"];
+  var PX_TIME_ONLY_TIMELINE_KEYS = ["trigger", "delay", "fillMode", "direction"];
+  var PX_FLAT_RUNTIME_VIEW_KEYS = [
+    ...PX_TIMELINE_SHARED_KEYS,
+    ...PX_TIME_ONLY_TIMELINE_KEYS,
+    "fill",
+    "resetOnFinish",
+    "timelineSource",
+    "scroll"
+  ];
   var PxTimelineEngine = {
     native: "native",
     js: "js"
@@ -1033,6 +1132,19 @@ var PixodeskAnimator = (() => {
   function mayUseNativeScrollTimeline(engine) {
     return engine !== PxTimelineEngineExtra.js;
   }
+  var PX_TRIGGER_DEFAULTS = {
+    startOn: "load",
+    outAction: "continue",
+    scrollIntoViewThreshold: 0
+  };
+  function resolveTrigger(trigger) {
+    var _a, _b, _c;
+    return {
+      startOn: (_a = trigger == null ? void 0 : trigger.startOn) != null ? _a : PX_TRIGGER_DEFAULTS.startOn,
+      outAction: (_b = trigger == null ? void 0 : trigger.outAction) != null ? _b : PX_TRIGGER_DEFAULTS.outAction,
+      scrollIntoViewThreshold: (_c = trigger == null ? void 0 : trigger.scrollIntoViewThreshold) != null ? _c : PX_TRIGGER_DEFAULTS.scrollIntoViewThreshold
+    };
+  }
   var PxLoopRepeatAt = {
     /** Segment from the START; the repetition runs BEFORE the first keyframe
      *  (intro loops that play until the main timeline begins). */
@@ -1092,10 +1204,6 @@ var PixodeskAnimator = (() => {
     TRANSFORM_PART.scale,
     TRANSFORM_PART.origin
   ];
-  var PxGradientUnits = {
-    userSpaceOnUse: "userSpaceOnUse",
-    objectBoundingBox: "objectBoundingBox"
-  };
   var PxGradientSpreadMethod = {
     pad: "pad",
     reflect: "reflect",
@@ -1108,8 +1216,18 @@ var PixodeskAnimator = (() => {
   function getAnimatorConfig(doc) {
     var _a;
     const cfg = (doc == null ? void 0 : doc.animator) || ((_a = doc == null ? void 0 : doc.meta) == null ? void 0 : _a.animator);
-    return cfg ? flattenAnimatorTimeline(cfg) : void 0;
-  }
+    if (!cfg) return void 0;
+    const memoised = wireViewMemo.get(cfg);
+    if (memoised) return memoised;
+    const wire = cfg;
+    const stray = PX_FLAT_RUNTIME_VIEW_KEYS.filter((k) => wire[k] !== void 0);
+    const source = stray.length ? __spreadValues({}, wire) : cfg;
+    for (const k of stray) delete source[k];
+    const view = flattenAnimatorTimeline(source);
+    wireViewMemo.set(cfg, view);
+    return view;
+  }
+  var wireViewMemo = /* @__PURE__ */ new WeakMap();
   var flattenMemo = /* @__PURE__ */ new WeakMap();
   function flattenAnimatorTimeline(cfg) {
     const timeline = cfg.timeline;
@@ -1135,7 +1253,7 @@ var PixodeskAnimator = (() => {
       else if (pin && typeof pin === "object") {
         scroll.pin = true;
         if (pin.align !== void 0) scroll.pinAlign = pin.align;
-        if (pin.top !== void 0) scroll.pinTop = pin.top;
+        if (pin.offset !== void 0) scroll.pinOffset = pin.offset;
         if (pin.distance !== void 0) scroll.pinDistance = pin.distance;
       }
       flat.scroll = scroll;
@@ -1177,14 +1295,13 @@ var PixodeskAnimator = (() => {
     // e.g. for colors
     px.number(),
     px.array(px.number()),
-    // ORDER LAW: the key-discriminated object shapes (`{path}`, `{paths}`) come BEFORE the
+    // ORDER LAW: the key-discriminated object shape (`{pathData}`) comes BEFORE the
     // all-optional transform-parts record. In default (non-strict) mode that record accepts
     // ANY object (every key optional, unknown keys ignored), so listing it earlier made
-    // Union.sanitize route `{path}`/`{paths}` values into it and strip them to `{}` —
+    // Union.sanitize route `{pathData}` values into it and strip them to `{}` —
     // silent morph-data loss (repro: the editor's keyframeValueSanitize spec). Validity is
     // order-independent (`some()`); only sanitize routing depends on this order.
-    px.object({ path: px.string() }),
-    px.lazy(() => px.object({ paths: px.array(PxBezierPathSchema) }), { paths: [] }),
+    px.object({ pathData: px.string() }),
     // Gradient `stops` timeline — each kf value is the full stops-array snapshot.
     px.lazy(() => px.array(PxGradientStopSchema), []),
     px.lazy(() => PxTransformPartsSchema, {})
@@ -1224,7 +1341,7 @@ var PixodeskAnimator = (() => {
     keyframes: px.array(PxKeyframeSchema).optional(),
     loop: px.union([PxLoopSchema, px.boolean()]).optional(),
     autoOrient: px.boolean().optional(),
-    alongPathMode: px.enum(["sampled", "offsetPath"]).optional()
+    alongPathMode: px.enum([PxAlongPathMode.sampled, PxAlongPathMode.offsetPath]).optional()
   }));
   var PxTransformPartsSchema = implementsInterface()(px.object({
     translate: px.tuple([px.number(), px.number()]).optional(),
@@ -1248,17 +1365,17 @@ var PixodeskAnimator = (() => {
     PxAnimationDefinitionSchema
   ]));
   var PxTriggerSchema = implementsInterface()(px.object({
-    startOn: px.enum(["load", "mouseOver", "click", "scrollIntoView", "programmatic"]).optional(),
-    outAction: px.enum(["continue", "pause", "reset", "reverse"]).optional(),
+    startOn: px.enum([PxStartOn.load, PxStartOn.mouseOver, PxStartOn.click, PxStartOn.scrollIntoView, PxStartOn.programmatic], PX_TRIGGER_DEFAULTS.startOn).optional(),
+    outAction: px.enum([PxOutAction.continue, PxOutAction.pause, PxOutAction.reset, PxOutAction.reverse], PX_TRIGGER_DEFAULTS.outAction).optional(),
     // What happens after a NATURAL finish — `'hold'` (default: keep the end state per
     // `fill`) or `'reset'` (snap back to the start state). Pairs with `outAction` ("what
     // happens when the trigger condition ends"); both end-of-life knobs now read alike.
-    finishAction: px.enum(["hold", "reset"]).optional(),
+    finishAction: px.enum([PxFinishAction.hold, PxFinishAction.reset]).optional(),
     scrollIntoViewThreshold: px.number().optional()
   }));
   var PxGlyphSchema = implementsInterface()(px.object({
     width: px.number(),
-    d: px.string()
+    pathData: px.string()
   }));
   var PxGlyphFontSchema = implementsInterface()(px.object({
     fontFamily: px.string(),
@@ -1275,9 +1392,15 @@ var PixodeskAnimator = (() => {
     styles: px.record(px.record(px.union([px.string(), px.number()]))).optional(),
     fonts: px.record(PxGlyphFontSchema).optional()
   }));
-  var PX_SCROLL_PHASES = ["cover", "contain", "entry", "exit", "entry-crossing", "exit-crossing"];
   var PxScrollRangePointSchema = implementsInterface()(px.object({
-    phase: px.enum(PX_SCROLL_PHASES).optional(),
+    phase: px.enum([
+      PxScrollPhase.cover,
+      PxScrollPhase.contain,
+      PxScrollPhase.entry,
+      PxScrollPhase.exit,
+      PxScrollPhase.entryCrossing,
+      PxScrollPhase.exitCrossing
+    ]).optional(),
     fraction: px.number().optional()
   }));
   var PxScrollRangeSchema = px.object({
@@ -1285,21 +1408,21 @@ var PixodeskAnimator = (() => {
     end: PxScrollRangePointSchema.optional()
   });
   var PxScrollSchema = implementsInterface()(px.object({
-    kind: px.enum(["view", "scroll"]).optional(),
-    axis: px.enum(["block", "inline", "x", "y"]).optional(),
-    source: px.enum(["nearest", "root"]).optional(),
+    kind: px.enum([PxScrollKind.view, PxScrollKind.scroll]).optional(),
+    axis: px.enum([PxScrollAxis.block, PxScrollAxis.inline, PxScrollAxis.x, PxScrollAxis.y]).optional(),
+    source: px.enum([PxScrollSource.nearest, PxScrollSource.root]).optional(),
     // Free-form: the two keywords `parent`/`scroller` plus any CSS selector.
     subject: px.string().optional(),
     smoothing: px.number().optional(),
     pin: px.boolean().optional(),
-    pinAlign: px.enum(["top", "center", "bottom"]).optional(),
-    pinTop: px.number().optional(),
+    pinAlign: px.enum([PxPinAlign.top, PxPinAlign.center, PxPinAlign.bottom]).optional(),
+    pinOffset: px.number().optional(),
     pinDistance: px.number().optional(),
     range: PxScrollRangeSchema.optional()
   }));
   var PxTimelinePinSchema = implementsInterface()(px.object({
-    align: px.enum(["top", "center", "bottom"]).optional(),
-    top: px.number().optional(),
+    align: px.enum([PxPinAlign.top, PxPinAlign.center, PxPinAlign.bottom]).optional(),
+    offset: px.number().optional(),
     distance: px.number().optional()
   }));
   var PxTimelineEngineSchema = px.enum([PxTimelineEngineExtra.auto, PxTimelineEngineExtra.native, PxTimelineEngineExtra.js]).optional();
@@ -1314,8 +1437,8 @@ var PixodeskAnimator = (() => {
     iterations: px.union([px.number(), px.literal("infinite")]).optional(),
     // `fillMode` on the wire (CSS `animation-fill-mode`; the runtime view calls it `fill`)
     // — never `fill`, which is paint everywhere else in the format.
-    fillMode: px.enum(["forwards", "backwards", "both", "none"]).optional(),
-    direction: px.enum(["normal", "reverse", "alternate", "alternate-reverse"]).optional()
+    fillMode: px.enum([PxFillMode.forwards, PxFillMode.backwards, PxFillMode.both, PxFillMode.none]).optional(),
+    direction: px.enum([PxPlaybackDirection.normal, PxPlaybackDirection.reverse, PxPlaybackDirection.alternate, PxPlaybackDirection.alternateReverse]).optional()
   }));
   var scrollishTimelineShape = {
     // §2.8: duration is a property of the TIMELINE — under scrubbing it is the keyframe
@@ -1326,8 +1449,8 @@ var PixodeskAnimator = (() => {
     iterations: px.number().optional(),
     engine: PxTimelineEngineSchema,
     frameRate: px.number().optional(),
-    axis: px.enum(["block", "inline", "x", "y"]).optional(),
-    source: px.enum(["nearest", "root"]).optional(),
+    axis: px.enum([PxScrollAxis.block, PxScrollAxis.inline, PxScrollAxis.x, PxScrollAxis.y]).optional(),
+    source: px.enum([PxScrollSource.nearest, PxScrollSource.root]).optional(),
     subject: px.string().optional(),
     // 'parent' | 'scroller' | any CSS selector
     smoothing: px.number().optional(),
@@ -1416,7 +1539,7 @@ var PixodeskAnimator = (() => {
     height: px.number().optional()
   }));
   var PxClipPathEffectSchema = implementsInterface()(px.object({
-    d: PxAnimatableStringSchema.optional()
+    pathData: PxAnimatableStringSchema.optional()
   }));
   var PxStrokeTrimEffectSchema = implementsInterface()(px.object({
     offset: PxAnimatableNumberSchema.optional(),
@@ -1453,7 +1576,7 @@ var PixodeskAnimator = (() => {
     radius: PxAnimatableNumberSchema.optional(),
     focal: PxAnimatableVec2Schema.optional(),
     stops: PxAnimatableGradientStopsSchema.optional(),
-    gradientUnits: px.enum([PxGradientUnits.userSpaceOnUse, PxGradientUnits.objectBoundingBox]).optional(),
+    gradientUnits: px.enum([PxUnits.userSpaceOnUse, PxUnits.objectBoundingBox]).optional(),
     spreadMethod: px.enum([PxGradientSpreadMethod.pad, PxGradientSpreadMethod.reflect, PxGradientSpreadMethod.repeat]).optional(),
     gradientTransform: px.string().optional()
   }));
@@ -1499,10 +1622,13 @@ var PixodeskAnimator = (() => {
     // documented — because a wire key that is not in a schema is invisible to the
     // minifier's reserve list and gets renamed (MINIFICATION-BOUNDARY-PLAN.md §1.1).
     domType: px.string().optional(),
+    // Text content of a `<text>` / `<tspan>`. Declared, so a non-string value is a schema error
+    // and the minifier reserves the key; `text` is NOT an alias for it and is not read anywhere.
+    textContent: px.string().optional(),
     id: px.string().optional(),
     meta: px.any().optional(),
     // Player-effects bucket emitted by the Editor's lightweight design format.
-    // Consumed and removed by `applyPlayerEffects` before any other normalisation
+    // Consumed and removed by `applyPlayerEffects` before any other normalization
     // (see `createAnimatorImpl`), so downstream code never sees it.
     effects: PxEffectsSchema.optional(),
     // `PxElementAnimation` (not just `PxAnimationDefinition`) — accepts
@@ -1534,7 +1660,7 @@ var PixodeskAnimator = (() => {
     c: px.boolean().optional()
   }));
 
-  // ../svg-animator-core/src/materialise/PxMotionPath.ts
+  // ../svg-animator-core/src/materialize/PxMotionPath.ts
   function getKfTranslate(kf) {
     const v = kfValue(kf);
     if (!v) return void 0;
@@ -1615,7 +1741,7 @@ var PixodeskAnimator = (() => {
   var DEFAULT_FLATNESS_TOL = 0.5;
   var DEFAULT_ROTATION_TOL = 5;
   var DEFAULT_MAX_SAMPLES = 32;
-  function materialiseMotionPathInPropAnim(anim, opts) {
+  function materializeMotionPathInPropAnim(anim, opts) {
     var _a, _b, _c;
     if (!propAnimIsMotionPath(anim)) return anim;
     const kfs = anim.keyframes;
@@ -1647,7 +1773,7 @@ var PixodeskAnimator = (() => {
       if (autoOrient && i > 0) {
         insertSharpCornerStepKfIfNeeded(out, prevKf, nextKf, prevPos, nextPos, rotationTol);
       }
-      materialiseSegment(out, prevKf, nextKf, prevPos, nextPos, autoOrient, flatnessTol, rotationTol, maxSamples);
+      materializeSegment(out, prevKf, nextKf, prevPos, nextPos, autoOrient, flatnessTol, rotationTol, maxSamples);
     }
     const lastInE = getKfEasing(kfs[kfs.length - 1]);
     if (lastInE) out[out.length - 1].e = lastInE;
@@ -1761,7 +1887,7 @@ var PixodeskAnimator = (() => {
     out.push(makeOutKf(stepTime, dupValue));
   }
   var CORNER_STEP_AFTER_BOUNDARY_MS = 0.05;
-  function materialiseSegment(out, prevKf, nextKf, prevPos, nextPos, autoOrient, flatnessTol, rotationTol, maxSamples) {
+  function materializeSegment(out, prevKf, nextKf, prevPos, nextPos, autoOrient, flatnessTol, rotationTol, maxSamples) {
     const seg = getSegmentCache(prevKf, nextKf, prevPos, nextPos);
     const prevTime = getKfTime(prevKf);
     const nextTime = getKfTime(nextKf);
@@ -1977,8 +2103,8 @@ var PixodeskAnimator = (() => {
     return typeof value === "string" && extractPathData(value) !== void 0;
   }
   function normalizePathValue(value) {
-    if (value && typeof value === "object" && typeof value.path === "string") {
-      const d = extractPathData(value.path);
+    if (value && typeof value === "object" && typeof value.pathData === "string") {
+      const d = extractPathData(value.pathData);
       return d ? { paths: parseSvgPathToBezier(d) } : value;
     }
     if (value && typeof value === "object" && "paths" in value) {
@@ -2062,7 +2188,7 @@ var PixodeskAnimator = (() => {
       const bPaths = (_b = b == null ? void 0 : b.paths) != null ? _b : Array.isArray(b) ? b : [];
       return { paths: interpolateBeziers(aPaths, bPaths, t) };
     }
-    if (COLOUR_ATTR_NAMES.has(propName)) {
+    if (COLOR_ATTR_NAMES.has(propName)) {
       return interpolateColor(a || [0, 0, 0, 1], b || [0, 0, 0, 1], t);
     }
     if (propName === "transform" && typeof a === "object" && a !== null && !Array.isArray(a) && typeof b === "object" && b !== null && !Array.isArray(b)) {
@@ -2284,7 +2410,7 @@ var PixodeskAnimator = (() => {
         value = normalizePathValue(value);
       }
       const propNameKebab = isCamelCaseWord(propName) ? camelCaseToKebabWordIfNeeded(propName) : propName;
-      if (COLOUR_ATTR_NAMES.has(propNameKebab)) {
+      if (COLOR_ATTR_NAMES.has(propNameKebab)) {
         value = (_a = parseColor(value)) != null ? _a : value;
       }
       const normKf = {
@@ -2363,12 +2489,12 @@ var PixodeskAnimator = (() => {
         const out = { keyframes: normalizedKfs };
         if (propAnim.autoOrient !== void 0) out.autoOrient = propAnim.autoOrient;
         if (propAnim.loop !== void 0) out.loop = propAnim.loop;
-        normalized[propName] = engine === PxTimelineEngine.native && propName === "transform" ? materialiseMotionPathInPropAnim(out) : out;
+        normalized[propName] = engine === PxTimelineEngine.native && propName === "transform" ? materializeMotionPathInPropAnim(out) : out;
       }
     }
     return normalized;
   }
-  function getNormalisedBindings(doc, engine = PxTimelineEngine.native) {
+  function getNormalizedBindings(doc, engine = PxTimelineEngine.native) {
     const animatorConfig = getAnimatorConfig(doc) || {};
     const defs = getDefs(doc);
     const duration = animatorConfig.duration || 1e3;
@@ -2459,7 +2585,7 @@ var PixodeskAnimator = (() => {
         nextPaths,
         localProgress
       ).map((bz) => bezierToSvgPath(bz)).join("");
-    } else if (COLOUR_ATTR_NAMES.has(cssAttrName)) {
+    } else if (COLOR_ATTR_NAMES.has(cssAttrName)) {
       cssValue = toRGBA(interpolateColor(
         prevV || [0, 0, 0, 1],
         nextV || [0, 0, 0, 1],
@@ -2556,6 +2682,40 @@ var PixodeskAnimator = (() => {
     return result;
   }
 
+  // ../svg-animator-core/src/playback/PxPlaybackTime.ts
+  var PX_RATE_REJECTED = "setPlaybackRate: rate must be finite and non-zero";
+  function isValidPlaybackRate(rate) {
+    return Number.isFinite(rate) && rate !== 0;
+  }
+  function seekCeilingMs(durationMs, iterations) {
+    if (!(durationMs > 0)) return 0;
+    if (iterations === Infinity) return Infinity;
+    return durationMs * (iterations > 0 ? iterations : 1);
+  }
+  function progressSpanMs(durationMs, iterations) {
+    if (!(durationMs > 0)) return 0;
+    if (iterations === Infinity) return durationMs;
+    return durationMs * (iterations > 0 ? iterations : 1);
+  }
+  function clampSeekMs(timeMs, ceilingMs) {
+    if (Number.isNaN(timeMs) || timeMs < 0) return 0;
+    if (Number.isFinite(ceilingMs)) return timeMs > ceilingMs ? ceilingMs : timeMs;
+    return Number.isFinite(timeMs) ? timeMs : 0;
+  }
+  function timeToProgress(timeMs, durationMs, iterations) {
+    const span = progressSpanMs(durationMs, iterations);
+    if (!(span > 0) || !Number.isFinite(timeMs)) return 0;
+    if (timeMs <= 0) return 0;
+    if (iterations === Infinity) return timeMs % span / span;
+    return timeMs >= span ? 1 : timeMs / span;
+  }
+  function progressToTimeMs(progress, durationMs, iterations) {
+    const span = progressSpanMs(durationMs, iterations);
+    if (!(span > 0) || !Number.isFinite(progress)) return 0;
+    if (progress <= 0) return 0;
+    return progress >= 1 ? span : progress * span;
+  }
+
   // ../svg-animator-core/src/playback/PxFrameLoop.ts
   function requestFrame(cb) {
     const g = globalThis;
@@ -2573,7 +2733,7 @@ var PixodeskAnimator = (() => {
   function createBasicFrameLoopAnimator(doc, adapter, callbacks) {
     var _a;
     const config = getAnimatorConfig(doc) || {};
-    const bindings = getNormalisedBindings(doc, PxTimelineEngine.js);
+    const bindings = getNormalizedBindings(doc, PxTimelineEngine.js);
     const _iterations = config.iterations;
     let iterations = 1;
     if (typeof _iterations === "number") iterations = _iterations || 1;
@@ -2803,8 +2963,8 @@ var PixodeskAnimator = (() => {
         finishAnim(true);
       },
       "setPlaybackRate": (rate) => {
-        if (!isFinite(rate) || rate === 0) {
-          console.warn("setPlaybackRate: rate must be finite and non-zero");
+        if (!isValidPlaybackRate(rate)) {
+          console.warn(PX_RATE_REJECTED);
           return;
         }
         let current = getRawAnimTime();
@@ -2818,13 +2978,16 @@ var PixodeskAnimator = (() => {
         return getAnimCurrentTime();
       },
       "setCurrentTime": (newTime) => {
-        if (newTime < 0) newTime = 0;
-        if (Number.isFinite(totalDuration) && newTime > totalDuration) newTime = totalDuration;
+        newTime = clampSeekMs(newTime, totalDuration);
         timeBeforeLastStartMs = newTime;
         if (playing) lastStartedTs = Date.now();
         if (!Number.isFinite(totalDuration) || newTime < totalDuration) finishCalled = false;
         renderFrame(getAnimCurrentTime());
       },
+      "getCurrentProgress": () => timeToProgress(getAnimCurrentTime(), duration, iterations),
+      "setCurrentProgress": (progress) => {
+        api.setCurrentTime(progressToTimeMs(progress, duration, iterations));
+      },
       "destroy": () => {
         var _a2;
         api.cancel();
@@ -2834,13 +2997,82 @@ var PixodeskAnimator = (() => {
     return api;
   }
 
+  // ../svg-animator-core/src/playback/PxDiagnostics.ts
+  var PxDiagnosticKind = {
+    /** The document is wrong — regenerate or repair the file. */
+    document: "document",
+    /** The page or app cannot provide what the document asks for — fix the mount. */
+    host: "host",
+    /** The platform cannot do it and the player degraded — usually nothing to fix. */
+    platform: "platform",
+    /** The call is wrong or self-contradictory — fix the options or props you passed. */
+    usage: "usage",
+    /** The player failed where it did not expect to — report it to us. */
+    internal: "internal"
+  };
+  function asError(error) {
+    return typeof error === "string" ? new Error(error) : error;
+  }
+  function isSilenced(silent, kind) {
+    if (!silent) return false;
+    return silent === true || silent.includes(kind);
+  }
+  function createDiagnostics(config, prefix) {
+    const tag = prefix ? prefix + " " : "";
+    return {
+      warn: (kind, message, detail) => {
+        if (config == null ? void 0 : config.onWarn) {
+          config.onWarn({ kind, message, detail });
+          return;
+        }
+        if (isSilenced(config == null ? void 0 : config.silent, kind)) return;
+        const line = tag + kind + ": " + message;
+        if (detail === void 0) console.warn(line);
+        else console.warn(line, detail);
+      },
+      error: (kind, error) => {
+        const err = asError(error);
+        if (config == null ? void 0 : config.onError) {
+          config.onError({ kind, message: err.message, error: err });
+          return;
+        }
+        if (isSilenced(config == null ? void 0 : config.silent, kind)) return;
+        console.error(tag + kind + ": " + err.message);
+      }
+    };
+  }
+
+  // src/shared/PxAnimatorCallbacks.ts
+  function toEngineCallbacks(inline) {
+    const { onPlay, onPause, onCancel, onFinish, onRemove, onStop, onWarn, onError, silent } = inline != null ? inline : {};
+    const withStop = (own) => own || onStop ? () => {
+      own == null ? void 0 : own();
+      onStop == null ? void 0 : onStop();
+    } : void 0;
+    return {
+      onPlay,
+      onPause: withStop(onPause),
+      onCancel: withStop(onCancel),
+      onFinish: withStop(onFinish),
+      onRemove: withStop(onRemove),
+      onWarn,
+      onError,
+      silent
+    };
+  }
+
   // src/triggers/PxAnimatorTriggers.ts
-  function setupAnimationTriggers(api, config) {
-    const { startOn, outAction = "continue", scrollIntoViewThreshold = 0 } = config;
+  function setupAnimationTriggers(api, config, diag) {
+    const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
+    const cleanups = [];
+    const dispose = () => {
+      for (const undo of cleanups.splice(0)) undo();
+    };
+    const { startOn, outAction, scrollIntoViewThreshold } = resolveTrigger(config);
     const root = api.getRootElement();
     if (!root) {
-      console.warn("setupAnimationTriggers: No root element found for animation.");
-      return api;
+      report.warn(PxDiagnosticKind.host, "setupAnimationTriggers: No root element found for animation.");
+      return dispose;
     }
     let reversed = false;
     const start = () => {
@@ -2875,6 +3107,7 @@ var PixodeskAnimator = (() => {
           startHandler();
         } else {
           window.addEventListener("load", startHandler, { once: true });
+          cleanups.push(() => window.removeEventListener("load", startHandler));
         }
         break;
       }
@@ -2889,6 +3122,10 @@ var PixodeskAnimator = (() => {
         };
         root.addEventListener("mouseenter", mouseOverHandler);
         root.addEventListener("mouseleave", mouseOutHandler);
+        cleanups.push(() => {
+          root.removeEventListener("mouseenter", mouseOverHandler);
+          root.removeEventListener("mouseleave", mouseOutHandler);
+        });
         break;
       }
       case "click": {
@@ -2900,6 +3137,7 @@ var PixodeskAnimator = (() => {
           }
         };
         root.addEventListener("click", clickHandler);
+        cleanups.push(() => root.removeEventListener("click", clickHandler));
         break;
       }
       case "scrollIntoView": {
@@ -2931,12 +3169,13 @@ var PixodeskAnimator = (() => {
           { threshold: thresholdSteps }
         );
         observer.observe(root);
+        cleanups.push(() => observer.disconnect());
         break;
       }
       case "programmatic":
         break;
     }
-    return api;
+    return dispose;
   }
 
   // src/engines/PxAnimatorFrameLoop.ts
@@ -2944,35 +3183,41 @@ var PixodeskAnimator = (() => {
     return "#" + id;
   }
   function createFrameLoopAnimator(doc, adapter, callbacks, rootElement) {
+    var _a;
     const config = getAnimatorConfig(doc) || {};
+    const diag = createDiagnostics(callbacks, "[PxAnimator]");
     if (!rootElement) {
       if (doc.id) {
         const rootSelector = getSelector(doc.id);
         rootElement = document.querySelector(rootSelector);
-        if (!rootElement) console.warn("createFrameLoopAnimator: No root element found for selector: ", rootSelector);
+        if (!rootElement) diag.warn(PxDiagnosticKind.host, "createFrameLoopAnimator: No root element found for selector: " + rootSelector);
       } else {
-        console.warn("createFrameLoopAnimator: No root element provided");
+        diag.warn(PxDiagnosticKind.host, "createFrameLoopAnimator: No root element provided");
       }
     }
     const basicApi = createBasicFrameLoopAnimator(
       doc,
-      adapter || createDomAdapter(rootElement),
+      adapter || createDomAdapter(rootElement, diag),
       callbacks
     );
     const api = __spreadProps(__spreadValues({}, basicApi), {
       "getRootElement": () => rootElement || null
     });
-    if (config.trigger) {
-      if (isScrollTimeline(config)) {
-        console.warn("scroll timeline: `animator.trigger` is ignored (triggers do not apply to scroll-driven playback)");
-      } else {
-        setupAnimationTriggers(api, config.trigger);
-      }
+    if (isScrollTimeline(config)) {
+      if (config.trigger) diag.warn(PxDiagnosticKind.usage, "scroll timeline: `animator.trigger` is ignored (triggers do not apply to scroll-driven playback)");
+    } else {
+      const detachTriggers = setupAnimationTriggers(api, (_a = config.trigger) != null ? _a : {}, diag);
+      const destroyEngine = api.destroy.bind(api);
+      api.destroy = () => {
+        detachTriggers();
+        destroyEngine();
+      };
     }
     return api;
   }
-  function createDomAdapter(rootElement) {
+  function createDomAdapter(rootElement, diag) {
     const warnedSelectors = /* @__PURE__ */ new Set();
+    const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
     const adapter = {
       isConnected: () => {
         if (!rootElement) return true;
@@ -2984,7 +3229,7 @@ var PixodeskAnimator = (() => {
         const elements = (rootElement == null ? void 0 : rootElement.querySelectorAll(selector)) || document.querySelectorAll(selector);
         if (elements.length === 0 && !warnedSelectors.has(selector)) {
           warnedSelectors.add(selector);
-          console.warn('setAttribute: No elements found for selector "' + selector + '"');
+          report.warn(PxDiagnosticKind.host, 'setAttribute: No elements found for selector "' + selector + '"');
         }
         for (let i = 0; i < elements.length; i++) {
           const element = elements[i];
@@ -3009,7 +3254,7 @@ var PixodeskAnimator = (() => {
     };
     let cssValue;
     let cssKey = propName;
-    if (COLOUR_ATTR_NAMES.has(propName) && Array.isArray(value)) {
+    if (COLOR_ATTR_NAMES.has(propName) && Array.isArray(value)) {
       cssValue = toRGBA(value);
     } else if (propName === "transform" && value !== null && typeof value === "object" && !Array.isArray(value)) {
       cssValue = composeTransformParts(value, { withUnits: true });
@@ -3096,18 +3341,19 @@ var PixodeskAnimator = (() => {
     return result;
   }
   function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsupportedAttrs, scrollTimeline) {
-    var _a;
+    var _a, _b;
     const config = getAnimatorConfig(doc) || {};
+    const diag = createDiagnostics(callbacks, "[PxAnimator]");
     if (!rootElement) {
       if (doc.id) {
         const rootSelector = getSelector(doc.id);
         rootElement = document.querySelector(rootSelector);
-        if (!rootElement) console.warn("createFrameLoopAnimator: No root element found for selector: ", rootSelector);
+        if (!rootElement) diag.warn(PxDiagnosticKind.host, "createWebApiAnimator: No root element found for selector: " + rootSelector);
       } else {
-        console.warn("createFrameLoopAnimator: No root element provided");
+        diag.warn(PxDiagnosticKind.host, "createWebApiAnimator: No root element provided");
       }
     }
-    const bindings = getNormalisedBindings(doc, PxTimelineEngine.native);
+    const bindings = getNormalizedBindings(doc, PxTimelineEngine.native);
     const animations = [];
     const _iterations = config.iterations;
     let iterations;
@@ -3117,18 +3363,18 @@ var PixodeskAnimator = (() => {
     let finishNotified = false;
     let removeCalled = false;
     if (!(bindings == null ? void 0 : bindings.length)) {
-      console.warn("createWebApiAnimator: No animation bindings defined");
+      diag.warn(PxDiagnosticKind.document, "createWebApiAnimator: No animation bindings defined");
     }
     for (const binding of bindings || []) {
       const animDef = binding.animate;
       if (!animDef || typeof animDef !== "object" || Array.isArray(animDef)) {
-        console.warn("createWebApiAnimator: Empty or unresolved binding", binding);
+        diag.warn(PxDiagnosticKind.document, "createWebApiAnimator: Empty or unresolved binding", binding);
         continue;
       }
       const selector = getSelector(binding.id);
       const elements = (rootElement == null ? void 0 : rootElement.querySelectorAll(selector)) || document.querySelectorAll(selector);
       if (elements.length === 0) {
-        console.warn('createWebApiAnimator: No elements found for selector "' + selector + '"');
+        diag.warn(PxDiagnosticKind.host, 'createWebApiAnimator: No elements found for selector "' + selector + '"');
       }
       const keyframesMap = convertToWebApiKeyframes(animDef, unsupportedSet, config);
       const positiveDelay = config.delay && config.delay > 0 ? config.delay : void 0;
@@ -3177,14 +3423,14 @@ var PixodeskAnimator = (() => {
               }
               animations.push(anim);
             } catch (e) {
-              console.warn(e);
+              diag.warn(PxDiagnosticKind.internal, "createWebApiAnimator: could not build the animation", e);
             }
           }
         }
       }
     }
     if (!forceEvenIfHasUnsupportedAttrs && unsupportedSet.size) {
-      console.warn("Unsupported CSS attrs: " + [...unsupportedSet].join(", "));
+      diag.warn(PxDiagnosticKind.platform, "Unsupported CSS attrs: " + [...unsupportedSet].join(", "));
       return null;
     }
     const api = {
@@ -3228,20 +3474,36 @@ var PixodeskAnimator = (() => {
         }
       },
       "setPlaybackRate": (rate) => {
+        if (!isValidPlaybackRate(rate)) {
+          diag.warn(PxDiagnosticKind.usage, PX_RATE_REJECTED);
+          return api;
+        }
         animations.forEach((a) => a.playbackRate = rate);
         return api;
       },
       "getCurrentTime": () => {
-        var _a2, _b;
-        const res = (_b = (_a2 = animations[0]) == null ? void 0 : _a2.currentTime) != null ? _b : null;
+        var _a2, _b2;
+        const res = (_b2 = (_a2 = animations[0]) == null ? void 0 : _a2.currentTime) != null ? _b2 : null;
         return res !== null ? +res : null;
       },
       "setCurrentTime": (time) => {
+        var _a2;
+        const ceiling = seekCeilingMs((_a2 = config.duration) != null ? _a2 : 0, iterations != null ? iterations : 1);
+        const seek = ceiling > 0 ? clampSeekMs(time, ceiling) : Math.max(0, time);
         finishNotified = false;
         animations.forEach((a) => {
-          a.currentTime = time;
+          a.currentTime = seek;
         });
       },
+      "getCurrentProgress": () => {
+        var _a2;
+        const t = api.getCurrentTime();
+        return t === null ? null : timeToProgress(t, (_a2 = config.duration) != null ? _a2 : 0, iterations != null ? iterations : 1);
+      },
+      "setCurrentProgress": (progress) => {
+        var _a2;
+        api.setCurrentTime(progressToTimeMs(progress, (_a2 = config.duration) != null ? _a2 : 0, iterations != null ? iterations : 1));
+      },
       "destroy": () => {
         var _a2;
         api.cancel();
@@ -3252,12 +3514,15 @@ var PixodeskAnimator = (() => {
         }
       }
     };
-    if (config.trigger) {
-      if (config.timelineSource === "scroll") {
-        console.warn("scroll timeline: `animator.trigger` is ignored (triggers do not apply to scroll-driven playback)");
-      } else {
-        setupAnimationTriggers(api, config.trigger);
-      }
+    if (config.timelineSource === "scroll") {
+      if (config.trigger) diag.warn(PxDiagnosticKind.usage, "scroll timeline: `animator.trigger` is ignored (triggers do not apply to scroll-driven playback)");
+    } else {
+      const detachTriggers = setupAnimationTriggers(api, (_b = config.trigger) != null ? _b : {}, diag);
+      const destroyEngine = api.destroy.bind(api);
+      api.destroy = () => {
+        detachTriggers();
+        destroyEngine();
+      };
     }
     if (scrollTimeline) {
       animations.forEach((a) => a.play());
@@ -3273,13 +3538,14 @@ var PixodeskAnimator = (() => {
     if (pct === void 0) return void 0;
     return view ? { rangeName: (_c = point == null ? void 0 : point.phase) != null ? _c : "cover", offset: pct } : { offset: pct };
   }
-  function createNativeScrollTimeline(subject, config) {
+  function createNativeScrollTimeline(subject, config, diag) {
     var _a, _b, _c, _d;
+    const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
     if (!config || !isScrollTimeline(config)) return null;
     const scroll = config.scroll || {};
     const kind = (_a = scroll.kind) != null ? _a : "view";
     if (scroll.smoothing) {
-      console.warn("scroll timeline: `smoothing` needs the built-in driver \u2014 using the built-in driver instead of the browser timeline");
+      report.warn(PxDiagnosticKind.platform, "scroll timeline: `smoothing` needs the built-in driver \u2014 using the built-in driver instead of the browser timeline");
       return null;
     }
     const g = globalThis;
@@ -3290,13 +3556,13 @@ var PixodeskAnimator = (() => {
     let timeline;
     try {
       if (view) {
-        timeline = new Ctor({ subject: resolveScrollSubject(subject, scroll.subject), axis });
+        timeline = new Ctor({ subject: resolveScrollSubject(subject, scroll.subject, report), axis });
       } else {
         const source = scroll.source === "root" ? documentScroller() : findNearestScroller(subject, "y") || findNearestScroller(subject, "x") || documentScroller();
         timeline = new Ctor({ source, axis });
       }
     } catch (e) {
-      console.warn("scroll timeline: native timeline construction failed \u2014 falling back to the player measuring progress itself", e);
+      report.warn(PxDiagnosticKind.platform, "scroll timeline: native timeline construction failed \u2014 falling back to the player measuring progress itself", e);
       return null;
     }
     return {
@@ -3323,8 +3589,9 @@ var PixodeskAnimator = (() => {
   }
   var SUBJECT_PARENT = "parent";
   var SUBJECT_SCROLLER = "scroller";
-  function resolveScrollSubject(svgRoot, subject) {
+  function resolveScrollSubject(svgRoot, subject, diag) {
     var _a, _b;
+    const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
     const spec = subject == null ? void 0 : subject.trim();
     if (!spec) return svgRoot;
     if (spec === SUBJECT_PARENT) {
@@ -3342,21 +3609,22 @@ var PixodeskAnimator = (() => {
     try {
       found = document.querySelector(spec);
     } catch (e) {
-      console.warn('scroll timeline: subject "' + spec + '" is not a valid selector \u2014 measuring the SVG itself');
+      report.warn(PxDiagnosticKind.document, 'scroll timeline: subject "' + spec + '" is not a valid selector \u2014 measuring the SVG itself');
       return svgRoot;
     }
     if (!found) {
-      console.warn('scroll timeline: subject "' + spec + '" matched no element \u2014 measuring the SVG itself');
+      report.warn(PxDiagnosticKind.host, 'scroll timeline: subject "' + spec + '" matched no element \u2014 measuring the SVG itself');
       return svgRoot;
     }
     return found;
   }
-  function createScrollDriver(subject, config, onProgress) {
+  function createScrollDriver(subject, config, onProgress, diag) {
     var _a, _b;
     if (!config || !isScrollTimeline(config)) return null;
+    const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
     const scroll = config.scroll || {};
     const kind = (_a = scroll.kind) != null ? _a : "view";
-    const measured = resolveScrollSubject(subject, scroll.subject);
+    const measured = resolveScrollSubject(subject, scroll.subject, report);
     const nearest = findNearestScroller(subject, "y") || findNearestScroller(subject, "x");
     const scroller = kind === "scroll" && scroll.source === "root" ? documentScroller() : nearest || documentScroller();
     const isRootScroller = scroller === documentScroller();
@@ -3475,7 +3743,7 @@ var PixodeskAnimator = (() => {
     const alignFactor = scroll.pinAlign === "center" ? 0.5 : scroll.pinAlign === "bottom" ? 1 : 0;
     const applyTop = () => {
       var _a;
-      const extra = (_a = scroll.pinTop) != null ? _a : 0;
+      const extra = (_a = scroll.pinOffset) != null ? _a : 0;
       if (!alignFactor) {
         style.top = extra + "px";
         return;
@@ -3537,6 +3805,7 @@ var PixodeskAnimator = (() => {
   }
   function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
     const animatorConfig = getAnimatorConfig(doc) || {};
+    const diag = createDiagnostics(callbacks, "[PxAnimator]");
     if (isScrollTimeline(animatorConfig)) {
       return finaliseAnimator(animatorConfig, callbacks, (cb) => {
         var _a;
@@ -3544,7 +3813,7 @@ var PixodeskAnimator = (() => {
         };
         if (mayUseNativeScrollTimeline(animatorConfig.engine) && rootElement) {
           unpin = applyScrollPin(rootElement, animatorConfig.scroll);
-          const native = createNativeScrollTimeline(rootElement, animatorConfig);
+          const native = createNativeScrollTimeline(rootElement, animatorConfig, diag);
           if (native) {
             const api2 = createWebApiAnimator(
               doc,
@@ -3574,7 +3843,8 @@ var PixodeskAnimator = (() => {
           const driver = createScrollDriver(
             subject,
             animatorConfig,
-            (progress) => api.setCurrentTime(progress * totalMs)
+            (progress) => api.setCurrentTime(progress * totalMs),
+            diag
           );
           if (driver) {
             const destroy = api.destroy.bind(api);
@@ -3585,7 +3855,7 @@ var PixodeskAnimator = (() => {
             };
           }
         } else {
-          console.warn("scroll timeline: no root element to observe \u2014 animation will stay at frame 0");
+          diag.warn(PxDiagnosticKind.host, "scroll timeline: no root element to observe \u2014 animation will stay at frame 0");
         }
         return api;
       });
@@ -3602,16 +3872,16 @@ var PixodeskAnimator = (() => {
       ) || createFrameLoopAnimator(doc, adapter, cb, rootElement);
     });
   }
-  function requireData(options) {
-    if (!(options == null ? void 0 : options.data)) throw new Error("createAnimator: `data` is required");
-    return options.data;
+  function requireDoc(options) {
+    if (!(options == null ? void 0 : options.doc)) throw new Error("createAnimator: `doc` is required");
+    return options.doc;
   }
   function createPrerenderedAnimator(options) {
-    return bindWithEngineChoice(requireData(options), options.adapter, options.callbacks, null);
+    return bindWithEngineChoice(requireDoc(options), options.adapter, toEngineCallbacks(options), null);
   }
 
   // src/shared/PxAnimatorKeys.ts
-  var PX_ANIMATOR_DATA_KEY = "data";
+  var PX_ANIMATOR_DOC_KEY = "doc";
   return __toCommonJS(index_prerendered_exports);
 })();
 //# sourceMappingURL=index.prerendered.umd.js.map