@pixodesk/svg-animator-web 1.0.41 → 1.0.44

package/dist/index.cjs

@@ -60,7 +60,9 @@ __export(index_exports, {
   createAdapterAnimator: () => createAdapterAnimator,
   createAnimator: () => createAnimator,
   generateNewIds: () => generateNewIds,
+  getAllAnimators: () => getAllAnimators,
   loadTagAnimators: () => loadTagAnimators,
+  onAnimatorsChange: () => onAnimatorsChange,
   px: () => px,
   renderNode: () => renderNode,
   setupAnimationTriggers: () => setupAnimationTriggers,
@@ -69,7 +71,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// ../svg-animator-core/dist/chunk-L6GJ6Y2M.js
+// ../svg-animator-core/dist/chunk-EFQLDGFY.js
 var __defProp2 = Object.defineProperty;
 var __defProps2 = Object.defineProperties;
 var __getOwnPropDescs2 = Object.getOwnPropertyDescriptors;
@@ -603,7 +605,7 @@ var px = {
   /** Defers schema creation — required for recursive types. Must supply a default value. */
   lazy: (fn, defaultVal) => new Lazy(fn, defaultVal)
 };
-var PX_WIRE_SCHEMA_VERSION = "1.1";
+var PX_WIRE_SCHEMA_VERSION = "1.2";
 var VERSION_RE = /^(\d+)\.(\d+)(?:\.(\d+))?$/;
 function parseWireVersion(raw) {
   if (typeof raw !== "string") return void 0;
@@ -627,14 +629,18 @@ var PxPlaybackDirection = {
 };
 var PX_ANIM_SRC_ATTR_NAME = "data-px-animation-src";
 var PX_ANIM_ATTR_NAME = "_px_animator";
-var PxStartOn = {
+var PxTriggerStart = {
   load: "load",
   mouseOver: "mouseOver",
   click: "click",
-  scrollIntoView: "scrollIntoView",
-  programmatic: "programmatic"
+  none: "none"
+};
+var PxOffScreenAction = {
+  pause: "pause",
+  continue: "continue",
+  reset: "reset"
 };
-var PxOutAction = {
+var PxMouseOutAction = {
   continue: "continue",
   pause: "pause",
   reset: "reset",
@@ -702,16 +708,20 @@ function mayUseNativeScrollTimeline(engine) {
   return engine !== PxTimelineEngineSetting.js;
 }
 var PX_TRIGGER_DEFAULTS = {
-  startOn: "load",
-  outAction: "continue",
-  scrollIntoViewThreshold: 0
+  start: "load",
+  offScreen: "pause",
+  mouseOut: "continue",
+  visibilityThreshold: 0.5,
+  visibilityDebounce: 150
 };
 function resolveTrigger(trigger) {
-  var _a2, _b, _c;
+  var _a2, _b, _c, _d, _e;
   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
+    start: (_a2 = trigger == null ? void 0 : trigger.start) != null ? _a2 : PX_TRIGGER_DEFAULTS.start,
+    offScreen: (_b = trigger == null ? void 0 : trigger.offScreen) != null ? _b : PX_TRIGGER_DEFAULTS.offScreen,
+    mouseOut: (_c = trigger == null ? void 0 : trigger.mouseOut) != null ? _c : PX_TRIGGER_DEFAULTS.mouseOut,
+    visibilityThreshold: (_d = trigger == null ? void 0 : trigger.visibilityThreshold) != null ? _d : PX_TRIGGER_DEFAULTS.visibilityThreshold,
+    visibilityDebounce: (_e = trigger == null ? void 0 : trigger.visibilityDebounce) != null ? _e : PX_TRIGGER_DEFAULTS.visibilityDebounce
   };
 }
 var PxLoopRepeatAt = {
@@ -847,9 +857,9 @@ function flattenAnimatorTimeline(cfg) {
   } else {
     if (timeline.duration !== void 0) flat.duration = timeline.duration;
     if (timeline.trigger !== void 0) {
-      const _b = timeline.trigger, { finishAction } = _b, restTrigger = __objRest2(_b, ["finishAction"]);
+      const _b = timeline.trigger, { finish } = _b, restTrigger = __objRest2(_b, ["finish"]);
       if (Object.keys(restTrigger).length) flat.trigger = restTrigger;
-      if (finishAction !== void 0) flat.resetOnFinish = finishAction === "reset";
+      if (finish !== void 0) flat.resetOnFinish = finish === "reset";
     }
     if (timeline.delay !== void 0) flat.delay = timeline.delay;
     if (timeline.iterations !== void 0) flat.iterations = timeline.iterations;
@@ -948,13 +958,15 @@ var PxElementAnimationSchema = implementsInterface()(px.union([
   PxAnimationDefinitionSchema
 ]));
 var PxTriggerSchema = implementsInterface()(px.object({
-  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(),
+  start: px.enum([PxTriggerStart.load, PxTriggerStart.mouseOver, PxTriggerStart.click, PxTriggerStart.none], PX_TRIGGER_DEFAULTS.start).optional(),
+  offScreen: px.enum([PxOffScreenAction.pause, PxOffScreenAction.continue, PxOffScreenAction.reset], PX_TRIGGER_DEFAULTS.offScreen).optional(),
+  mouseOut: px.enum([PxMouseOutAction.continue, PxMouseOutAction.pause, PxMouseOutAction.reset, PxMouseOutAction.reverse], PX_TRIGGER_DEFAULTS.mouseOut).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([PxFinishAction.hold, PxFinishAction.reset]).optional(),
-  scrollIntoViewThreshold: px.number().optional()
+  // `fill`) or `'reset'` (snap back to the start state). One of four occasion keys
+  // (`start`, `offScreen`, `mouseOut`, `finish`), all named the same way.
+  finish: px.enum([PxFinishAction.hold, PxFinishAction.reset]).optional(),
+  visibilityThreshold: px.number().optional(),
+  visibilityDebounce: px.number().optional()
 }));
 var PxGlyphSchema = implementsInterface()(px.object({
   width: px.number(),
@@ -3986,32 +3998,34 @@ var PxDiagnosticKind = {
   /** 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;
+var DOCS_URL = "https://github.com/pixodesk/pixodesk-svg-animator/blob/main/docs/diagnostics.md";
+function codeLine(code) {
+  return "PX" + code + " " + DOCS_URL + "#px" + code;
+}
+function errorIn(data) {
+  return data.find((d) => d instanceof Error);
 }
 function createDiagnostics(config, prefix) {
   const tag = prefix ? prefix + " " : "";
   return {
-    warn: (kind, message, detail) => {
+    warn: (kind, code, ...data) => {
+      const message = codeLine(code);
       if (config == null ? void 0 : config.onWarn) {
-        config.onWarn({ kind, message, detail });
+        config.onWarn({ code, kind, data, message });
         return;
       }
       if (config == null ? void 0 : config.muteWarn) return;
-      const line = tag + kind + ": " + message;
-      if (detail === void 0) console.warn(line);
-      else console.warn(line, detail);
+      console.warn(tag + kind + " " + message, ...data);
     },
-    error: (kind, error, detail) => {
-      const err = asError(error);
+    error: (kind, code, ...data) => {
+      const message = codeLine(code);
+      const error = errorIn(data);
       if (config == null ? void 0 : config.onError) {
-        config.onError({ kind, message: err.message, error: err, detail });
+        config.onError({ code, kind, data, message, error });
         return;
       }
       if (config == null ? void 0 : config.muteError) return;
-      const line = tag + kind + ": " + err.message;
-      if (detail === void 0) console.error(line);
-      else console.error(line, detail);
+      console.error(tag + kind + " " + message, ...data);
     }
   };
 }
@@ -6128,6 +6142,36 @@ function createAdapterAnimator(doc, adapter, callbacks) {
   };
   return api;
 }
+var PxDiagnosticCode = /* @__PURE__ */ ((PxDiagnosticCode2) => {
+  PxDiagnosticCode2[PxDiagnosticCode2["buildFailed"] = 1001] = "buildFailed";
+  PxDiagnosticCode2[PxDiagnosticCode2["invalidDocumentAtSrc"] = 1002] = "invalidDocumentAtSrc";
+  PxDiagnosticCode2[PxDiagnosticCode2["loadFailed"] = 1003] = "loadFailed";
+  PxDiagnosticCode2[PxDiagnosticCode2["animationBuildFailed"] = 1004] = "animationBuildFailed";
+  PxDiagnosticCode2[PxDiagnosticCode2["effectsShape"] = 1101] = "effectsShape";
+  PxDiagnosticCode2[PxDiagnosticCode2["timelineOverrideIgnored"] = 1102] = "timelineOverrideIgnored";
+  PxDiagnosticCode2[PxDiagnosticCode2["blockedTag"] = 1103] = "blockedTag";
+  PxDiagnosticCode2[PxDiagnosticCode2["unsupportedAnimatedAttrs"] = 1104] = "unsupportedAnimatedAttrs";
+  PxDiagnosticCode2[PxDiagnosticCode2["noBindings"] = 1105] = "noBindings";
+  PxDiagnosticCode2[PxDiagnosticCode2["unresolvedBinding"] = 1106] = "unresolvedBinding";
+  PxDiagnosticCode2[PxDiagnosticCode2["triggersNoRoot"] = 1201] = "triggersNoRoot";
+  PxDiagnosticCode2[PxDiagnosticCode2["noRootForSelector"] = 1202] = "noRootForSelector";
+  PxDiagnosticCode2[PxDiagnosticCode2["noRootElement"] = 1203] = "noRootElement";
+  PxDiagnosticCode2[PxDiagnosticCode2["noElementsForSelector"] = 1206] = "noElementsForSelector";
+  PxDiagnosticCode2[PxDiagnosticCode2["setAttributeNoElement"] = 1207] = "setAttributeNoElement";
+  PxDiagnosticCode2[PxDiagnosticCode2["scrollSmoothingNeedsOwnDriver"] = 1301] = "scrollSmoothingNeedsOwnDriver";
+  PxDiagnosticCode2[PxDiagnosticCode2["scrollNativeUnavailable"] = 1302] = "scrollNativeUnavailable";
+  PxDiagnosticCode2[PxDiagnosticCode2["scrollSubjectInvalid"] = 1303] = "scrollSubjectInvalid";
+  PxDiagnosticCode2[PxDiagnosticCode2["scrollSubjectNoMatch"] = 1304] = "scrollSubjectNoMatch";
+  PxDiagnosticCode2[PxDiagnosticCode2["scrollNoRootToObserve"] = 1305] = "scrollNoRootToObserve";
+  PxDiagnosticCode2[PxDiagnosticCode2["scrollTriggerIgnored"] = 1306] = "scrollTriggerIgnored";
+  PxDiagnosticCode2[PxDiagnosticCode2["rateRejected"] = 1401] = "rateRejected";
+  PxDiagnosticCode2[PxDiagnosticCode2["controlPropsConflict"] = 1501] = "controlPropsConflict";
+  PxDiagnosticCode2[PxDiagnosticCode2["rnCompileFailed"] = 1601] = "rnCompileFailed";
+  PxDiagnosticCode2[PxDiagnosticCode2["rnRenderFailed"] = 1602] = "rnRenderFailed";
+  PxDiagnosticCode2[PxDiagnosticCode2["rnBoundaryCaught"] = 1603] = "rnBoundaryCaught";
+  PxDiagnosticCode2[PxDiagnosticCode2["rnUnsupported"] = 1604] = "rnUnsupported";
+  return PxDiagnosticCode2;
+})(PxDiagnosticCode || {});
 var FLAT_ONLY_KEYS = [
   "timelineSource",
   "scroll",
@@ -6202,16 +6246,16 @@ function foldTimelineOverride(timeline, shortcuts) {
   } else {
     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) {
+  const { duration, delay, iterations, start } = shortcuts;
+  if (duration === void 0 && delay === void 0 && iterations === void 0 && start === void 0) {
     return base === void 0 ? void 0 : { timeline: base };
   }
   const out = isPlainObject(base) ? __spreadValues2({}, base) : {};
   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) {
-    out.trigger = __spreadProps2(__spreadValues2({}, out.trigger), { startOn });
+  if (start !== void 0) {
+    out.trigger = __spreadProps2(__spreadValues2({}, out.trigger), { start });
   }
   return { timeline: out };
 }
@@ -6358,6 +6402,202 @@ function asThrownError(e) {
   return e instanceof Error ? e : new Error(String(e));
 }
 
+// src/registry/PxAnimatorRegistry.ts
+var STORE_KEY = /* @__PURE__ */ Symbol.for("@pixodesk/svg-animator-web:animators");
+var GLOBAL_NAME = "__pixodeskAnimators";
+function store() {
+  const g = globalThis;
+  let s = g[STORE_KEY];
+  if (!s) {
+    const animators = /* @__PURE__ */ new Set();
+    const listeners = /* @__PURE__ */ new Set();
+    s = {
+      animators,
+      listeners,
+      getAll: () => Array.from(animators),
+      subscribe: (listener) => {
+        listeners.add(listener);
+        return () => {
+          listeners.delete(listener);
+        };
+      }
+    };
+    g[STORE_KEY] = s;
+    if (g[GLOBAL_NAME] === void 0) g[GLOBAL_NAME] = s;
+  }
+  return s;
+}
+function getAllAnimators() {
+  return store().getAll();
+}
+function onAnimatorsChange(listener) {
+  return store().subscribe(listener);
+}
+function notify(event, animator) {
+  for (const listener of store().listeners) {
+    try {
+      listener(event, animator);
+    } catch (e) {
+      setTimeout(() => {
+        throw e;
+      }, 0);
+    }
+  }
+}
+function registerAnimator(animator) {
+  const s = store();
+  if (s.animators.has(animator)) return;
+  s.animators.add(animator);
+  notify("add", animator);
+  const destroy = animator.destroy.bind(animator);
+  animator.destroy = () => {
+    destroy();
+    if (s.animators.delete(animator)) notify("remove", animator);
+  };
+}
+function withRegistryEvents(callbacks, api) {
+  const fire = (event) => {
+    const a = api();
+    if (a) notify(event, a);
+  };
+  return __spreadProps(__spreadValues({}, callbacks), {
+    onPlay: () => {
+      var _a2;
+      (_a2 = callbacks == null ? void 0 : callbacks.onPlay) == null ? void 0 : _a2.call(callbacks);
+      fire("play");
+    },
+    onPause: () => {
+      var _a2;
+      (_a2 = callbacks == null ? void 0 : callbacks.onPause) == null ? void 0 : _a2.call(callbacks);
+      fire("pause");
+    },
+    onCancel: () => {
+      var _a2;
+      (_a2 = callbacks == null ? void 0 : callbacks.onCancel) == null ? void 0 : _a2.call(callbacks);
+      fire("cancel");
+    },
+    onFinish: () => {
+      var _a2;
+      (_a2 = callbacks == null ? void 0 : callbacks.onFinish) == null ? void 0 : _a2.call(callbacks);
+      fire("finish");
+    }
+  });
+}
+
+// src/triggers/PxVisibilityGate.ts
+var PLAY_WHEN_VISIBLE_DEFAULTS = {
+  offScreen: PX_TRIGGER_DEFAULTS.offScreen,
+  visibilityThreshold: PX_TRIGGER_DEFAULTS.visibilityThreshold,
+  visibilityDebounce: PX_TRIGGER_DEFAULTS.visibilityDebounce
+};
+var THRESHOLD_STEPS = Array.from({ length: 21 }, (_, i) => i / 20);
+function effectiveRatio(entry) {
+  var _a2, _b;
+  const target = entry.boundingClientRect;
+  const visible = entry.intersectionRect;
+  if (!(target == null ? void 0 : target.height) || !visible) return entry.intersectionRatio;
+  const live = typeof window !== "undefined" && window.innerHeight ? window.innerHeight : Infinity;
+  const declared = (_b = (_a2 = entry.rootBounds) == null ? void 0 : _a2.height) != null ? _b : Infinity;
+  const viewport = Math.min(live, declared);
+  const denom = Math.min(target.height, Number.isFinite(viewport) ? viewport : target.height);
+  return denom > 0 ? visible.height / denom : entry.intersectionRatio;
+}
+function openGate(host) {
+  return {
+    requestStart: () => host.play(),
+    dispose: () => {
+    }
+  };
+}
+function isGated(offScreen) {
+  return offScreen !== PxOffScreenAction.continue;
+}
+function createVisibilityGate(root, trigger, host) {
+  if (!isGated(trigger.offScreen)) return openGate(host);
+  if (typeof IntersectionObserver === "undefined") return openGate(host);
+  const threshold = trigger.visibilityThreshold;
+  const debounceMs = trigger.visibilityDebounce;
+  let isOpen = void 0;
+  let startPending = false;
+  let pausedByGate = false;
+  let lastRatio = 0;
+  let openTimer;
+  const cancelPendingOpen = () => {
+    if (openTimer !== void 0) {
+      clearTimeout(openTimer);
+      openTimer = void 0;
+    }
+  };
+  const open = () => {
+    openTimer = void 0;
+    if (isOpen === true) return;
+    isOpen = true;
+    if (startPending || pausedByGate) {
+      startPending = false;
+      pausedByGate = false;
+      host.play();
+    }
+  };
+  const close = () => {
+    cancelPendingOpen();
+    if (isOpen === false) return;
+    isOpen = false;
+    if (!host.isPlaying()) return;
+    if (trigger.offScreen === PxOffScreenAction.reset) {
+      host.cancel();
+    } else {
+      host.pause();
+    }
+    pausedByGate = true;
+  };
+  const apply2 = (ratio) => {
+    lastRatio = ratio;
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      close();
+      return;
+    }
+    if (ratio >= threshold) {
+      if (isOpen === true || openTimer !== void 0) return;
+      if (debounceMs > 0) openTimer = setTimeout(open, debounceMs);
+      else open();
+      return;
+    }
+    if (ratio <= 0) {
+      close();
+      return;
+    }
+    if (isOpen !== true) cancelPendingOpen();
+  };
+  const observer = new IntersectionObserver((entries) => {
+    const last = entries[entries.length - 1];
+    if (last) apply2(last.isIntersecting ? effectiveRatio(last) : 0);
+  }, { threshold: THRESHOLD_STEPS });
+  observer.observe(root);
+  const onVisibilityChange = () => {
+    apply2(lastRatio);
+  };
+  const hasDocument = typeof document !== "undefined";
+  if (hasDocument) document.addEventListener("visibilitychange", onVisibilityChange);
+  return {
+    requestStart: (immediate) => {
+      if (immediate || isOpen === true) {
+        cancelPendingOpen();
+        isOpen = true;
+        startPending = false;
+        pausedByGate = false;
+        host.play();
+        return;
+      }
+      startPending = true;
+    },
+    dispose: () => {
+      cancelPendingOpen();
+      observer.disconnect();
+      if (hasDocument) document.removeEventListener("visibilitychange", onVisibilityChange);
+    }
+  };
+}
+
 // src/triggers/PxAnimatorTriggers.ts
 function setupAnimationTriggers(api, trigger, diag) {
   const report = diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]");
@@ -6365,10 +6605,10 @@ function setupAnimationTriggers(api, trigger, diag) {
   const dispose = () => {
     for (const undo of cleanups.splice(0)) undo();
   };
-  const { startOn, outAction, scrollIntoViewThreshold } = resolveTrigger(trigger);
+  const resolved = resolveTrigger(trigger);
   const root = api.getRootElement();
   if (!root) {
-    report.warn(PxDiagnosticKind.host, "setupAnimationTriggers: No root element found for animation.");
+    report.warn(PxDiagnosticKind.host, PxDiagnosticCode.triggersNoRoot);
     return dispose;
   }
   let reversed = false;
@@ -6379,27 +6619,34 @@ function setupAnimationTriggers(api, trigger, diag) {
     }
     api.play();
   };
-  const handleEndAction = () => {
-    switch (outAction) {
-      case "pause":
+  const gate = createVisibilityGate(root, resolved, {
+    isPlaying: () => api.isPlaying(),
+    play: start,
+    pause: () => api.pause(),
+    cancel: () => api.cancel()
+  });
+  cleanups.push(() => gate.dispose());
+  const handleMouseOut = () => {
+    switch (resolved.mouseOut) {
+      case PxMouseOutAction.pause:
         api.pause();
         break;
-      case "reset":
+      case PxMouseOutAction.reset:
         api.cancel();
         break;
-      case "reverse":
+      case PxMouseOutAction.reverse:
         reversed = true;
         api.setPlaybackRate(-1);
         api.play();
         break;
-      case "continue":
+      case PxMouseOutAction.continue:
       default:
         break;
     }
   };
-  switch (startOn) {
-    case "load": {
-      const startHandler = () => start();
+  switch (resolved.start) {
+    case PxTriggerStart.load: {
+      const startHandler = () => gate.requestStart(false);
       if (document.readyState === "complete") {
         startHandler();
       } else {
@@ -6408,14 +6655,14 @@ function setupAnimationTriggers(api, trigger, diag) {
       }
       break;
     }
-    case "mouseOver": {
+    case PxTriggerStart.mouseOver: {
       let enteredOnce = false;
       const mouseOverHandler = () => {
         enteredOnce = true;
-        start();
+        gate.requestStart(true);
       };
       const mouseOutHandler = () => {
-        if (enteredOnce) handleEndAction();
+        if (enteredOnce) handleMouseOut();
       };
       root.addEventListener("mouseenter", mouseOverHandler);
       root.addEventListener("mouseleave", mouseOutHandler);
@@ -6425,51 +6672,16 @@ function setupAnimationTriggers(api, trigger, diag) {
       });
       break;
     }
-    case "click": {
+    case PxTriggerStart.click: {
       const clickHandler = () => {
-        if (api.isPlaying()) {
-          handleEndAction();
-        } else {
-          start();
-        }
+        if (api.isPlaying()) api.pause();
+        else gate.requestStart(true);
       };
       root.addEventListener("click", clickHandler);
       cleanups.push(() => root.removeEventListener("click", clickHandler));
       break;
     }
-    case "scrollIntoView": {
-      const effectiveRatio = (entry) => {
-        var _a2, _b;
-        const target = entry.boundingClientRect;
-        const visible = entry.intersectionRect;
-        if (!(target == null ? void 0 : target.height) || !visible) return entry.intersectionRatio;
-        const live = typeof window !== "undefined" && window.innerHeight ? window.innerHeight : Infinity;
-        const declared = (_b = (_a2 = entry.rootBounds) == null ? void 0 : _a2.height) != null ? _b : Infinity;
-        const viewport = Math.min(live, declared);
-        const denom = Math.min(target.height, Number.isFinite(viewport) ? viewport : target.height);
-        return denom > 0 ? visible.height / denom : entry.intersectionRatio;
-      };
-      const thresholdSteps = Array.from({ length: 21 }, (_, i) => i / 20);
-      let wasIntersecting = false;
-      const observer = new IntersectionObserver(
-        (entries) => {
-          entries.forEach((entry) => {
-            if (entry.isIntersecting && effectiveRatio(entry) >= scrollIntoViewThreshold) {
-              wasIntersecting = true;
-              start();
-            } else if (wasIntersecting) {
-              wasIntersecting = false;
-              handleEndAction();
-            }
-          });
-        },
-        { threshold: thresholdSteps }
-      );
-      observer.observe(root);
-      cleanups.push(() => observer.disconnect());
-      break;
-    }
-    case "programmatic":
+    case PxTriggerStart.none:
       break;
   }
   return dispose;
@@ -6477,7 +6689,12 @@ function setupAnimationTriggers(api, trigger, diag) {
 
 // src/engines/PxAnimatorFrameLoop.ts
 function getSelector(id) {
-  return "#" + id;
+  return "#" + escapeCssId(id);
+}
+function escapeCssId(id) {
+  const css = globalThis.CSS;
+  if (typeof (css == null ? void 0 : css.escape) === "function") return css.escape(id);
+  return id.replace(/^([0-9])/, (_all, digit) => "\\3" + digit + " ").replace(/([^\w\-\\ ])/g, "\\$1");
 }
 function createFrameLoopAnimator(doc, adapter, callbacks, rootElement) {
   var _a2;
@@ -6487,9 +6704,9 @@ function createFrameLoopAnimator(doc, adapter, callbacks, rootElement) {
     if (doc.id) {
       const rootSelector = getSelector(doc.id);
       rootElement = document.querySelector(rootSelector);
-      if (!rootElement) diag.warn(PxDiagnosticKind.host, "createFrameLoopAnimator: No root element found for selector: " + rootSelector);
+      if (!rootElement) diag.warn(PxDiagnosticKind.host, PxDiagnosticCode.noRootForSelector, rootSelector);
     } else {
-      diag.warn(PxDiagnosticKind.host, "createFrameLoopAnimator: No root element provided");
+      diag.warn(PxDiagnosticKind.host, PxDiagnosticCode.noRootElement);
     }
   }
   const basicApi = createAdapterAnimator(
@@ -6501,7 +6718,7 @@ function createFrameLoopAnimator(doc, adapter, callbacks, rootElement) {
     "getRootElement": () => rootElement || null
   });
   if (isScrollTimeline(config)) {
-    if (config.trigger) diag.warn(PxDiagnosticKind.usage, "scroll timeline: `animator.trigger` is ignored (triggers do not apply to scroll-driven playback)");
+    if (config.trigger) diag.warn(PxDiagnosticKind.usage, PxDiagnosticCode.scrollTriggerIgnored);
   } else {
     const detachTriggers = setupAnimationTriggers(api, (_a2 = config.trigger) != null ? _a2 : {}, diag);
     const destroyEngine = api.destroy.bind(api);
@@ -6526,7 +6743,7 @@ function createDomAdapter(rootElement, diag) {
       const elements = (rootElement == null ? void 0 : rootElement.querySelectorAll(selector)) || document.querySelectorAll(selector);
       if (elements.length === 0 && !warnedSelectors.has(selector)) {
         warnedSelectors.add(selector);
-        report.warn(PxDiagnosticKind.host, 'setAttribute: No elements found for selector "' + selector + '"');
+        report.warn(PxDiagnosticKind.host, PxDiagnosticCode.setAttributeNoElement, selector);
       }
       for (let i = 0; i < elements.length; i++) {
         const element = elements[i];
@@ -6645,9 +6862,9 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
     if (doc.id) {
       const rootSelector = getSelector(doc.id);
       rootElement = document.querySelector(rootSelector);
-      if (!rootElement) diag.warn(PxDiagnosticKind.host, "createWebApiAnimator: No root element found for selector: " + rootSelector);
+      if (!rootElement) diag.warn(PxDiagnosticKind.host, PxDiagnosticCode.noRootForSelector, rootSelector);
     } else {
-      diag.warn(PxDiagnosticKind.host, "createWebApiAnimator: No root element provided");
+      diag.warn(PxDiagnosticKind.host, PxDiagnosticCode.noRootElement);
     }
   }
   const bindings = normalizeBindings(doc, PxTimelineEngine.native);
@@ -6660,18 +6877,18 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
   let finishNotified = false;
   let removeCalled = false;
   if (!(bindings == null ? void 0 : bindings.length)) {
-    diag.warn(PxDiagnosticKind.document, "createWebApiAnimator: No animation bindings defined");
+    diag.warn(PxDiagnosticKind.document, PxDiagnosticCode.noBindings);
   }
   for (const binding of bindings || []) {
     const animDef = binding.animate;
     if (!animDef || typeof animDef !== "object" || Array.isArray(animDef)) {
-      diag.warn(PxDiagnosticKind.document, "createWebApiAnimator: Empty or unresolved binding", binding);
+      diag.warn(PxDiagnosticKind.document, PxDiagnosticCode.unresolvedBinding, binding);
       continue;
     }
     const selector = getSelector(binding.id);
     const elements = (rootElement == null ? void 0 : rootElement.querySelectorAll(selector)) || document.querySelectorAll(selector);
     if (elements.length === 0) {
-      diag.warn(PxDiagnosticKind.host, 'createWebApiAnimator: No elements found for selector "' + selector + '"');
+      diag.warn(PxDiagnosticKind.host, PxDiagnosticCode.noElementsForSelector, selector);
     }
     const keyframesMap = convertToWebApiKeyframes(animDef, unsupportedSet, config);
     const positiveDelay = config.delay && config.delay > 0 ? config.delay : void 0;
@@ -6720,14 +6937,14 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
             }
             animations.push(anim);
           } catch (e) {
-            diag.warn(PxDiagnosticKind.internal, "createWebApiAnimator: could not build the animation", e);
+            diag.warn(PxDiagnosticKind.internal, PxDiagnosticCode.animationBuildFailed, e);
           }
         }
       }
     }
   }
   if (!forceEvenIfHasUnsupportedAttrs && unsupportedSet.size) {
-    diag.warn(PxDiagnosticKind.platform, "Unsupported CSS attrs: " + [...unsupportedSet].join(", "));
+    diag.warn(PxDiagnosticKind.platform, PxDiagnosticCode.unsupportedAnimatedAttrs, [...unsupportedSet].join(", "));
     return null;
   }
   const api = {
@@ -6772,7 +6989,7 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
     },
     "setPlaybackRate": (rate) => {
       if (!isValidPlaybackRate(rate)) {
-        diag.warn(PxDiagnosticKind.usage, PX_RATE_REJECTED);
+        diag.warn(PxDiagnosticKind.usage, PxDiagnosticCode.rateRejected);
         return api;
       }
       animations.forEach((a) => a.playbackRate = rate);
@@ -6812,7 +7029,7 @@ function createWebApiAnimator(doc, callbacks, rootElement, forceEvenIfHasUnsuppo
     }
   };
   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)");
+    if (config.trigger) diag.warn(PxDiagnosticKind.usage, PxDiagnosticCode.scrollTriggerIgnored);
   } else {
     const detachTriggers = setupAnimationTriggers(api, (_b = config.trigger) != null ? _b : {}, diag);
     const destroyEngine = api.destroy.bind(api);
@@ -6842,7 +7059,7 @@ function createNativeScrollTimeline(subject, config, diag) {
   const scroll = config.scroll || {};
   const kind = (_a2 = scroll.kind) != null ? _a2 : "view";
   if (scroll.smoothing) {
-    report.warn(PxDiagnosticKind.platform, "scroll timeline: `smoothing` needs the built-in driver \u2014 using the built-in driver instead of the browser timeline");
+    report.warn(PxDiagnosticKind.platform, PxDiagnosticCode.scrollSmoothingNeedsOwnDriver);
     return null;
   }
   const g = globalThis;
@@ -6859,7 +7076,7 @@ function createNativeScrollTimeline(subject, config, diag) {
       timeline = new Ctor({ source, axis });
     }
   } catch (e) {
-    report.warn(PxDiagnosticKind.platform, "scroll timeline: native timeline construction failed \u2014 falling back to the player measuring progress itself", e);
+    report.warn(PxDiagnosticKind.platform, PxDiagnosticCode.scrollNativeUnavailable, e);
     return null;
   }
   return {
@@ -6906,11 +7123,11 @@ function resolveScrollSubject(svgRoot, subject, diag) {
   try {
     found = document.querySelector(spec);
   } catch (e) {
-    report.warn(PxDiagnosticKind.document, 'scroll timeline: subject "' + spec + '" is not a valid selector \u2014 measuring the SVG itself');
+    report.warn(PxDiagnosticKind.document, PxDiagnosticCode.scrollSubjectInvalid, spec);
     return svgRoot;
   }
   if (!found) {
-    report.warn(PxDiagnosticKind.host, 'scroll timeline: subject "' + spec + '" matched no element \u2014 measuring the SVG itself');
+    report.warn(PxDiagnosticKind.host, PxDiagnosticCode.scrollSubjectNoMatch, spec);
     return svgRoot;
   }
   return found;
@@ -7152,7 +7369,7 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
           };
         }
       } else {
-        diag.warn(PxDiagnosticKind.host, "scroll timeline: no root element to observe \u2014 animation will stay at frame 0");
+        diag.warn(PxDiagnosticKind.host, PxDiagnosticCode.scrollNoRootToObserve);
       }
       return api;
     });
@@ -7174,7 +7391,7 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
 var SVG_NS = "http://www.w3.org/2000/svg";
 function createElement(tagName, normalizedProps, style, children, textContent, diag) {
   if (PX_DISALLOWED_SVG_TAGS_LOWER.has(tagName.toLowerCase())) {
-    (diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]")).warn(PxDiagnosticKind.document, "SVG tag blocked (dangerous): " + tagName);
+    (diag != null ? diag : createDiagnostics(void 0, "[PxAnimator]")).warn(PxDiagnosticKind.document, PxDiagnosticCode.blockedTag, tagName);
     return null;
   }
   const element = document.createElementNS(SVG_NS, tagName);
@@ -7237,11 +7454,11 @@ function createAnimatorFromConfig(doc, adapter, callbacks, rootElement) {
 function createAnimatorImpl(doc, adapter, callbacks, containerElement, patch, resetTimeline) {
   const diag = createDiagnostics(callbacks, "[PxAnimator]");
   const effectsWarnings = validateNodeEffects(doc);
-  for (const w of effectsWarnings) diag.warn(PxDiagnosticKind.document, "effects shape: " + w);
+  for (const w of effectsWarnings) diag.warn(PxDiagnosticKind.document, PxDiagnosticCode.effectsShape, w);
   reportDocumentDiagnostics(doc, "[PxAnimator] createAnimator");
   if (patch !== void 0 || resetTimeline) {
     const patched = applyAnimatorConfig(doc, patch != null ? patch : {}, { resetTimeline: !!resetTimeline });
-    for (const w of patched.warnings) diag.warn(PxDiagnosticKind.usage, "timeline override: " + w);
+    for (const w of patched.warnings) diag.warn(PxDiagnosticKind.usage, PxDiagnosticCode.timelineOverrideIgnored, w);
     doc = patched.doc;
   }
   const animatorConfig = getAnimatorConfig(doc) || {};
@@ -7273,14 +7490,15 @@ function isInternalOptions(options) {
   return "adapter" in options;
 }
 function resolveTimelineOption(options) {
-  const { timeline, duration, delay, iterations, startOn } = options;
-  return foldTimelineOverride(timeline, { duration, delay, iterations, startOn });
+  const { timeline, duration, delay, iterations, start } = options;
+  return foldTimelineOverride(timeline, { duration, delay, iterations, start });
 }
 function createAnimator(options) {
   const { src, doc, container, resetTimeline } = options;
   const adapter = isInternalOptions(options) ? options.adapter : void 0;
   const patch = resolveTimelineOption(options);
-  const callbacks = toEngineCallbacks(options);
+  let proxy;
+  const callbacks = withRegistryEvents(toEngineCallbacks(options), () => proxy);
   if (doc !== void 0 && src !== void 0) {
     throw new Error("createAnimator: provide either `src` or `doc`, not both");
   }
@@ -7304,31 +7522,19 @@ function createAnimator(options) {
     pending = null;
     queued == null ? void 0 : queued.forEach((call) => call(api));
   };
-  const failed = (kind, message, detail) => {
+  const failed = (kind, code, ...data) => {
     pending = null;
-    diag.error(kind, message, detail);
+    diag.error(kind, code, ...data);
   };
   const build = (document2) => {
     try {
       ready(createAnimatorImpl(document2, adapter, callbacks, container, patch, resetTimeline));
     } catch (e) {
       const err = asThrownError(e);
-      failed(PxDiagnosticKind.internal, "createAnimator: could not build the player \u2014 " + err.message, err);
+      failed(PxDiagnosticKind.internal, PxDiagnosticCode.buildFailed, err);
     }
   };
-  if (doc !== void 0) {
-    build(doc);
-  } else {
-    fetch(src).then((res) => res.json()).then((json) => {
-      if (destroyed) return;
-      if (isPxDocument(json)) build(json);
-      else failed(PxDiagnosticKind.document, 'createAnimator: invalid animation document format at "' + src + '"');
-    }).catch((err) => {
-      var _a2;
-      failed(PxDiagnosticKind.host, 'createAnimator: failed to load "' + src + '" \u2014 ' + ((_a2 = err == null ? void 0 : err.message) != null ? _a2 : String(err)));
-    });
-  }
-  return {
+  proxy = {
     "isReady": () => !!animator,
     "getRootElement": () => animator ? animator.getRootElement() : null,
     "isPlaying": () => (animator == null ? void 0 : animator.isPlaying()) || false,
@@ -7361,6 +7567,20 @@ function createAnimator(options) {
       animator == null ? void 0 : animator.destroy();
     }
   };
+  registerAnimator(proxy);
+  if (doc !== void 0) {
+    build(doc);
+  } else {
+    fetch(src).then((res) => res.json()).then((json) => {
+      if (destroyed) return;
+      if (isPxDocument(json)) build(json);
+      else failed(PxDiagnosticKind.document, PxDiagnosticCode.invalidDocumentAtSrc, src);
+    }).catch((err) => {
+      var _a2;
+      failed(PxDiagnosticKind.host, PxDiagnosticCode.loadFailed, src, (_a2 = err == null ? void 0 : err.message) != null ? _a2 : String(err));
+    });
+  }
+  return proxy;
 }
 function loadTagAnimators(options) {
   const elements = document.querySelectorAll("[" + PX_ANIM_SRC_ATTR_NAME + "]");
@@ -7387,7 +7607,9 @@ function loadTagAnimators(options) {
   createAdapterAnimator,
   createAnimator,
   generateNewIds,
+  getAllAnimators,
   loadTagAnimators,
+  onAnimatorsChange,
   px,
   renderNode,
   setupAnimationTriggers,