@pixodesk/svg-animator-web 1.0.41 → 1.0.44

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { P as PxAnimatorApi } from './PxAnimator-yjuSFhQw.cjs';
 export { a as PxAnimatorOptions, b as PxPlaybackApi, c as PxTagAnimatorOptions, d as createAnimator, l as loadTagAnimators } from './PxAnimator-yjuSFhQw.cjs';
 import { PxAnimatorCallbacks, PxAnimatedSvgDocument, PxTrigger, PxDiagnostics, PxNode, PxDefinitions } from '@pixodesk/svg-animator-core';
-export { PxAnimatedSvgDocument, PxAnimatorCallbacks, PxAnimatorConfig, PxAnimatorConfigSchema, PxBinding, PxDefinitions, PxDefinitionsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxEngineCallbacks, PxFillMode, PxInfer, PxNode, PxNodeBaseSchema, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverride, PxSchema, PxScrollSchema, PxStartOn, PxSvgNode, PxSvgNodeRootSchema, PxTimelineEngineSetting, PxTimelinePatch, PxTrigger, PxTriggerSchema, PxValidationContext, createAdapterAnimator, generateNewIds, px, toDomProps, validateDocument } from '@pixodesk/svg-animator-core';
+export { PxAnimatedSvgDocument, PxAnimatorCallbacks, PxAnimatorConfig, PxAnimatorConfigSchema, PxBinding, PxDefinitions, PxDefinitionsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxEngineCallbacks, PxFillMode, PxInfer, PxNode, PxNodeBaseSchema, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverride, PxSchema, PxScrollSchema, PxSvgNode, PxSvgNodeRootSchema, PxTimelineEngineSetting, PxTimelinePatch, PxTrigger, PxTriggerSchema, PxTriggerStart, PxValidationContext, createAdapterAnimator, generateNewIds, px, toDomProps, validateDocument } from '@pixodesk/svg-animator-core';
 
 /**
  * Options accepted by the pre-rendered entry points — a subset of `PxAnimatorOptions`: the
@@ -19,41 +19,71 @@ interface PxPrerenderedAnimatorOptions extends PxAnimatorCallbacks {
 }
 
 /**
- * Sets up event-based triggers for an animation.
+ * Wires a document's trigger block to its root element.
  *
- * This function attaches event listeners to the animation's root element based on the
- * provided configuration, allowing animations to be started by user interactions
- * or visibility changes.
+ * TWO INDEPENDENT AXES, which is why there is no `scrollIntoView` here:
+ *  - `start` — what STARTS the animation: 'load' (default), 'mouseOver', 'click', or 'none'
+ *    (nothing but the API does).
+ *  - `offScreen` + `visibilityThreshold` + `visibilityDebounce` — whether it may RUN, whatever
+ *    started it. Owned by {@link createVisibilityGate}, wired for every document.
  *
- * ### Trigger Options (startOn):
- * - 'load' (default): Starts after the page loads.
- * - 'mouseOver': Starts on mouse enter.
- * - 'click': Toggles play/end action on click.
- * - 'scrollIntoView': Starts when the element scrolls into the viewport.
- * - 'programmatic': No automatic start. Must be controlled via the API.
+ * `start: 'load'` behind the default gate is what `startOn: 'scrollIntoView'` used to mean: hold
+ * at frame 0 until enough is on screen, play, pause when it leaves, resume when it returns. The
+ * difference is that the same gate now also applies to a document started by a click or a hover.
  *
- * ### End Action Options (outAction):
- * Defines behavior when the trigger condition ends (e.g., mouse leave).
- * - 'continue' (default): Animation continues playing.
- * - 'pause': Pauses the animation.
- * - 'reset': Cancels the animation, resetting it to the start.
- * - 'reverse': Reverses the animation playback.
+ * `mouseOut` is what happens when the pointer LEAVES ('continue' by default, or pause / reset /
+ * reverse); it is read only for `start: 'mouseOver'`. A `click` document is a plain play/pause
+ * toggle with nothing to configure.
  *
- * @param {!PxAnimatorApi} api The animator API instance to control.
- * @param {!PxTrigger} trigger The trigger configuration object. Only `startOn`, `outAction` and
- *   `scrollIntoViewThreshold` are read here; `finishAction` belongs to the PLAYER (what happens
- *   after a natural end), not to the trigger wiring.
- * @returns A disposer that detaches every listener and observer this call attached (review §14).
- *   `createAnimator` ties it to `destroy()`. Call it yourself before re-arming an element you
- *   wired by hand — otherwise the old listeners stay live next to the new ones.
+ * @param api The animator API instance to control.
+ * @param trigger The trigger configuration. `finish` belongs to the PLAYER (what happens after a
+ *   natural end), not to the trigger wiring, and is not read here.
+ * @returns A disposer that detaches every listener, observer and timer this call attached
+ *   (review §14). `createAnimator` ties it to `destroy()`. Call it yourself before re-arming an
+ *   element you wired by hand — otherwise the old listeners stay live next to the new ones.
  * @public
  */
 declare function setupAnimationTriggers(api: PxAnimatorApi, trigger: PxTrigger, diag?: PxDiagnostics): () => void;
 
