@pixodesk/svg-animator-web 1.0.35 → 1.0.39

package/dist/index.js

@@ -292,7 +292,7 @@ function parseColor(s) {
   }
   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) {
@@ -671,6 +671,7 @@ var Enum = class extends Base {
     return false;
   }
 };
+var UNION_MEMBER_ERROR_LIMIT = 4;
 var Union = class extends Base {
   constructor(schemas, defaultVal) {
     super();
@@ -688,7 +689,35 @@ var Union = class extends Base {
     var _a2;
     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 " + ((_a2 = JSON.stringify(raw)) != null ? _a2 : "").slice(0, 240));
+    if (!ctx) return false;
+    const base = pathStr(path != null ? path : []);
+    ctx.errors.push(base + ": no union member matched for value " + ((_a2 = JSON.stringify(raw)) != null ? _a2 : "").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) {
@@ -1060,6 +1089,17 @@ var px = {
   lazy: (fn, defaultVal) => new Lazy(fn, defaultVal)
 };
 var PX_PLAYER_SCHEMA_VERSION = "1.1";
+var WIRE_VERSION_KEY = "version";
+var ANIMATOR_KEY = "animator";
+var META_KEY = "meta";
+var WireVersionRelation = /* @__PURE__ */ ((WireVersionRelation2) => {
+  WireVersionRelation2["unstamped"] = "unstamped";
+  WireVersionRelation2["same"] = "same";
+  WireVersionRelation2["older"] = "older";
+  WireVersionRelation2["newer"] = "newer";
+  WireVersionRelation2["otherGeneration"] = "otherGeneration";
+  return WireVersionRelation2;
+})(WireVersionRelation || {});
 var VERSION_RE = /^(\d+)\.(\d+)(?:\.(\d+))?$/;
 function parseWireVersion(raw) {
   if (typeof raw !== "string") return void 0;
@@ -1067,12 +1107,235 @@ function parseWireVersion(raw) {
   if (!m) return void 0;
   return { a: Number(m[1]), b: Number(m[2]), c: m[3] === void 0 ? 0 : Number(m[3]) };
 }
+function formatWireVersion(v) {
+  return v.a + "." + v.b + "." + v.c;
+}
 var _a;
 var PLAYER_WIRE_VERSION = (_a = parseWireVersion(PX_PLAYER_SCHEMA_VERSION)) != null ? _a : { a: 1, b: 1, c: 0 };
+function getAnimatorBlock(doc) {
+  if (!doc || typeof doc !== "object") return void 0;
+  const atRoot = readObjectProp(doc, ANIMATOR_KEY);
+  if (atRoot) return atRoot;
+  const meta = readObjectProp(doc, META_KEY);
+  return meta ? readObjectProp(meta, ANIMATOR_KEY) : void 0;
+}
+function readObjectProp(obj, key) {
+  const value = obj[key];
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function readWireVersion(doc) {
+  const animator = getAnimatorBlock(doc);
+  return animator ? parseWireVersion(animator[WIRE_VERSION_KEY]) : void 0;
+}
+function compareWireVersion(file, mine, readerReadsEditorPart) {
+  if (!file) return "unstamped";
+  if (file.a !== mine.a) return "otherGeneration";
+  if (file.b !== mine.b) return file.b > mine.b ? "newer" : "older";
+  if (!readerReadsEditorPart || file.c === mine.c) return "same";
+  return file.c > mine.c ? "newer" : "older";
+}
+function versionAdvice(relation, file, mine, isPlayer) {
+  if (!file) return void 0;
+  const target = isPlayer ? "player" : "editor";
+  const gap = "written for schema " + formatWireVersion(file) + ", this " + target + " reads " + formatWireVersion(mine);
+  switch (relation) {
+    case "newer":
+      return "This file is " + gap + ". Update the " + target + " to open it fully.";
+    case "older":
+      return "This file is " + gap + ". Saving it from this " + target + " rewrites it in the current format.";
+    case "otherGeneration":
+      return "This file is " + gap + " \u2014 a different format generation, which no conversion bridges. Open it in a " + target + " of that generation, or accept this document without the parts named above.";
+    default:
+      return void 0;
+  }
+}
+var WireStepKind = /* @__PURE__ */ ((WireStepKind2) => {
+  WireStepKind2["additive"] = "additive";
+  WireStepKind2["converted"] = "converted";
+  return WireStepKind2;
+})(WireStepKind || {});
+var BASELINE_PLAYER_VERSION = "1.1";
+var PLAYER_WIRE_STEPS = [];
+function applyWireSteps(doc, cfg) {
+  const from = readWireVersion(doc);
+  const relation = compareWireVersion(from, cfg.target, cfg.readerReadsEditorPart);
+  if (!from || relation !== "older") {
+    return {
+      doc,
+      from,
+      relation,
+      applied: [],
+      advice: versionAdvice(relation, from, cfg.target, !cfg.readerReadsEditorPart)
+    };
+  }
+  const due = [];
+  for (const step of cfg.steps) {
+    const stepTo = parseWireVersion(step.to);
+    if (!stepTo) continue;
+    if (compareWireVersion(from, stepTo, cfg.readerReadsEditorPart) !== "older") continue;
+    if (!step.up) continue;
+    due.push(step);
+  }
+  if (!due.length || !doc || typeof doc !== "object") return { doc, from, relation, applied: [] };
+  const target = clonePlain(doc);
+  const applied = [];
+  for (const step of due) {
+    try {
+      step.up(target);
+      applied.push(step);
+    } catch (e) {
+      break;
+    }
+  }
+  if (!applied.length) return { doc, from, relation, applied: [] };
+  stampVersion(target, cfg.target, cfg.readerReadsEditorPart);
+  return { doc: target, from, relation, applied };
+}
+function convertPlayerDocument(doc) {
+  return applyWireSteps(doc, {
+    steps: PLAYER_WIRE_STEPS,
+    target: PLAYER_WIRE_VERSION,
+    readerReadsEditorPart: false
+  });
+}
+function clonePlain(value) {
+  const structured = globalThis.structuredClone;
+  return structured ? structured(value) : JSON.parse(JSON.stringify(value));
+}
+function stampVersion(doc, target, readerReadsEditorPart) {
+  const animator = getAnimatorBlock(doc);
+  if (!animator) return;
+  const previous = parseWireVersion(animator[WIRE_VERSION_KEY]);
+  animator[WIRE_VERSION_KEY] = formatWireVersion({
+    a: target.a,
+    b: target.b,
+    c: readerReadsEditorPart ? target.c : previous ? previous.c : 0
+  });
+}
+function applyWireStepsDown(doc, cfg) {
+  const from = readWireVersion(doc);
+  if (!from) {
+    return { ok: false, blocking: [], reason: "The document carries no version, so there is nothing to convert down from." };
+  }
+  const relation = compareWireVersion(from, cfg.target, cfg.readerReadsEditorPart);
+  if (relation === "otherGeneration") {
+    return {
+      ok: false,
+      blocking: [],
+      reason: "Schema " + formatWireVersion(from) + " and " + formatWireVersion(cfg.target) + " are different generations; no conversion bridges them."
+    };
+  }
+  if (relation !== "newer") return { ok: true, doc, applied: [] };
+  const toUndo = [];
+  for (const step of cfg.steps) {
+    const stepTo = parseWireVersion(step.to);
+    if (!stepTo) continue;
+    if (compareWireVersion(stepTo, cfg.target, cfg.readerReadsEditorPart) !== "newer") continue;
+    if (compareWireVersion(stepTo, from, cfg.readerReadsEditorPart) === "newer") continue;
+    toUndo.push(step);
+  }
+  toUndo.reverse();
+  const blocking = toUndo.filter((s) => s.kind === "converted" && !s.down);
+  if (blocking.length) {
+    return {
+      ok: false,
+      blocking,
+      reason: "Cannot convert down to " + formatWireVersion(cfg.target) + ": " + blocking.map((s) => s.from + " \u2192 " + s.to + " (" + s.reason + ")").join("; ") + " cannot be undone."
+    };
+  }
+  const target = clonePlain(doc);
+  const applied = [];
+  for (const step of toUndo) {
+    if (!step.down) continue;
+    try {
+      step.down(target);
+      applied.push(step);
+    } catch (e) {
+      return {
+        ok: false,
+        blocking: [step],
+        reason: "Undoing " + step.from + " \u2192 " + step.to + " failed: " + String(e)
+      };
+    }
+  }
+  stampVersion(target, cfg.target, cfg.readerReadsEditorPart);
+  return { ok: true, doc: target, applied };
+}
+function downgradePlayerDocument(doc, target) {
+  return applyWireStepsDown(doc, { steps: PLAYER_WIRE_STEPS, target, readerReadsEditorPart: false });
+}
+var PxFillMode = {
+  forwards: "forwards",
+  backwards: "backwards",
+  both: "both",
+  none: "none"
+};
+var PxPlaybackDirection = {
+  normal: "normal",
+  reverse: "reverse",
+  alternate: "alternate",
+  alternateReverse: "alternate-reverse"
+};
 var PX_ANIM_SRC_ATTR_NAME = "data-px-animation-src";
 var PX_ANIM_ATTR_NAME = "_px_animator";
+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"
@@ -1089,6 +1352,50 @@ function isNativeForced(engine) {
 function mayUseNativeScrollTimeline(engine) {
   return engine !== PxTimelineEngineExtra.js;
 }
+var PX_TRIGGER_DEFAULTS = {
+  startOn: "load",
+  outAction: "continue",
+  scrollIntoViewThreshold: 0
+};
+var PxControlMode = {
+  /** No control props — the document's trigger decides, and nothing is taken over. */
+  static: "static",
+  /** `progress` / `time` — the host scrubs; the component seeks and stays paused. */
+  fixedTime: "fixedTime",
+  /** `play` / `pause` — the host drives playback with booleans. */
+  play: "play",
+  /** `autoplay` — the document's own trigger starts it. */
+  autoplay: "autoplay"
+};
+function resolveControlMode(props) {
+  const hasFixedTime = props.progress !== void 0 || props.time !== void 0;
+  const hasPlayPause = props.play !== void 0 || props.pause !== void 0;
+  const hasAutoplay = !!props.autoplay;
+  const warnings = [];
+  const named = (a, b, winner) => a + " and " + b + " were both set \u2014 " + winner + " wins, " + (winner === a ? b : a) + " is ignored.";
+  if (hasFixedTime) {
+    if (hasPlayPause) warnings.push(named("progress/time", "play/pause", "progress/time"));
+    if (hasAutoplay) warnings.push(named("progress/time", "autoplay", "progress/time"));
+    return { mode: PxControlMode.fixedTime, warnings };
+  }
+  if (hasPlayPause) {
+    if (hasAutoplay) warnings.push(named("play/pause", "autoplay", "play/pause"));
+    return { mode: PxControlMode.play, warnings };
+  }
+  if (hasAutoplay) return { mode: PxControlMode.autoplay, warnings };
+  return { mode: PxControlMode.static, warnings };
+}
+function controlModeTakesOverTrigger(mode) {
+  return mode !== PxControlMode.autoplay;
+}
+function resolveTrigger(trigger) {
+  var _a2, _b, _c;
+  return {
+    startOn: (_a2 = trigger == null ? void 0 : trigger.startOn) != null ? _a2 : 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). */
@@ -1135,7 +1442,6 @@ var PxStrokeTrimSubPaths = {
   separate: "separate",
   combined: "combined"
 };
-var TEXT_ATTR = "text";
 var TEXT_CONTENT_ATTR = "textContent";
 var CLASS_ATTR = "class";
 var TRANSFORM_ATTR = "transform";
@@ -1147,7 +1453,6 @@ var INTERNAL_ATTRS = /* @__PURE__ */ new Set([
   "meta",
   "animate",
   "effects",
-  TEXT_ATTR,
   TEXT_CONTENT_ATTR
 ]);
 var TRANSFORM_PART = {
@@ -1162,10 +1467,6 @@ var PX_TRANSFORM_PART_KEYS = [
   TRANSFORM_PART.scale,
   TRANSFORM_PART.origin
 ];
-var PxGradientUnits = {
-  userSpaceOnUse: "userSpaceOnUse",
-  objectBoundingBox: "objectBoundingBox"
-};
 var PxGradientSpreadMethod = {
   pad: "pad",
   reflect: "reflect",
@@ -1184,8 +1485,18 @@ function isPxElementFileFormat(fileJson) {
 function getAnimatorConfig(doc) {
   var _a2;
   const cfg = (doc == null ? void 0 : doc.animator) || ((_a2 = doc == null ? void 0 : doc.meta) == null ? void 0 : _a2.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 ? __spreadValues2({}, 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;
@@ -1211,7 +1522,7 @@ function flattenAnimatorTimeline(cfg) {
     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;
@@ -1254,14 +1565,13 @@ var PxKeyframeValueSchema = implementsInterface()(px.union([
   // 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, {})
@@ -1301,7 +1611,7 @@ var PxPropertyAnimationSchema = implementsInterface()(px.object({
   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(),
@@ -1325,17 +1635,17 @@ var PxElementAnimationSchema = implementsInterface()(px.union([
   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(),
@@ -1352,9 +1662,15 @@ var PxDefsSchema = implementsInterface()(px.object({
   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({
@@ -1362,21 +1678,21 @@ var PxScrollRangeSchema = px.object({
   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();
@@ -1391,8 +1707,8 @@ var PxTimeTimelineSchema = implementsInterface()(px.object({
   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
@@ -1403,8 +1719,8 @@ var scrollishTimelineShape = {
   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(),
@@ -1493,7 +1809,7 @@ var PxMaskedByEffectSchema = implementsInterface()(px.object({
   height: px.number().optional()
 }));
 var PxClipPathEffectSchema = implementsInterface()(px.object({
-  d: PxAnimatableStringSchema.optional()
+  pathData: PxAnimatableStringSchema.optional()
 }));
 var PxStrokeTrimEffectSchema = implementsInterface()(px.object({
   offset: PxAnimatableNumberSchema.optional(),
@@ -1530,7 +1846,7 @@ var PxFillGradientEffectSchema = implementsInterface()(px.object({
   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()
 }));
@@ -1576,11 +1892,71 @@ function validateNodeEffects(root, opts) {
   walk(root, "root");
   return warnings;
 }
-function validateDocument(doc) {
-  const ctx = { errors: [], warnings: [], strict: true };
+function validateGlyphFontRefs(root, fonts) {
+  if (!fonts || !Object.keys(fonts).length) return [];
+  const problems = [];
+  const walk = (node, path, inherited, inGlyphText) => {
+    var _a2, _b;
+    if (!node) return;
+    const own = typeof node.fontFamily === "string" ? node.fontFamily : void 0;
+    const family = own != null ? own : inherited;
+    const isGlyphText = inGlyphText || node.type === "text" && !!((_b = (_a2 = node.effects) == null ? void 0 : _a2.text) == null ? void 0 : _b.useGlyphs);
+    if (isGlyphText && own && !Object.prototype.hasOwnProperty.call(fonts, own)) {
+      const problem = path + ': glyph-mode text uses font-family "' + own + '", which has no entry in animator.definitions.fonts';
+      if (!problems.includes(problem)) problems.push(problem);
+    }
+    if (Array.isArray(node.children)) {
+      node.children.forEach((c, i) => walk(c, path + ".children[" + i + "]", family, isGlyphText));
+    }
+  };
+  walk(root, "root", void 0, false);
+  return problems;
+}
+function validateEasingRefs(root, easings) {
+  const problems = [];
+  const walk = (node, path) => {
+    if (Array.isArray(node)) {
+      node.forEach((item, i) => walk(item, path + "[" + i + "]"));
+      return;
+    }
+    if (!node || typeof node !== "object") return;
+    const easing = node.easing;
+    if (typeof easing === "string" && !(easings && Object.prototype.hasOwnProperty.call(easings, easing))) {
+      const problem = path + '.easing: "' + easing + '" names no entry in animator.definitions.easings \u2014 it will play linear';
+      if (!problems.includes(problem)) problems.push(problem);
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "easing") continue;
+      if (value && typeof value === "object") walk(value, path + "." + key);
+    }
+  };
+  walk(root, "root");
+  return problems;
+}
+function validateVersionStamp(doc) {
+  var _a2;
+  const version = (_a2 = getAnimatorConfig(doc)) == null ? void 0 : _a2.version;
+  if (version === void 0) return [];
+  if (parseWireVersion(version) !== void 0) return [];
+  return ["root.animator.version: " + JSON.stringify(version) + ' is not a version stamp ("a.b" or "a.b.c") \u2014 it reads as unstamped'];
+}
+function validateDocument(doc, opts) {
+  var _a2;
+  const strict = (opts == null ? void 0 : opts.strict) !== false;
+  const ctx = { errors: [], warnings: [], strict };
   const problems = PxAnimatedSvgDocumentSchema.isValid(doc, ctx, ["root"]) ? [] : [...ctx.errors];
   if (doc && typeof doc === "object") {
-    for (const w of validateNodeEffects(doc, { strict: true })) {
+    for (const w of validateNodeEffects(doc, { strict })) {
+      if (!problems.includes(w)) problems.push(w);
+    }
+    const defs = (_a2 = getAnimatorConfig(doc)) == null ? void 0 : _a2.definitions;
+    for (const w of validateGlyphFontRefs(doc, defs == null ? void 0 : defs.fonts)) {
+      if (!problems.includes(w)) problems.push(w);
+    }
+    for (const w of validateEasingRefs(doc, defs == null ? void 0 : defs.easings)) {
+      if (!problems.includes(w)) problems.push(w);
+    }
+    for (const w of validateVersionStamp(doc)) {
       if (!problems.includes(w)) problems.push(w);
     }
   }
@@ -1603,10 +1979,13 @@ var PxNodeBase = px.openObject({
   // 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
@@ -1638,8 +2017,8 @@ var PxBezierPathSchema = implementsInterface()(px.object({
   c: px.boolean().optional()
 }));
 function isPxElementFileFormatDeep(fileJson) {
-  const valid = PxAnimatedSvgDocumentSchema.isValid(fileJson);
-  return { valid, errors: valid ? [] : ["Document failed schema validation"] };
+  const errors = validateDocument(fileJson, { strict: false });
+  return { valid: errors.length === 0, errors };
 }
 var _idCounter = 0;
 function generateUniqueId() {
@@ -1794,7 +2173,7 @@ function isDangerousAttrName(nameLower) {
   if (nameLower.startsWith("on")) return true;
   return false;
 }
-function sanitiseAttributeValue(name, value) {
+function sanitizeAttributeValue(name, value) {
   const nameLower = name.toLowerCase();
   if (isDangerousAttrName(nameLower)) {
     console.warn("Attribute blocked (event handler / dangerous): ", nameLower);
@@ -1833,7 +2212,7 @@ function getNormalizedProps(props) {
     if (INTERNAL_ATTRS.has(key)) continue;
     if (key === "style") continue;
     let value = props[rawKey];
-    if (COLOUR_ATTR_NAMES.has(key) && Array.isArray(value)) {
+    if (COLOR_ATTR_NAMES.has(key) && Array.isArray(value)) {
       propsCopy[key] = toRGBA(value);
     } else if (key === "transform" && value !== null && typeof value === "object" && !Array.isArray(value) && !value.keyframes) {
       const parts = value.value && typeof value.value === "object" ? value.value : value;
@@ -1933,7 +2312,7 @@ function tFromArcFraction(lut, arcFrac) {
 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 _a2, _b, _c;
   if (!propAnimIsMotionPath(anim)) return anim;
   const kfs = anim.keyframes;
@@ -1965,7 +2344,7 @@ function materialiseMotionPathInPropAnim(anim, opts) {
     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;
@@ -2079,7 +2458,7 @@ function insertSharpCornerStepKfIfNeeded(out, prevKf, nextKf, prevPos, nextPos,
   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);
@@ -2202,16 +2581,16 @@ function perpDist(q, pA, pB) {
   const cross = (q[0] - pA[0]) * dy - (q[1] - pA[1]) * dx;
   return Math.abs(cross) / Math.sqrt(len2);
 }
-function materialiseMotionPathsInTree(root, opts) {
-  const out = walkAndMaterialise(root, opts);
+function materializeMotionPathsInTree(root, opts) {
+  const out = walkAndMaterialize(root, opts);
   return out != null ? out : root;
 }
-function walkAndMaterialise(node, opts) {
+function walkAndMaterialize(node, opts) {
   let newChildren;
   if (node.children) {
     for (let i = 0; i < node.children.length; i++) {
       const ch = node.children[i];
-      const ret = walkAndMaterialise(ch, opts);
+      const ret = walkAndMaterialize(ch, opts);
       if (ret !== null) {
         if (!newChildren) newChildren = node.children.slice();
         newChildren[i] = ret;
@@ -2224,9 +2603,9 @@ function walkAndMaterialise(node, opts) {
     const animDef = animBucket;
     const transformAnim = animDef.transform;
     if (transformAnim && typeof transformAnim === "object" && propAnimIsMotionPath(transformAnim)) {
-      const materialised = materialiseMotionPathInPropAnim(transformAnim, opts);
-      if (materialised !== transformAnim) {
-        newAnimate = __spreadProps2(__spreadValues2({}, animDef), { transform: materialised });
+      const materialized = materializeMotionPathInPropAnim(transformAnim, opts);
+      if (materialized !== transformAnim) {
+        newAnimate = __spreadProps2(__spreadValues2({}, animDef), { transform: materialized });
       }
     }
   }
@@ -2327,8 +2706,8 @@ function isPathString(value) {
   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) {
@@ -2412,7 +2791,7 @@ function interpolateValue(propName, a, b, t) {
     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)) {
@@ -2634,7 +3013,7 @@ function normalizeKeyframes(propName, propAnim, duration, defs) {
       value = normalizePathValue(value);
     }
     const propNameKebab = isCamelCaseWord(propName) ? camelCaseToKebabWordIfNeeded(propName) : propName;
-    if (COLOUR_ATTR_NAMES.has(propNameKebab)) {
+    if (COLOR_ATTR_NAMES.has(propNameKebab)) {
       value = (_a2 = parseColor(value)) != null ? _a2 : value;
     }
     const normKf = {
@@ -2668,20 +3047,20 @@ function mergeAnimationDefinitions(animations) {
   }
   return merged;
 }
-function materialiseInternalLoopsInPropAnim(propName, propAnim, duration) {
+function materializeInternalLoopsInPropAnim(propName, propAnim, duration) {
   const loopRaw = propAnim.loop;
   if (loopRaw === void 0 || loopRaw === null || loopRaw === false) return propAnim;
   const loop = loopRaw === true ? {} : loopRaw;
   const rawKfs = propAnim.keyframes;
   if (!Array.isArray(rawKfs) || rawKfs.length < 2) return propAnim;
   const propNameKebab = isCamelCaseWord(propName) ? camelCaseToKebabWordIfNeeded(propName) : propName;
-  const isColour = COLOUR_ATTR_NAMES.has(propNameKebab);
+  const isColor = COLOR_ATTR_NAMES.has(propNameKebab);
   const kfs = rawKfs.map((kf) => {
     var _a2;
     const t = kfTime(kf);
     let v = kfValue(kf);
     if (propName === "d") v = normalizePathValue(v);
-    if (isColour) v = (_a2 = parseColor(v)) != null ? _a2 : v;
+    if (isColor) v = (_a2 = parseColor(v)) != null ? _a2 : v;
     const e = kfEasing(kf);
     const out2 = { t, v, e };
     const tIn = kfTangentIn(kf);
@@ -2695,15 +3074,15 @@ function materialiseInternalLoopsInPropAnim(propName, propAnim, duration) {
   if (propAnim.autoOrient !== void 0) out.autoOrient = propAnim.autoOrient;
   return out;
 }
-function materialiseInternalLoopsInTree(root, duration) {
-  const ret = walkAndMaterialiseLoops(root, duration);
+function materializeInternalLoopsInTree(root, duration) {
+  const ret = walkAndMaterializeLoops(root, duration);
   return ret != null ? ret : root;
 }
-function walkAndMaterialiseLoops(node, duration) {
+function walkAndMaterializeLoops(node, duration) {
   let newChildren;
   if (node.children) {
     for (let i = 0; i < node.children.length; i++) {
-      const ret = walkAndMaterialiseLoops(node.children[i], duration);
+      const ret = walkAndMaterializeLoops(node.children[i], duration);
       if (ret !== null) {
         if (!newChildren) newChildren = node.children.slice();
         newChildren[i] = ret;
@@ -2716,10 +3095,10 @@ function walkAndMaterialiseLoops(node, duration) {
     const animDef = animBucket;
     for (const propName of Object.keys(animDef)) {
       const propAnim = animDef[propName];
-      const materialised = materialiseInternalLoopsInPropAnim(propName, propAnim, duration);
-      if (materialised !== propAnim) {
+      const materialized = materializeInternalLoopsInPropAnim(propName, propAnim, duration);
+      if (materialized !== propAnim) {
         if (!newAnimate) newAnimate = __spreadValues2({}, animDef);
-        newAnimate[propName] = materialised;
+        newAnimate[propName] = materialized;
       }
     }
   }
@@ -2774,12 +3153,12 @@ function normalizeAnimationDefinition(animDef, duration, defs, engine = PxTimeli
       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;
@@ -2870,7 +3249,7 @@ function calcPropertyValue(propName, propAnim, progress) {
       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],
@@ -3028,7 +3407,7 @@ function applyUseOffsetToG(gNode) {
   }
   return gNode;
 }
-function materialiseAnimatedUseInstances(root) {
+function materializeAnimatedUseInstances(root) {
   var _a2;
   const idMap = buildIdMap(root);
   const animatedIds = computeAnimatedSubtreeIds(root, idMap);
@@ -3037,7 +3416,7 @@ function materialiseAnimatedUseInstances(root) {
   const genId3 = () => "_lw_use_mat_" + ++idCounter;
   const rootViewport = readRootViewport(root);
   const defsCollector = [];
-  const walked = walkAndMaterialise2(root, idMap, animatedIds, genId3, defsCollector, rootViewport);
+  const walked = walkAndMaterialize2(root, idMap, animatedIds, genId3, defsCollector, rootViewport);
   if (defsCollector.length === 0) return walked;
   const defsNode = { type: "defs", children: defsCollector };
   const newChildren = [...(_a2 = walked.children) != null ? _a2 : [], defsNode];
@@ -3110,7 +3489,7 @@ function stripHash(href) {
   if (typeof href !== "string") return void 0;
   return href.startsWith("#") ? href.slice(1) : href;
 }
-function materialiseOneUse(useNode, target, idMap, animatedIds, genId3, defsCollector, rootViewport) {
+function materializeOneUse(useNode, target, idMap, animatedIds, genId3, defsCollector, rootViewport) {
   var _a2, _b, _c, _d;
   const clone2 = deepClonePxNode(target);
   regenerateIdsAndRewriteRefs(clone2, genId3);
@@ -3118,8 +3497,8 @@ function materialiseOneUse(useNode, target, idMap, animatedIds, genId3, defsColl
   const useW = (_b = (_a2 = numericAttr(useNode.width)) != null ? _a2 : symbolViewBox == null ? void 0 : symbolViewBox[2]) != null ? _b : rootViewport[0];
   const useH = (_d = (_c = numericAttr(useNode.height)) != null ? _c : symbolViewBox == null ? void 0 : symbolViewBox[3]) != null ? _d : rootViewport[1];
   const rewrittenClone = clone2.type === "symbol" ? rewriteSymbolRootToGroup(clone2, genId3, defsCollector, useW, useH) : clone2;
-  const materialisedClone = walkAndMaterialise2(rewrittenClone, idMap, animatedIds, genId3, defsCollector, rootViewport);
-  const newNode = __spreadProps2(__spreadValues2({}, useNode), { type: "g", children: [materialisedClone] });
+  const materializedClone = walkAndMaterialize2(rewrittenClone, idMap, animatedIds, genId3, defsCollector, rootViewport);
+  const newNode = __spreadProps2(__spreadValues2({}, useNode), { type: "g", children: [materializedClone] });
   delete newNode.href;
   delete newNode.width;
   delete newNode.height;
@@ -3157,18 +3536,18 @@ function parseViewBox(v) {
   if (parts.length < 4 || parts.some((n) => !Number.isFinite(n))) return void 0;
   return [parts[0], parts[1], parts[2], parts[3]];
 }
-function walkAndMaterialise2(node, idMap, animatedIds, genId3, defsCollector, rootViewport) {
+function walkAndMaterialize2(node, idMap, animatedIds, genId3, defsCollector, rootViewport) {
   if (node.type === "use" && typeof node.href === "string") {
     const targetId = stripHash(node.href);
     if (targetId && animatedIds.has(targetId)) {
       const target = idMap.get(targetId);
-      if (target) return materialiseOneUse(node, target, idMap, animatedIds, genId3, defsCollector, rootViewport);
+      if (target) return materializeOneUse(node, target, idMap, animatedIds, genId3, defsCollector, rootViewport);
     }
   }
   if (!node.children) return node;
   let changed = false;
   const newChildren = node.children.map((ch) => {
-    const m = walkAndMaterialise2(ch, idMap, animatedIds, genId3, defsCollector, rootViewport);
+    const m = walkAndMaterialize2(ch, idMap, animatedIds, genId3, defsCollector, rootViewport);
     if (m !== ch) changed = true;
     return m;
   });
@@ -3194,7 +3573,7 @@ function readAnimatable(raw) {
     const obj = raw;
     const kfs = obj.keyframes;
     if (kfs) {
-      const out = { kind: "animated", keyframes: kfs.map(normaliseKeyframe), autoOrient: obj.autoOrient, loop: obj.loop };
+      const out = { kind: "animated", keyframes: kfs.map(normalizeKeyframe), autoOrient: obj.autoOrient, loop: obj.loop };
       const base = (_a2 = obj.value) != null ? _a2 : obj.v;
       if (base !== void 0 && out.kind === "animated") out.base = base;
       return out;
@@ -3222,7 +3601,7 @@ function writeAnimatableChannel(node, attrName, read, opts) {
   const baseline = (_d = (_b = read.base) != null ? _b : (_a2 = read.keyframes[0]) == null ? void 0 : _a2.value) != null ? _d : (_c = read.keyframes[0]) == null ? void 0 : _c.v;
   if (baseline !== void 0) node[attrName] = toOut(baseline);
 }
-function normaliseKeyframe(kf) {
+function normalizeKeyframe(kf) {
   if (!kf || typeof kf !== "object") return kf;
   const k = kf;
   if (k.t === void 0 && k.v === void 0 && k.e === void 0 && k.to === void 0 && k.ti === void 0) {
@@ -3724,10 +4103,10 @@ function formatOffset(o) {
   return pct + "%";
 }
 function applyClipPathEffect(node, fx, ctx) {
-  if (!(fx == null ? void 0 : fx.d)) return node;
+  if (!(fx == null ? void 0 : fx.pathData)) return node;
   const clipId = genId(ctx, "clip");
   const pathChild = { type: "path" };
-  const read = readAnimatable(fx.d);
+  const read = readAnimatable(fx.pathData);
   if (read.kind !== "absent") {
     if (read.kind === "static") {
       pathChild.d = pathString(read.value);
@@ -3742,7 +4121,7 @@ function applyClipPathEffect(node, fx, ctx) {
 }
 function pathString(v) {
   if (typeof v === "string") return v;
-  if (v && typeof v === "object" && typeof v.path === "string") return v.path;
+  if (v && typeof v === "object" && typeof v.pathData === "string") return v.pathData;
   return void 0;
 }
 function applyMaskedByEffect(node, fx, transformBy, ctx) {
@@ -3787,8 +4166,8 @@ function wrapInverseTransform(inner, fx, ctx) {
 }
 function wrapInversePart(inner, part, raw, origin, ctx) {
   if (raw === void 0) return inner;
-  const normalisedRaw = part === "scale" && Array.isArray(raw) ? [raw[0] / 100, raw[1] / 100] : raw;
-  const v = readAnimatable(normalisedRaw);
+  const normalizedRaw = part === "scale" && Array.isArray(raw) ? [raw[0] / 100, raw[1] / 100] : raw;
+  const v = readAnimatable(normalizedRaw);
   if (v.kind === "static") {
     return { type: "g", transform: { value: partsRecord(part, invertPartValue(part, v.value), origin) }, children: [inner] };
   }
@@ -4183,7 +4562,7 @@ function synthesiseScale(raw, i) {
   const scalePower = (v) => [Math.pow(v[0], i), Math.pow(v[1], i)];
   return mapAnimatable(raw, scalePower, true);
 }
-var RETIME_MATERIALISATION_MODE_INLINE_G = false;
+var RETIME_MATERIALIZATION_MODE_INLINE_G = false;
 function asRetime(r) {
   var _a2, _b;
   return { start: (_a2 = r.start) != null ? _a2 : 0, stretch: (_b = r.stretch) != null ? _b : 1 };
@@ -4268,11 +4647,11 @@ function applyAllRetimeEffects(root, ctx) {
     if (!retime) continue;
     const crop = retime.timeCrop;
     clearCloneRetime(useNode);
-    materialiseRetime(useNode, asRetime(retime), ctx);
+    materializeRetime(useNode, asRetime(retime), ctx);
     if (crop) applyTimeCrop(useNode, crop, ctx);
   }
 }
-function materialiseRetime(useNode, retime, ctx) {
+function materializeRetime(useNode, retime, ctx) {
   const targetId = stripHash2(useNode.href);
   if (!targetId) {
     ctx.errors.push("retime: <use> has no href to follow");
@@ -4280,7 +4659,7 @@ function materialiseRetime(useNode, retime, ctx) {
   }
   const chainRootId = buildChainClone(targetId, retime, ctx, /* @__PURE__ */ new Set());
   if (!chainRootId) return;
-  if (RETIME_MATERIALISATION_MODE_INLINE_G) {
+  if (RETIME_MATERIALIZATION_MODE_INLINE_G) {
     const cloneNode = ctx.idMap.get(chainRootId);
     useNode.type = "g";
     delete useNode.href;
@@ -4320,13 +4699,13 @@ function buildChainClone(targetId, accum, ctx, chain) {
       if (subId2) cloneNode.href = "#" + subId2;
     }
   } else {
-    materialiseNestedRetimeUses(cloneNode, accum, ctx, chain, targetId);
+    materializeNestedRetimeUses(cloneNode, accum, ctx, chain, targetId);
   }
   ctx.defs.push(cloneNode);
   if (typeof cloneNode.id === "string") ctx.idMap.set(cloneNode.id, cloneNode);
   return typeof cloneNode.id === "string" ? cloneNode.id : void 0;
 }
-function materialiseNestedRetimeUses(node, accum, ctx, chain, parentTargetId) {
+function materializeNestedRetimeUses(node, accum, ctx, chain, parentTargetId) {
   const visit = (n) => {
     var _a2;
     const retime = readCloneRetime(n);
@@ -4523,10 +4902,10 @@ function numRange(v) {
 function estimateTextAdvance(node) {
   let chars = 0, maxFont = 16;
   const walk = (el) => {
-    var _a2, _b;
+    var _a2;
     const fs = parseFloat(String((_a2 = el.fontSize) != null ? _a2 : "")) || 0;
     if (fs) maxFont = Math.max(maxFont, fs);
-    const t = (_b = el.text) != null ? _b : el.textContent;
+    const t = el.textContent;
     if (typeof t === "string") chars += t.length;
     if (el.children) for (const c of el.children) walk(c);
   };
@@ -4675,7 +5054,6 @@ var TEXT_ATTR_KEYS = [
   "stroke",
   "strokeWidth",
   "effects",
-  TEXT_ATTR,
   TEXT_CONTENT_ATTR,
   "xml:space"
 ];
@@ -4785,8 +5163,8 @@ function missingGlyphBoxEm(advanceEm, ascentEm) {
   const ix0 = x0 + t, ix1 = x1 - t, iyb = -t, iyt = y1 + t;
   return outer + "M" + ix0 + " " + iyb + "L" + ix0 + " " + iyt + "L" + ix1 + " " + iyt + "L" + ix1 + " " + iyb + "Z";
 }
-function materialiseGlyphTextHorizontal(node, opts) {
-  var _a2, _b, _c, _d;
+function materializeGlyphTextHorizontal(node, opts) {
+  var _a2, _b, _c;
   const { glyphs, create = jsonElementFactory, warnings } = opts;
   const soleFont = soleFontOf(glyphs);
   const pen = { x: (_a2 = parseLen(node.x)) != null ? _a2 : 0, y: (_b = parseLen(node.y)) != null ? _b : 0 };
@@ -4803,8 +5181,8 @@ function materialiseGlyphTextHorizontal(node, opts) {
     for (let i = 0; i < content.length; i++) {
       const ch = content.charAt(i);
       const g = gf == null ? void 0 : gf.glyphs[ch];
-      if (g && g.d) {
-        placements.push({ glyphD: g.d, m: [scale, 0, 0, scale, pen.x, pen.y], paint, line, x: pen.x, y: pen.y, scale });
+      if (g && g.pathData) {
+        placements.push({ glyphD: g.pathData, m: [scale, 0, 0, scale, pen.x, pen.y], paint, line, x: pen.x, y: pen.y, scale });
         pen.x += g.width * scale;
       } else if (/\S/.test(ch)) {
         const advEm = g && g.width > 0 ? g.width : MISSING_GLYPH_ADVANCE_EM * upm;
@@ -4818,7 +5196,7 @@ function materialiseGlyphTextHorizontal(node, opts) {
     }
   };
   const walk = (el, parentStyle) => {
-    var _a3, _b2, _c2, _d2;
+    var _a3, _b2, _c2;
     const s = resolveStyle2(el, parentStyle);
     const x = parseLen(el.x);
     const y = parseLen(el.y);
@@ -4830,14 +5208,14 @@ function materialiseGlyphTextHorizontal(node, opts) {
     if (y !== void 0) pen.y = y;
     pen.x += (_a3 = parseLen(el.dx)) != null ? _a3 : 0;
     pen.y += (_b2 = parseLen(el.dy)) != null ? _b2 : 0;
-    const content = (_c2 = str(el[TEXT_CONTENT_ATTR])) != null ? _c2 : str(el[TEXT_ATTR]);
-    if (content && !((_d2 = el.children) == null ? void 0 : _d2.length)) renderChars(content, s);
+    const content = str(el[TEXT_CONTENT_ATTR]);
+    if (content && !((_c2 = el.children) == null ? void 0 : _c2.length)) renderChars(content, s);
     if (el.children) for (const ch of el.children) walk(ch, s);
   };
   const rootStyle = rootStyleOf(node);
   if (node.children) for (const ch of node.children) walk(ch, rootStyle);
-  const rootContent = (_c = str(node[TEXT_CONTENT_ATTR])) != null ? _c : str(node[TEXT_ATTR]);
-  if (rootContent && !((_d = node.children) == null ? void 0 : _d.length)) renderChars(rootContent, rootStyle);
+  const rootContent = str(node[TEXT_CONTENT_ATTR]);
+  if (rootContent && !((_c = node.children) == null ? void 0 : _c.length)) renderChars(rootContent, rootStyle);
   const anchor = str(node.textAnchor);
   if (anchor === "middle" || anchor === "end") {
     for (const p of placements) {
@@ -4849,7 +5227,7 @@ function materialiseGlyphTextHorizontal(node, opts) {
   return toGroup(node, buildPaths(placements, create, warnings), create);
 }
 function layoutGlyphTextChars(node, opts) {
-  var _a2, _b, _c, _d, _e, _f;
+  var _a2, _b, _c, _d, _e;
   if ((_a2 = opts.alongPath) == null ? void 0 : _a2.pathD) return layoutGlyphTextCharsAlongPath(node, opts.alongPath.pathD, opts);
   const { glyphs, warnings } = opts;
   const soleFont = soleFontOf(glyphs);
@@ -4873,7 +5251,7 @@ function layoutGlyphTextChars(node, opts) {
     }
   };
   const walk = (el, parentStyle) => {
-    var _a3, _b2, _c2, _d2;
+    var _a3, _b2, _c2;
     const s = resolveStyle2(el, parentStyle);
     const x = parseLen(el.x);
     const y = parseLen(el.y);
@@ -4885,8 +5263,8 @@ function layoutGlyphTextChars(node, opts) {
     if (y !== void 0) pen.y = y;
     pen.x += (_a3 = parseLen(el.dx)) != null ? _a3 : 0;
     pen.y += (_b2 = parseLen(el.dy)) != null ? _b2 : 0;
-    const content = (_c2 = str(el[TEXT_CONTENT_ATTR])) != null ? _c2 : str(el[TEXT_ATTR]);
-    if (content && !((_d2 = el.children) == null ? void 0 : _d2.length)) renderChars(content, s);
+    const content = str(el[TEXT_CONTENT_ATTR]);
+    if (content && !((_c2 = el.children) == null ? void 0 : _c2.length)) renderChars(content, s);
     if (el.children) for (const ch of el.children) walk(ch, s);
   };
   const rootStyle = rootStyleOf(node);
@@ -4900,8 +5278,8 @@ function layoutGlyphTextChars(node, opts) {
       boxes.push({ x: pen.x, y: pen.y, width: 0, ascent: ((_d = gf == null ? void 0 : gf.ascent) != null ? _d : 0.9 * upm) * (s.fontSize / upm), fontSize: s.fontSize, line });
     }
   }
-  const rootContent = (_e = str(node[TEXT_CONTENT_ATTR])) != null ? _e : str(node[TEXT_ATTR]);
-  if (rootContent && !((_f = node.children) == null ? void 0 : _f.length)) renderChars(rootContent, rootStyle);
+  const rootContent = str(node[TEXT_CONTENT_ATTR]);
+  if (rootContent && !((_e = node.children) == null ? void 0 : _e.length)) renderChars(rootContent, rootStyle);
   const anchor = str(node.textAnchor);
   if (anchor === "middle" || anchor === "end") {
     for (const b of boxes) {
@@ -4909,8 +5287,8 @@ function layoutGlyphTextChars(node, opts) {
       b.x += anchor === "middle" ? -w / 2 : -w;
     }
   }
-  return boxes.map((_g) => {
-    var _h = _g, { line: _l } = _h, b = __objRest2(_h, ["line"]);
+  return boxes.map((_f) => {
+    var _g = _f, { line: _l } = _g, b = __objRest2(_g, ["line"]);
     return b;
   });
 }
@@ -4926,14 +5304,14 @@ function layoutGlyphTextCharsAlongPath(node, pathD, opts) {
   const chars = [];
   let adv = 0;
   const walk = (el, parentStyle) => {
-    var _a3, _b2, _c;
+    var _a3, _b2;
     const s = resolveStyle2(el, parentStyle);
-    const content = (_a3 = str(el[TEXT_CONTENT_ATTR])) != null ? _a3 : str(el[TEXT_ATTR]);
-    if (content && !((_b2 = el.children) == null ? void 0 : _b2.length)) {
+    const content = str(el[TEXT_CONTENT_ATTR]);
+    if (content && !((_a3 = el.children) == null ? void 0 : _a3.length)) {
       const gf = glyphFontFor(s, glyphs, soleFont, warnings);
       const upm = (gf == null ? void 0 : gf.unitsPerEm) || 1e3;
       const scale = s.fontSize / upm;
-      const ascent = ((_c = gf == null ? void 0 : gf.ascent) != null ? _c : 0.9 * upm) * scale;
+      const ascent = ((_b2 = gf == null ? void 0 : gf.ascent) != null ? _b2 : 0.9 * upm) * scale;
       for (let i = 0; i < content.length; i++) {
         const ch = content.charAt(i);
         const g = gf == null ? void 0 : gf.glyphs[ch];
@@ -4980,21 +5358,21 @@ function collectAlongPathCells(node, glyphs, soleFont, warnings) {
   const cells = [];
   let adv = 0;
   const walk = (el, parentStyle) => {
-    var _a2, _b, _c;
+    var _a2, _b;
     const s = resolveStyle2(el, parentStyle);
-    const content = (_a2 = str(el[TEXT_CONTENT_ATTR])) != null ? _a2 : str(el[TEXT_ATTR]);
-    if (content && !((_b = el.children) == null ? void 0 : _b.length)) {
+    const content = str(el[TEXT_CONTENT_ATTR]);
+    if (content && !((_a2 = el.children) == null ? void 0 : _a2.length)) {
       const gf = glyphFontFor(s, glyphs, soleFont, warnings);
       if (gf) {
         const scale = s.fontSize / gf.unitsPerEm;
-        const ascentEm = (_c = gf.ascent) != null ? _c : 0.9 * gf.unitsPerEm;
+        const ascentEm = (_b = gf.ascent) != null ? _b : 0.9 * gf.unitsPerEm;
         const paint = paintOf(s);
         for (let i = 0; i < content.length; i++) {
           const ch = content.charAt(i);
           const g = gf.glyphs[ch];
-          if (g && g.d) {
+          if (g && g.pathData) {
             const glyphAdv = g.width * scale;
-            cells.push({ glyphD: g.d, widthEm: g.width, scale, paint, midBase: adv + glyphAdv / 2 });
+            cells.push({ glyphD: g.pathData, widthEm: g.width, scale, paint, midBase: adv + glyphAdv / 2 });
             adv += glyphAdv;
           } else if (/\S/.test(ch)) {
             const wEm = g && g.width > 0 ? g.width : MISSING_GLYPH_ADVANCE_EM * gf.unitsPerEm;
@@ -5025,7 +5403,7 @@ function alongPathNodeOffsets(node) {
     perp: (_c = parseLen(node.dy)) != null ? _c : 0
   };
 }
-function materialiseGlyphTextAlongPath(node, pathD, startOffset, opts, textLength, pathOverflow) {
+function materializeGlyphTextAlongPath(node, pathD, startOffset, opts, textLength, pathOverflow) {
   const { glyphs, create = jsonElementFactory, warnings } = opts;
   const sampler = pathD ? createPathSampler(pathD) : null;
   if (!sampler) {
@@ -5104,8 +5482,8 @@ function buildAnimatedAlongPath(cells, sampler, distOf, times, loop, create, isC
   const onPath = (dist) => dist >= 0 && dist <= sampler.totalLength;
   const out = [];
   for (const c of cells) {
-    const centred = [c.scale, 0, 0, c.scale, -c.scale * (c.widthEm / 2), 0];
-    const d = transformPathData(c.glyphD, centred);
+    const centered = [c.scale, 0, 0, c.scale, -c.scale * (c.widthEm / 2), 0];
+    const d = transformPathData(c.glyphD, centered);
     const sampleKf = (dist, time) => {
       const { x, y, angle } = sampler.sampleAtDistance(dist);
       const cos = Math.cos(angle), sin = Math.sin(angle);
@@ -5203,9 +5581,9 @@ function toGroup(node, children, create) {
   }
   return create("g", gProps, children);
 }
-function materialiseGlyphText(node, opts) {
-  if (opts.alongPath) return materialiseGlyphTextAlongPath(node, opts.alongPath.pathD, opts.alongPath.startOffset, opts, opts.alongPath.textLength, opts.alongPath.pathOverflow);
-  return materialiseGlyphTextHorizontal(node, opts);
+function materializeGlyphText(node, opts) {
+  if (opts.alongPath) return materializeGlyphTextAlongPath(node, opts.alongPath.pathD, opts.alongPath.startOffset, opts, opts.alongPath.textLength, opts.alongPath.pathOverflow);
+  return materializeGlyphTextHorizontal(node, opts);
 }
 function applyTextGlyphsEffect(node, fx, ctx) {
   if (!(fx == null ? void 0 : fx.useGlyphs)) return node;
@@ -5213,14 +5591,14 @@ function applyTextGlyphsEffect(node, fx, ctx) {
     ctx.warnings.push("textGlyphs: no definitions.fonts \u2014 left as native <text>");
     return node;
   }
-  return materialiseGlyphTextHorizontal(node, { glyphs: ctx.glyphs, warnings: ctx.warnings });
+  return materializeGlyphTextHorizontal(node, { glyphs: ctx.glyphs, warnings: ctx.warnings });
 }
 function applyTextGlyphsAlongPath(node, ctx, pathD, startOffset, textLength, pathOverflow) {
   if (!ctx.glyphs) {
     ctx.warnings.push("textGlyphs: no definitions.fonts");
     return null;
   }
-  return materialiseGlyphTextAlongPath(node, pathD, startOffset, { glyphs: ctx.glyphs, warnings: ctx.warnings }, textLength, pathOverflow);
+  return materializeGlyphTextAlongPath(node, pathD, startOffset, { glyphs: ctx.glyphs, warnings: ctx.warnings }, textLength, pathOverflow);
 }
 function applyStrokeTrimEffect(node, strokeTrim, ctx) {
   if (!strokeTrim) return node;
@@ -5682,7 +6060,7 @@ function buildOffsetPath(propAnim) {
   }
   return { pathStr: d, distanceKfs, autoOrient: !!propAnim.autoOrient, anchor };
 }
-function materialiseOffsetPathsInTree(root) {
+function materializeOffsetPathsInTree(root) {
   const walk = (node) => {
     var _a2;
     let out = node;
@@ -5725,15 +6103,15 @@ function materialiseOffsetPathsInTree(root) {
   };
   return walk(root);
 }
-function materialiseAllInTree(doc, engine, opts) {
+function materializeAllInTree(doc, engine, opts) {
   var _a2, _b;
   let root = applyPlayerEffects(doc).root;
-  root = materialiseOffsetPathsInTree(root);
+  root = materializeOffsetPathsInTree(root);
   const duration = (_b = (_a2 = getAnimatorConfig(root)) == null ? void 0 : _a2.duration) != null ? _b : DEFAULT_DURATION_MS;
-  root = materialiseInternalLoopsInTree(root, duration);
+  root = materializeInternalLoopsInTree(root, duration);
   if (engine === PxTimelineEngine.native) {
-    root = materialiseMotionPathsInTree(root, opts == null ? void 0 : opts.motionPath);
-    root = materialiseAnimatedUseInstances(root);
+    root = materializeMotionPathsInTree(root, opts == null ? void 0 : opts.motionPath);
+    root = materializeAnimatedUseInstances(root);
     root = pruneUnreferencedDefs(root);
   }
   return root;
@@ -5767,6 +6145,38 @@ function pruneUnreferencedDefs(root) {
   }
   return root;
 }
+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;
+}
 function requestFrame(cb) {
   const g = globalThis;
   if (typeof g.requestAnimationFrame === "function") return g.requestAnimationFrame(cb);
@@ -5783,7 +6193,7 @@ function cancelFrame(handle) {
 function createBasicFrameLoopAnimator(doc, adapter, callbacks) {
   var _a2;
   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;
@@ -6013,8 +6423,8 @@ function createBasicFrameLoopAnimator(doc, adapter, callbacks) {
       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();
@@ -6028,13 +6438,16 @@ function createBasicFrameLoopAnimator(doc, adapter, callbacks) {
       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 _a3;
       api.cancel();
@@ -6043,6 +6456,49 @@ function createBasicFrameLoopAnimator(doc, adapter, callbacks) {
   };
   return api;
 }
+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);
+    }
+  };
+}
 var IDENTITY = [1, 0, 0, 1, 0, 0];
 function mul(m, n) {
   return [
@@ -6312,32 +6768,30 @@ function mergeTimeline(base, patch, warn) {
   }
   return merged;
 }
-function foldAnimatorConfigShortcuts(config, shortcuts) {
+function foldTimelineOverride(timeline, shortcuts) {
   let base;
-  if (typeof config === "string") {
+  if (typeof timeline === "string") {
     try {
-      base = JSON.parse(config);
+      base = JSON.parse(timeline);
     } catch (e) {
-      console.warn("animator config: not valid JSON \u2014 ignored", e);
+      console.warn("timeline override: not valid JSON \u2014 ignored", e);
       base = void 0;
     }
   } else {
-    base = config != null ? config : void 0;
+    base = timeline != null ? timeline : void 0;
   }
   const { duration, delay, iterations, startOn } = shortcuts;
   if (duration === void 0 && delay === void 0 && iterations === void 0 && startOn === void 0) {
-    return base;
+    return base === void 0 ? void 0 : { timeline: base };
   }
   const out = isPlainObject(base) ? __spreadValues2({}, base) : {};
-  const timeline = __spreadValues2({}, out.timeline);
-  if (duration !== void 0) timeline.duration = duration;
-  if (delay !== void 0) timeline.delay = delay;
-  if (iterations !== void 0) timeline.iterations = iterations;
+  if (duration !== void 0) out.duration = duration;
+  if (delay !== void 0) out.delay = delay;
+  if (iterations !== void 0) out.iterations = iterations;
   if (startOn !== void 0) {
-    timeline.trigger = __spreadProps2(__spreadValues2({}, timeline.trigger), { startOn });
+    out.trigger = __spreadProps2(__spreadValues2({}, out.trigger), { startOn });
   }
-  out.timeline = timeline;
-  return out;
+  return { timeline: out };
 }
 function mergeAnimatorConfig(base, patch) {
   const warnings = [];
@@ -6403,26 +6857,12 @@ function applyAnimatorConfig(doc, patch, opts) {
   return { doc: __spreadProps2(__spreadValues2({}, anyDoc), { animator: merged.config }), warnings };
 }
 var MAX_REPORTED = 6;
-var LEGACY_FLAT_KEYS = [
-  ...PX_TIMELINE_SHARED_KEYS,
-  ...PX_TIME_ONLY_TIMELINE_KEYS,
-  "fill",
-  "resetOnFinish",
-  "timelineSource",
-  "scroll"
-];
-var isLegacyFlatAnimatorKey = (w) => LEGACY_FLAT_KEYS.some((k) => w.indexOf("animator." + k + ":") >= 0);
 function diagnoseDocument(doc) {
-  let all;
   try {
-    all = validateDocument(doc);
+    return { problems: validateDocument(doc) };
   } catch (e) {
-    return { problems: [], legacy: [] };
+    return { problems: [] };
   }
-  const problems = [];
-  const legacy = [];
-  for (const w of all) (isLegacyFlatAnimatorKey(w) ? legacy : problems).push(w);
-  return { problems, legacy };
 }
 function reportDocumentDiagnostics(doc, where) {
   const { problems } = diagnoseDocument(doc);
@@ -6434,13 +6874,37 @@ function reportDocumentDiagnostics(doc, where) {
   );
 }
 
+// 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 = () => {
@@ -6475,6 +6939,7 @@ function setupAnimationTriggers(api, config) {
         startHandler();
       } else {
         window.addEventListener("load", startHandler, { once: true });
+        cleanups.push(() => window.removeEventListener("load", startHandler));
       }
       break;
     }
@@ -6489,6 +6954,10 @@ function setupAnimationTriggers(api, config) {
       };
       root.addEventListener("mouseenter", mouseOverHandler);
       root.addEventListener("mouseleave", mouseOutHandler);
+      cleanups.push(() => {
+        root.removeEventListener("mouseenter", mouseOverHandler);
+        root.removeEventListener("mouseleave", mouseOutHandler);
+      });
       break;
     }
     case "click": {
@@ -6500,6 +6969,7 @@ function setupAnimationTriggers(api, config) {
         }
       };
       root.addEventListener("click", clickHandler);
+      cleanups.push(() => root.removeEventListener("click", clickHandler));
       break;
     }
     case "scrollIntoView": {
@@ -6531,12 +7001,13 @@ function setupAnimationTriggers(api, config) {
         { threshold: thresholdSteps }
       );
       observer.observe(root);
+      cleanups.push(() => observer.disconnect());
       break;
     }
     case "programmatic":
       break;
   }
-  return api;
+  return dispose;
 }
 
 // src/engines/PxAnimatorFrameLoop.ts
@@ -6544,35 +7015,41 @@ function getSelector(id) {
   return "#" + id;
 }
 function createFrameLoopAnimator(doc, adapter, callbacks, rootElement) {
+  var _a2;
   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, (_a2 = config.trigger) != null ? _a2 : {}, 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;
@@ -6584,7 +7061,7 @@ function createDomAdapter(rootElement) {
       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];
@@ -6609,7 +7086,7 @@ function createCssKf(kf, t, propName, unsupportedSet) {
   };
   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 });
@@ -6696,18 +7173,19 @@ function convertToWebApiKeyframes(animDef, unsupportedSet, config) {
   return result;
 }
 function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsupportedAttrs, scrollTimeline) {
-  var _a2;
+  var _a2, _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;
@@ -6717,18 +7195,18 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
   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;
@@ -6777,14 +7255,14 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
             }
             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 = {
@@ -6828,20 +7306,36 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
       }
     },
     "setPlaybackRate": (rate) => {
+      if (!isValidPlaybackRate(rate)) {
+        diag.warn(PxDiagnosticKind.usage, PX_RATE_REJECTED);
+        return api;
+      }
       animations.forEach((a) => a.playbackRate = rate);
       return api;
     },
     "getCurrentTime": () => {
-      var _a3, _b;
-      const res = (_b = (_a3 = animations[0]) == null ? void 0 : _a3.currentTime) != null ? _b : null;
+      var _a3, _b2;
+      const res = (_b2 = (_a3 = animations[0]) == null ? void 0 : _a3.currentTime) != null ? _b2 : null;
       return res !== null ? +res : null;
     },
     "setCurrentTime": (time) => {
+      var _a3;
+      const ceiling = seekCeilingMs((_a3 = config.duration) != null ? _a3 : 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 _a3;
+      const t = api.getCurrentTime();
+      return t === null ? null : timeToProgress(t, (_a3 = config.duration) != null ? _a3 : 0, iterations != null ? iterations : 1);
+    },
+    "setCurrentProgress": (progress) => {
+      var _a3;
+      api.setCurrentTime(progressToTimeMs(progress, (_a3 = config.duration) != null ? _a3 : 0, iterations != null ? iterations : 1));
+    },
     "destroy": () => {
       var _a3;
       api.cancel();
@@ -6852,12 +7346,15 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
       }
     }
   };
-  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());
@@ -6873,13 +7370,14 @@ function nativeRangeOffset(point, defaultFraction, view) {
   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 _a2, _b, _c, _d;
+  const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
   if (!config || !isScrollTimeline(config)) return null;
   const scroll = config.scroll || {};
   const kind = (_a2 = scroll.kind) != null ? _a2 : "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;
@@ -6890,13 +7388,13 @@ function createNativeScrollTimeline(subject, config) {
   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 {
@@ -6923,8 +7421,9 @@ function documentScroller() {
 }
 var SUBJECT_PARENT = "parent";
 var SUBJECT_SCROLLER = "scroller";
-function resolveScrollSubject(svgRoot, subject) {
+function resolveScrollSubject(svgRoot, subject, diag) {
   var _a2, _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) {
@@ -6942,21 +7441,22 @@ function resolveScrollSubject(svgRoot, subject) {
   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 _a2, _b;
   if (!config || !isScrollTimeline(config)) return null;
+  const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
   const scroll = config.scroll || {};
   const kind = (_a2 = scroll.kind) != null ? _a2 : "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();
@@ -7075,7 +7575,7 @@ function applyScrollPin(svgRoot, scroll) {
   const alignFactor = scroll.pinAlign === "center" ? 0.5 : scroll.pinAlign === "bottom" ? 1 : 0;
   const applyTop = () => {
     var _a2;
-    const extra = (_a2 = scroll.pinTop) != null ? _a2 : 0;
+    const extra = (_a2 = scroll.pinOffset) != null ? _a2 : 0;
     if (!alignFactor) {
       style.top = extra + "px";
       return;
@@ -7137,6 +7637,7 @@ function finaliseAnimator(animatorConfig, callbacks, make) {
 }
 function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
   const animatorConfig = getAnimatorConfig(doc) || {};
+  const diag = createDiagnostics(callbacks, "[PxAnimator]");
   if (isScrollTimeline(animatorConfig)) {
     return finaliseAnimator(animatorConfig, callbacks, (cb) => {
       var _a2;
@@ -7144,7 +7645,7 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
       };
       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,
@@ -7174,7 +7675,8 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
         const driver = createScrollDriver(
           subject,
           animatorConfig,
-          (progress) => api.setCurrentTime(progress * totalMs)
+          (progress) => api.setCurrentTime(progress * totalMs),
+          diag
         );
         if (driver) {
           const destroy = api.destroy.bind(api);
@@ -7185,7 +7687,7 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
           };
         }
       } 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;
     });
@@ -7205,35 +7707,36 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
 
 // src/dom/PxAnimatorDOM.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
-function createElement(tagName, normalisedProps, style, children, textContent) {
+function createElement(tagName, normalizedProps, style, children, textContent, diag) {
   if (DISALLOWED_SVG_TAGS_LOWER.has(tagName.toLowerCase())) {
-    console.warn("SVG tag blocked (dangerous): ", tagName);
+    (diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]")).warn(PxDiagnosticKind.document, "SVG tag blocked (dangerous): " + tagName);
     return null;
   }
   const element = document.createElementNS(SVG_NS, tagName);
-  for (const propName in normalisedProps) {
-    const sanitised = sanitiseAttributeValue(propName, normalisedProps[propName]);
-    if (sanitised === void 0) continue;
+  for (const propName in normalizedProps) {
+    const sanitized = sanitizeAttributeValue(propName, normalizedProps[propName]);
+    if (sanitized === void 0) continue;
     if (CSS_ONLY_STYLE_PROPS.has(propName)) {
-      element.style[propName] = String(sanitised);
+      element.style[propName] = String(sanitized);
       continue;
     }
-    element.setAttribute(camelCaseToKebabWordIfNeeded(propName), sanitised);
+    element.setAttribute(camelCaseToKebabWordIfNeeded(propName), sanitized);
   }
   if (style) {
     for (const styleProp in style) {
       element.style[styleProp] = String(style[styleProp]);
     }
   }
-  if (children) {
+  if (children == null ? void 0 : children.length) {
     for (const child of children) {
       element.appendChild(child);
     }
+  } else if (textContent) {
+    element.textContent = textContent;
   }
-  if (textContent) element.textContent = textContent;
   return element;
 }
-function renderNode(node, defs) {
+function renderNode(node, defs, diag) {
   if (!node) return null;
   const _a2 = node, { type, children, style } = _a2, props = __objRest(_a2, ["type", "children", "style"]);
   const domType = props.domType;
@@ -7243,7 +7746,7 @@ function renderNode(node, defs) {
   let childElements;
   if (children) {
     for (const ch of children) {
-      const child = renderNode(ch, nodeDefs);
+      const child = renderNode(ch, nodeDefs, diag);
       if (child) {
         if (!childElements) childElements = [];
         childElements.push(child);
@@ -7255,37 +7758,39 @@ function renderNode(node, defs) {
     getNormalizedProps(props),
     resolvedStyle,
     childElements,
-    props[TEXT_CONTENT_ATTR] || props[TEXT_ATTR]
+    props[TEXT_CONTENT_ATTR],
+    diag
   );
   if (element && domType !== void 0) element.setAttribute("type", domType);
   return element;
 }
 
 // src/shared/PxAnimatorKeys.ts
-var PX_ANIMATOR_DATA_KEY = "data";
+var PX_ANIMATOR_DOC_KEY = "doc";
 
 // src/animator/PxAnimator.ts
 function createAnimatorFromConfig(doc, adapter, callbacks, rootElement) {
   return bindWithEngineChoice(doc, adapter, callbacks, rootElement);
 }
-function createAnimatorImpl(doc, adapter, callbacks, containerElement, config, resetDocDefaults) {
+function createAnimatorImpl(doc, adapter, callbacks, containerElement, patch, resetTimeline) {
+  const diag = createDiagnostics(callbacks, "[PxAnimator]");
   const effectsWarnings = validateNodeEffects(doc);
-  for (const w of effectsWarnings) console.warn("[PxAnimator] effects shape warning:", w);
+  for (const w of effectsWarnings) diag.warn(PxDiagnosticKind.document, "effects shape: " + w);
   reportDocumentDiagnostics(doc, "[PxAnimator] createAnimator");
-  if (config !== void 0 || resetDocDefaults) {
-    const patched = applyAnimatorConfig(doc, config != null ? config : {}, { resetDefaults: !!resetDocDefaults });
-    for (const w of patched.warnings) console.warn("[PxAnimator] config override:", w);
+  if (patch !== void 0 || resetTimeline) {
+    const patched = applyAnimatorConfig(doc, patch != null ? patch : {}, { resetDefaults: !!resetTimeline });
+    for (const w of patched.warnings) diag.warn(PxDiagnosticKind.usage, "timeline override: " + w);
     doc = patched.doc;
   }
   const animatorConfig = getAnimatorConfig(doc) || {};
   const engine = resolveTimelineEngine(animatorConfig.engine);
-  doc = materialiseAllInTree(doc, engine);
+  doc = materializeAllInTree(doc, engine);
   let rootElement = null;
   if (containerElement) {
     doc = generateNewIds(doc);
     const containerEl = typeof containerElement === "string" ? document.querySelector(containerElement) : containerElement;
     if (containerEl) {
-      rootElement = renderNode(doc);
+      rootElement = renderNode(doc, void 0, diag);
       if (rootElement) {
         containerEl.replaceChildren(rootElement);
       }
@@ -7302,21 +7807,22 @@ function createAnimatorImpl(doc, adapter, callbacks, containerElement, config, r
   }
   return api;
 }
-function resolveAnimatorConfigOption(options) {
-  const { config, duration, delay, iterations, startOn } = options;
-  return foldAnimatorConfigShortcuts(config, { duration, delay, iterations, startOn });
+function resolveTimelineOption(options) {
+  const { timeline, duration, delay, iterations, startOn } = options;
+  return foldTimelineOverride(timeline, { duration, delay, iterations, startOn });
 }
 function createAnimator(options) {
-  const { src, data, adapter, callbacks, container, resetDocDefaults } = options;
-  const config = resolveAnimatorConfigOption(options);
-  if (data !== void 0 && src !== void 0) {
-    throw new Error("createAnimator: provide either `src` or `data`, not both");
+  const { src, doc, adapter, container, resetTimeline } = options;
+  const patch = resolveTimelineOption(options);
+  const callbacks = toEngineCallbacks(options);
+  if (doc !== void 0 && src !== void 0) {
+    throw new Error("createAnimator: provide either `src` or `doc`, not both");
   }
-  if (data === void 0 && src === void 0) {
-    throw new Error("createAnimator: either `src` or `data` is required");
+  if (doc === void 0 && src === void 0) {
+    throw new Error("createAnimator: either `src` or `doc` is required");
   }
-  if (data !== void 0) {
-    return createAnimatorImpl(data, adapter, callbacks, container, config, resetDocDefaults);
+  if (doc !== void 0) {
+    return createAnimatorImpl(doc, adapter, callbacks, container, patch, resetTimeline);
   }
   let animator = null;
   let pending = [];
@@ -7328,19 +7834,27 @@ function createAnimator(options) {
       pending.push(call);
     }
   };
+  const loadDiag = createDiagnostics(callbacks, "[PxAnimator]");
   fetch(src).then((res) => res.json()).then((json) => {
     if (destroyed) return;
     if (isPxElementFileFormat(json)) {
-      animator = createAnimatorImpl(json, adapter, callbacks, container, config, resetDocDefaults);
+      animator = createAnimatorImpl(json, adapter, callbacks, container, patch, resetTimeline);
       const queued = pending;
       pending = null;
       queued == null ? void 0 : queued.forEach((call) => call(animator));
     } else {
-      console.error('createAnimator: invalid animation document format at "' + src + '"');
+      loadDiag.error(
+        PxDiagnosticKind.document,
+        'createAnimator: invalid animation document format at "' + src + '"'
+      );
     }
   }).catch((err) => {
+    var _a2;
     pending = null;
-    console.error('createAnimator: failed to load "' + src + '"', err);
+    loadDiag.error(
+      PxDiagnosticKind.host,
+      'createAnimator: failed to load "' + src + '" \u2014 ' + ((_a2 = err == null ? void 0 : err.message) != null ? _a2 : String(err))
+    );
   });
   return {
     "isReady": () => !!animator,
@@ -7365,6 +7879,10 @@ function createAnimator(options) {
     "setCurrentTime": (time) => {
       enqueue((api) => api.setCurrentTime(time));
     },
+    "getCurrentProgress": () => animator ? animator.getCurrentProgress() : null,
+    "setCurrentProgress": (progress) => {
+      enqueue((api) => api.setCurrentProgress(progress));
+    },
     "destroy": () => {
       destroyed = true;
       pending = null;
@@ -7372,88 +7890,118 @@ function createAnimator(options) {
     }
   };
 }
-function loadTagAnimators() {
+function loadTagAnimators(options) {
   const elements = document.querySelectorAll("[" + PX_ANIM_SRC_ATTR_NAME + "]");
   for (let i = 0; i < elements.length; i++) {
     const element = elements[i];
     if (!element[PX_ANIM_ATTR_NAME]) {
       const src = element.getAttribute(PX_ANIM_SRC_ATTR_NAME);
       if (src) {
-        element[PX_ANIM_ATTR_NAME] = createAnimator({ src, container: element });
+        element[PX_ANIM_ATTR_NAME] = createAnimator(__spreadProps(__spreadValues({}, options), { src, container: element }));
       }
     }
   }
 }
-if (typeof window !== "undefined") {
-  window["loadTagAnimators"] = loadTagAnimators;
-  window["createAnimator"] = createAnimator;
-  window["setupAnimationTriggers"] = setupAnimationTriggers;
-}
 export {
-  COLOUR_ATTR_NAMES,
+  BASELINE_PLAYER_VERSION,
+  COLOR_ATTR_NAMES,
+  DEFAULT_DURATION_MS,
   MISSING_GLYPH_CLASS_NAME,
-  PX_ANIMATOR_DATA_KEY,
+  PLAYER_WIRE_STEPS,
+  PLAYER_WIRE_VERSION,
+  PX_ANIMATOR_DOC_KEY,
   PX_ANIM_ATTR_NAME,
   PX_ANIM_SRC_ATTR_NAME,
+  PX_PLAYER_SCHEMA_VERSION,
   PX_TRANSFORM_PART_KEYS,
+  PX_TRIGGER_DEFAULTS,
+  PxAlongPathMode,
   PxAnimatedSvgDocumentSchema,
   PxAnimationDefinitionSchema,
   PxAnimatorConfigSchema,
   PxAttrValueSchema,
   PxBezierPathSchema,
   PxBindingSchema,
+  PxClipPathEffectSchema,
   PxCloneEffectSchema,
   PxCloneWithout,
+  PxControlMode,
   PxDefsSchema,
+  PxDiagnosticKind,
   PxEasingOrRefSchema,
   PxEffectsSchema,
   PxElementAnimationSchema,
   PxFillGradientEffectSchema,
+  PxFinishAction,
   PxGradientSpreadMethod,
   PxGradientStopSchema,
   PxGradientType,
-  PxGradientUnits,
   PxKeyframeSchema,
   PxKeyframeValueSchema,
+  PxLengthAdjust,
   PxLoopDirection,
   PxLoopRepeatAt,
   PxLoopSchema,
+  PxMaskType,
   PxMaskedByEffectSchema,
   PxNodeBase,
   PxNodeSchema,
+  PxPathOverflow,
+  PxPinAlign,
   PxPropertyAnimationSchema,
   PxRepeaterEffectSchema,
   PxRetimeEffectSchema,
+  PxScrollAxis,
+  PxScrollKind,
+  PxScrollPhase,
+  PxScrollRangePointSchema,
+  PxScrollRangeSchema,
+  PxScrollSchema,
+  PxScrollSource,
   PxStrokeGradientEffectSchema,
   PxStrokeTrimEffectSchema,
   PxStrokeTrimSubPaths,
   PxSvgNodeExtra,
   PxTextEffectSchema,
   PxTextPathEffectSchema,
+  PxTextPathMethod,
+  PxTextPathSpacing,
   PxTimelineEngine,
   PxTimelineEngineExtra,
+  PxTimelinePinSchema,
+  PxTimelineSchema,
   PxTransformByEffectSchema,
   PxTransformPartsSchema,
   PxTransformValueSchema,
   PxTriggerSchema,
+  PxUnits,
   STYLE_ATTR_NAMES,
   TRANSFORM_FN_NAMES,
+  WIRE_VERSION_KEY,
+  WireStepKind,
+  WireVersionRelation,
   applyAnimatorConfig,
   applyPlayerEffects,
   calcAnimationValues,
   camelCaseToKebabWordIfNeeded,
   collectSampleTimes,
+  compareWireVersion,
+  controlModeTakesOverTrigger,
+  convertPlayerDocument,
   createAnimator,
-  createAnimatorImpl,
   createBasicFrameLoopAnimator,
+  createDiagnostics,
   createFrameLoopAnimator,
   createPathSampler,
   createWebApiAnimator,
   describeSchema,
+  diagnoseDocument,
   diffInEffect,
+  downgradePlayerDocument,
   evaluateMotionPathSegment,
   extendedPathForBrowser,
-  foldAnimatorConfigShortcuts,
+  foldTimelineOverride,
+  formatWireVersion,
   generateNewIds,
   getAnimatorConfig,
   getBindings,
@@ -7465,26 +8013,33 @@ export {
   jsonElementFactory,
   layoutGlyphTextChars,
   loadTagAnimators,
-  materialiseAllInTree,
-  materialiseAnimatedUseInstances,
-  materialiseGlyphText,
-  materialiseGlyphTextAlongPath,
-  materialiseGlyphTextHorizontal,
-  materialiseInternalLoopsInPropAnim,
-  materialiseInternalLoopsInTree,
-  materialiseMotionPathInPropAnim,
-  materialiseMotionPathsInTree,
+  materializeAllInTree,
+  materializeAnimatedUseInstances,
+  materializeGlyphText,
+  materializeGlyphTextAlongPath,
+  materializeGlyphTextHorizontal,
+  materializeInternalLoopsInPropAnim,
+  materializeInternalLoopsInTree,
+  materializeMotionPathInPropAnim,
+  materializeMotionPathsInTree,
   mergeAnimatorConfig,
-  getNormalisedBindings as normalizeDocument,
+  getNormalizedBindings as normalizeDocument,
+  parseWireVersion,
+  progressToTimeMs,
   propAnimIsMotionPath,
   px,
+  readWireVersion,
   renderNode,
+  resolveControlMode,
+  resolveTrigger,
   schemaKeys,
   setupAnimationTriggers,
   shiftAnimatable,
+  timeToProgress,
   toRGBA,
   validateDocument,
   validateNodeEffects,
+  versionAdvice,
   visualModelAt
 };
 //# sourceMappingURL=index.js.map