+/**
+ * THE PAGE-WIDE REGISTRY — every live animator in the window, whoever created it.
+ *
+ * Like lottie-web's `getRegisteredAnimations()`: a dev tool, a test, or a "pause everything
+ * while the tab is hidden" can reach every player without holding on to each `createAnimator`
+ * result. An animator joins when it is built and leaves on `destroy()`; play / pause / cancel /
+ * finish are announced to subscribers.
+ *
+ * ONE registry per window, whatever the bundling: the store hangs off `globalThis` under a
+ * `Symbol.for` key, so the ESM build in one script and the UMD build in another share it. It
+ * is also reachable by NAME — `globalThis.__pixodeskAnimators` — for tooling that does not
+ * import the library (a devtools panel reading a page it did not build). Web only: React
+ * Native players never touch it.
+ *
+ * EXPERIMENTAL (2026-09): not settled — the event names, what `getAll()` includes and the
+ * global's name may change without a major version. Documented as such in
+ * docs/library/web-player.md ("Every animator on the page").
+ */
+/** What changed for an animator in the page-wide registry. Experimental — may change. @public */
+type PxAnimatorsEvent = 'add' | 'remove' | 'play' | 'pause' | 'cancel' | 'finish';
+/** Called for every {@link PxAnimatorsEvent} of every animator in the window. Experimental — may change. @public */
+type PxAnimatorsListener = (event: PxAnimatorsEvent, animator: PxAnimatorApi) => void;
+/** The store itself — what `globalThis.__pixodeskAnimators` holds. Experimental — may change. @public */
+interface PxAnimatorRegistry {
+    /** Every live animator, in creation order. */
+    getAll(): ReadonlyArray<PxAnimatorApi>;
+    /** Announcements of add / remove / play / pause / cancel / finish; returns the unsubscribe. */
+    subscribe(listener: PxAnimatorsListener): () => void;
+}
+/** Every live animator in this window, in creation order. Experimental — may change. @public */
+declare function getAllAnimators(): ReadonlyArray<PxAnimatorApi>;
+/** Hear every animator in this window start, pause, cancel, finish, appear or go — returns
+ *  the unsubscribe. Experimental — may change. @public */
+declare function onAnimatorsChange(listener: PxAnimatorsListener): () => void;
+
 /**
  * Renders a PxNode tree to DOM elements.
  * @public @advanced
  */
 declare function renderNode(node: PxNode, defs?: PxDefinitions, diag?: PxDiagnostics): Element | null;
 
-export { PxAnimatorApi, type PxPrerenderedAnimatorOptions, renderNode, setupAnimationTriggers };
+export { PxAnimatorApi, type PxAnimatorRegistry, type PxAnimatorsEvent, type PxAnimatorsListener, type PxPrerenderedAnimatorOptions, getAllAnimators, onAnimatorsChange, renderNode, setupAnimationTriggers };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { P as PxAnimatorApi } from './PxAnimator-yjuSFhQw.js';
 export { a as PxAnimatorOptions, b as PxPlaybackApi, c as PxTagAnimatorOptions, d as createAnimator, l as loadTagAnimators } from './PxAnimator-yjuSFhQw.js';
 import { PxAnimatorCallbacks, PxAnimatedSvgDocument, PxTrigger, PxDiagnostics, PxNode, PxDefinitions } from '@pixodesk/svg-animator-core';
-export { PxAnimatedSvgDocument, PxAnimatorCallbacks, PxAnimatorConfig, PxAnimatorConfigSchema, PxBinding, PxDefinitions, PxDefinitionsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxEngineCallbacks, PxFillMode, PxInfer, PxNode, PxNodeBaseSchema, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverride, PxSchema, PxScrollSchema, PxStartOn, PxSvgNode, PxSvgNodeRootSchema, PxTimelineEngineSetting, PxTimelinePatch, PxTrigger, PxTriggerSchema, PxValidationContext, createAdapterAnimator, generateNewIds, px, toDomProps, validateDocument } from '@pixodesk/svg-animator-core';
+export { PxAnimatedSvgDocument, PxAnimatorCallbacks, PxAnimatorConfig, PxAnimatorConfigSchema, PxBinding, PxDefinitions, PxDefinitionsSchema, PxDiagnostic, PxDiagnosticKind, PxDiagnostics, PxDiagnosticsConfig, PxEngineCallbacks, PxFillMode, PxInfer, PxNode, PxNodeBaseSchema, PxPlatformAdapter, PxPlaybackDirection, PxPlaybackOverride, PxSchema, PxScrollSchema, PxSvgNode, PxSvgNodeRootSchema, PxTimelineEngineSetting, PxTimelinePatch, PxTrigger, PxTriggerSchema, PxTriggerStart, PxValidationContext, createAdapterAnimator, generateNewIds, px, toDomProps, validateDocument } from '@pixodesk/svg-animator-core';
 
 /**
  * Options accepted by the pre-rendered entry points — a subset of `PxAnimatorOptions`: the
@@ -19,41 +19,71 @@ interface PxPrerenderedAnimatorOptions extends PxAnimatorCallbacks {
 }
 
 /**
- * Sets up event-based triggers for an animation.
+ * Wires a document's trigger block to its root element.
  *
- * This function attaches event listeners to the animation's root element based on the
- * provided configuration, allowing animations to be started by user interactions
- * or visibility changes.
+ * TWO INDEPENDENT AXES, which is why there is no `scrollIntoView` here:
+ *  - `start` — what STARTS the animation: 'load' (default), 'mouseOver', 'click', or 'none'
+ *    (nothing but the API does).
+ *  - `offScreen` + `visibilityThreshold` + `visibilityDebounce` — whether it may RUN, whatever
+ *    started it. Owned by {@link createVisibilityGate}, wired for every document.
  *
- * ### Trigger Options (startOn):
- * - 'load' (default): Starts after the page loads.
- * - 'mouseOver': Starts on mouse enter.
- * - 'click': Toggles play/end action on click.
- * - 'scrollIntoView': Starts when the element scrolls into the viewport.
- * - 'programmatic': No automatic start. Must be controlled via the API.
+ * `start: 'load'` behind the default gate is what `startOn: 'scrollIntoView'` used to mean: hold
+ * at frame 0 until enough is on screen, play, pause when it leaves, resume when it returns. The
+ * difference is that the same gate now also applies to a document started by a click or a hover.
  *
- * ### End Action Options (outAction):
- * Defines behavior when the trigger condition ends (e.g., mouse leave).
- * - 'continue' (default): Animation continues playing.
- * - 'pause': Pauses the animation.
- * - 'reset': Cancels the animation, resetting it to the start.
- * - 'reverse': Reverses the animation playback.
+ * `mouseOut` is what happens when the pointer LEAVES ('continue' by default, or pause / reset /
+ * reverse); it is read only for `start: 'mouseOver'`. A `click` document is a plain play/pause
+ * toggle with nothing to configure.
  *
- * @param {!PxAnimatorApi} api The animator API instance to control.
- * @param {!PxTrigger} trigger The trigger configuration object. Only `startOn`, `outAction` and
- *   `scrollIntoViewThreshold` are read here; `finishAction` belongs to the PLAYER (what happens
- *   after a natural end), not to the trigger wiring.
- * @returns A disposer that detaches every listener and observer this call attached (review §14).
- *   `createAnimator` ties it to `destroy()`. Call it yourself before re-arming an element you
- *   wired by hand — otherwise the old listeners stay live next to the new ones.
+ * @param api The animator API instance to control.
+ * @param trigger The trigger configuration. `finish` belongs to the PLAYER (what happens after a
+ *   natural end), not to the trigger wiring, and is not read here.
+ * @returns A disposer that detaches every listener, observer and timer this call attached
+ *   (review §14). `createAnimator` ties it to `destroy()`. Call it yourself before re-arming an
+ *   element you wired by hand — otherwise the old listeners stay live next to the new ones.
  * @public
  */
 declare function setupAnimationTriggers(api: PxAnimatorApi, trigger: PxTrigger, diag?: PxDiagnostics): () => void;
 
+/**
+ * THE PAGE-WIDE REGISTRY — every live animator in the window, whoever created it.
+ *
+ * Like lottie-web's `getRegisteredAnimations()`: a dev tool, a test, or a "pause everything
+ * while the tab is hidden" can reach every player without holding on to each `createAnimator`
+ * result. An animator joins when it is built and leaves on `destroy()`; play / pause / cancel /
+ * finish are announced to subscribers.
+ *
+ * ONE registry per window, whatever the bundling: the store hangs off `globalThis` under a
+ * `Symbol.for` key, so the ESM build in one script and the UMD build in another share it. It
+ * is also reachable by NAME — `globalThis.__pixodeskAnimators` — for tooling that does not
+ * import the library (a devtools panel reading a page it did not build). Web only: React
+ * Native players never touch it.
+ *
+ * EXPERIMENTAL (2026-09): not settled — the event names, what `getAll()` includes and the
+ * global's name may change without a major version. Documented as such in
+ * docs/library/web-player.md ("Every animator on the page").
+ */
+/** What changed for an animator in the page-wide registry. Experimental — may change. @public */
+type PxAnimatorsEvent = 'add' | 'remove' | 'play' | 'pause' | 'cancel' | 'finish';
+/** Called for every {@link PxAnimatorsEvent} of every animator in the window. Experimental — may change. @public */
+type PxAnimatorsListener = (event: PxAnimatorsEvent, animator: PxAnimatorApi) => void;
+/** The store itself — what `globalThis.__pixodeskAnimators` holds. Experimental — may change. @public */
+interface PxAnimatorRegistry {
+    /** Every live animator, in creation order. */
+    getAll(): ReadonlyArray<PxAnimatorApi>;
+    /** Announcements of add / remove / play / pause / cancel / finish; returns the unsubscribe. */
+    subscribe(listener: PxAnimatorsListener): () => void;
+}
+/** Every live animator in this window, in creation order. Experimental — may change. @public */
+declare function getAllAnimators(): ReadonlyArray<PxAnimatorApi>;
+/** Hear every animator in this window start, pause, cancel, finish, appear or go — returns
+ *  the unsubscribe. Experimental — may change. @public */
+declare function onAnimatorsChange(listener: PxAnimatorsListener): () => void;
+
 /**
  * Renders a PxNode tree to DOM elements.
  * @public @advanced
  */
 declare function renderNode(node: PxNode, defs?: PxDefinitions, diag?: PxDiagnostics): Element | null;
 
-export { PxAnimatorApi, type PxPrerenderedAnimatorOptions, renderNode, setupAnimationTriggers };
+export { PxAnimatorApi, type PxAnimatorRegistry, type PxAnimatorsEvent, type PxAnimatorsListener, type PxPrerenderedAnimatorOptions, getAllAnimators, onAnimatorsChange, renderNode, setupAnimationTriggers };