use-scroll-animate 1.4.0 → 2.0.0

package/dist/{index.esm.js → chunks/core-FUEi4ncH.js}

@@ -138,9 +138,8 @@ const PRESETS = {
     },
 };
 function resolvePreset(animation) {
-    var _a;
     if (typeof animation === 'string') {
-        return (_a = PRESETS[animation.trim()]) !== null && _a !== void 0 ? _a : PRESETS['fade-in-up'];
+        return PRESETS[animation.trim()] ?? PRESETS['fade-in-up'];
     }
     if (Array.isArray(animation)) {
         const combined = { from: {}, to: {} };
@@ -181,9 +180,8 @@ const EASING_MAP = {
     'heavy-bounce': 'cubic-bezier(0.68, -0.55, 0.265, 1.55)',
 };
 function resolveEasing(easing) {
-    var _a;
     if (typeof easing === 'string') {
-        return (_a = EASING_MAP[easing]) !== null && _a !== void 0 ? _a : easing;
+        return EASING_MAP[easing] ?? easing;
     }
     if (Array.isArray(easing)) {
         return `cubic-bezier(${easing.join(', ')})`;
@@ -217,6 +215,7 @@ const DEFAULT_CONFIG = {
     disabled: false,
     root: null,
     autoUnregister: true,
+    defaultEngine: 'auto',
 };
 const noop = () => undefined;
 /* ------------------------------------------------------------------ */
@@ -236,6 +235,23 @@ function prefersReducedMotion() {
     }
     return !!reducedMotionQuery && reducedMotionQuery.matches;
 }
+let scrollTimelineSupported;
+/**
+ * Whether the browser can run presets on a native scroll-driven timeline:
+ * `CSS.supports('animation-timeline: view()')` plus the `ViewTimeline`
+ * constructor used to attach it from JavaScript. Cached. SSR-safe.
+ */
+function supportsScrollTimeline() {
+    if (scrollTimelineSupported === undefined) {
+        scrollTimelineSupported =
+            hasDOM() &&
+                typeof CSS !== 'undefined' &&
+                typeof CSS.supports === 'function' &&
+                CSS.supports('animation-timeline: view()') &&
+                typeof globalThis.ViewTimeline === 'function';
+    }
+    return scrollTimelineSupported;
+}
 /* ------------------------------------------------------------------ */
 /* Option parsing                                                      */
 /* ------------------------------------------------------------------ */
@@ -252,23 +268,37 @@ function lengthValue(value) {
     const v = value.trim();
     return /^-?(\d+\.?\d*|\.\d+)$/.test(v) ? parseFloat(v) : v;
 }
-function parseDataAttributes(el, config) {
-    var _a;
-    const dataset = el.dataset || {};
+const DEFAULT_PROGRESS_VAR = '--sa-progress';
+const DEFAULT_VIEW_RANGE = ['entry 0%', 'entry 100%'];
+/** `''` (bare attribute) -> default name; `sa-progress` -> `--sa-progress`. */
+function normalizeVar(name) {
+    const v = name.trim();
+    if (!v)
+        return DEFAULT_PROGRESS_VAR;
+    return v.startsWith('--') ? v : `--${v}`;
+}
+/**
+ * @internal Read options from string attributes. `get(name)` returns the raw
+ * value of the attribute `name` (kebab-case, e.g. `root-margin`), `''` for a
+ * bare attribute and `undefined` when absent. Shared by `data-sa-*` and the
+ * `<scroll-animate>` element.
+ */
+function readOptions(get) {
     const opts = {};
-    if (dataset.saAnimation) {
-        const anim = dataset.saAnimation;
+    const anim = get('animation');
+    if (anim) {
         opts.animation = (anim.includes(',') ? anim.split(',').map((s) => s.trim()) : anim.trim());
     }
-    opts.duration = num(dataset.saDuration);
-    opts.delay = num(dataset.saDelay);
-    if (dataset.saEasing) {
-        const e = dataset.saEasing.trim();
+    opts.duration = num(get('duration'));
+    opts.delay = num(get('delay'));
+    const easing = get('easing');
+    if (easing) {
+        const e = easing.trim();
         if (e.startsWith('[')) {
             try {
                 opts.easing = JSON.parse(e);
             }
-            catch (_b) {
+            catch {
                 // Malformed JSON: fall back to the default easing instead of throwing
             }
         }
@@ -276,55 +306,95 @@ function parseDataAttributes(el, config) {
             opts.easing = e;
         }
     }
-    if (dataset.saThreshold) {
-        const t = dataset.saThreshold;
-        opts.threshold = t.includes(',')
-            ? t.split(',').map(parseFloat).filter(Number.isFinite)
-            : num(t);
+    const t = get('threshold');
+    if (t) {
+        opts.threshold = t.includes(',') ? t.split(',').map(parseFloat).filter(Number.isFinite) : num(t);
     }
-    if (dataset.saRootMargin)
-        opts.rootMargin = dataset.saRootMargin;
-    if (dataset.saRepeat !== undefined)
-        opts.repeat = dataset.saRepeat !== 'false';
-    if (dataset.saOnce !== undefined)
-        opts.once = dataset.saOnce !== 'false';
-    opts.offset = num(dataset.saOffset);
-    opts.stagger = num(dataset.saStagger);
-    if (dataset.saProgress)
-        opts.progressMode = dataset.saProgress.trim() === 'scroll' ? 'scroll' : 'ratio';
-    if (dataset.saParallaxX || dataset.saParallaxY || dataset.saParallaxRotate || dataset.saParallaxScale) {
+    const rootMargin = get('root-margin');
+    if (rootMargin)
+        opts.rootMargin = rootMargin;
+    const repeat = get('repeat');
+    if (repeat !== undefined)
+        opts.repeat = repeat !== 'false';
+    const once = get('once');
+    if (once !== undefined)
+        opts.once = once !== 'false';
+    opts.offset = num(get('offset'));
+    opts.stagger = num(get('stagger'));
+    const progressVar = get('progress-var');
+    if (progressVar !== undefined)
+        opts.progressVar = normalizeVar(progressVar);
+    const engine = get('engine')?.trim();
+    if (engine === 'auto' || engine === 'js' || engine === 'css')
+        opts.engine = engine;
+    const range = get('view-range');
+    if (range) {
+        const [start, end] = range.split(',').map((s) => s.trim());
+        if (start && end)
+            opts.viewRange = [start, end];
+    }
+    const exit = get('exit');
+    if (exit !== undefined) {
+        const e = exit.trim();
+        opts.exit = e === '' || e === 'true' ? true : e === 'false' ? false : (e.includes(',') ? e.split(',').map((s) => s.trim()) : e);
+    }
+    const progress = get('progress');
+    if (progress)
+        opts.progressMode = progress.trim() === 'scroll' ? 'scroll' : 'ratio';
+    const px = get('parallax-x');
+    const py = get('parallax-y');
+    const pr = get('parallax-rotate');
+    const ps = get('parallax-scale');
+    if (px || py || pr || ps) {
         opts.parallax = {
-            x: lengthValue(dataset.saParallaxX),
-            y: lengthValue(dataset.saParallaxY),
-            rotate: num(dataset.saParallaxRotate),
-            scale: num(dataset.saParallaxScale),
-            speed: (_a = num(dataset.saParallaxSpeed)) !== null && _a !== void 0 ? _a : 1,
+            x: lengthValue(px),
+            y: lengthValue(py),
+            rotate: num(pr),
+            scale: num(ps),
+            speed: num(get('parallax-speed')) ?? 1,
         };
     }
-    return mergeOptions(opts, config);
+    // Drop keys that were not set, so they don't override defaults when spread.
+    Object.keys(opts).forEach((k) => opts[k] === undefined && delete opts[k]);
+    return opts;
+}
+function parseDataAttributes(el, config) {
+    return mergeOptions(readOptions((name) => {
+        const v = el.getAttribute(`data-sa-${name}`);
+        return v === null ? undefined : v;
+    }), config);
 }
 function mergeOptions(opts, config) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
-    const repeat = (_a = opts.repeat) !== null && _a !== void 0 ? _a : config.defaultRepeat;
-    const threshold = (_b = opts.threshold) !== null && _b !== void 0 ? _b : config.defaultThreshold;
+    let engine = opts.engine ?? config.defaultEngine;
+    // 'auto' keeps time-based semantics when the element asks for them explicitly.
+    if (engine === 'auto' && (opts.duration !== undefined || opts.delay !== undefined || opts.offset !== undefined || (opts.stagger ?? 0) > 0)) {
+        engine = 'js';
+    }
+    const exit = opts.exit ?? false;
+    const repeat = opts.repeat ?? (exit ? true : config.defaultRepeat);
+    const threshold = opts.threshold ?? config.defaultThreshold;
     return {
-        animation: (_c = opts.animation) !== null && _c !== void 0 ? _c : config.defaultAnimation,
-        duration: (_d = opts.duration) !== null && _d !== void 0 ? _d : config.defaultDuration,
-        delay: (_e = opts.delay) !== null && _e !== void 0 ? _e : config.defaultDelay,
-        easing: (_f = opts.easing) !== null && _f !== void 0 ? _f : config.defaultEasing,
+        animation: opts.animation ?? config.defaultAnimation,
+        duration: opts.duration ?? config.defaultDuration,
+        delay: opts.delay ?? config.defaultDelay,
+        easing: opts.easing ?? config.defaultEasing,
         threshold: Array.isArray(threshold) && threshold.length === 0 ? config.defaultThreshold : threshold,
-        rootMargin: (_g = opts.rootMargin) !== null && _g !== void 0 ? _g : config.defaultRootMargin,
+        rootMargin: opts.rootMargin ?? config.defaultRootMargin,
         repeat,
-        once: (_h = opts.once) !== null && _h !== void 0 ? _h : (repeat ? false : config.defaultOnce),
-        offset: (_j = opts.offset) !== null && _j !== void 0 ? _j : config.defaultOffset,
-        stagger: (_k = opts.stagger) !== null && _k !== void 0 ? _k : 0,
-        parallax: (_l = opts.parallax) !== null && _l !== void 0 ? _l : {},
-        onStart: (_m = opts.onStart) !== null && _m !== void 0 ? _m : noop,
-        onComplete: (_o = opts.onComplete) !== null && _o !== void 0 ? _o : noop,
-        onEnter: (_p = opts.onEnter) !== null && _p !== void 0 ? _p : noop,
-        onLeave: (_q = opts.onLeave) !== null && _q !== void 0 ? _q : noop,
-        onProgress: (_r = opts.onProgress) !== null && _r !== void 0 ? _r : noop,
-        progressMode: (_s = opts.progressMode) !== null && _s !== void 0 ? _s : 'ratio',
+        once: opts.once ?? (repeat ? false : config.defaultOnce),
+        offset: opts.offset ?? config.defaultOffset,
+        stagger: opts.stagger ?? 0,
+        parallax: opts.parallax ?? {},
+        onStart: opts.onStart ?? noop,
+        onComplete: opts.onComplete ?? noop,
+        onEnter: opts.onEnter ?? noop,
+        onLeave: opts.onLeave ?? noop,
+        onProgress: opts.onProgress ?? noop,
+        progressMode: opts.progressMode ?? 'ratio',
+        progressVar: opts.progressVar ? normalizeVar(opts.progressVar) : '',
+        engine,
+        viewRange: opts.viewRange ?? DEFAULT_VIEW_RANGE,
+        exit,
     };
 }
 function resolveTargets(target) {
@@ -345,14 +415,13 @@ function resolveTargets(target) {
  * @internal
  */
 function applyOffset(rootMargin, offset) {
-    var _a, _b, _c;
     if (!offset)
         return rootMargin;
     const parts = (rootMargin || '0px').trim().split(/\s+/);
     const top = parts[0];
-    const right = (_a = parts[1]) !== null && _a !== void 0 ? _a : top;
-    const bottom = (_b = parts[2]) !== null && _b !== void 0 ? _b : top;
-    const left = (_c = parts[3]) !== null && _c !== void 0 ? _c : right;
+    const right = parts[1] ?? top;
+    const bottom = parts[2] ?? top;
+    const left = parts[3] ?? right;
     const m = /^(-?\d*\.?\d+)(px)?$/.exec(bottom);
     const base = m ? parseFloat(m[1]) : 0; // non-px bottoms (e.g. %) cannot be combined; offset wins
     return `${top} ${right} ${base - offset}px ${left}`;
@@ -361,7 +430,7 @@ function hasParallax(p) {
     return !!p && Object.keys(p).some((k) => p[k] !== undefined);
 }
 function needsProgress(opts) {
-    return hasParallax(opts.parallax) || opts.onProgress !== noop;
+    return hasParallax(opts.parallax) || opts.onProgress !== noop || !!opts.progressVar;
 }
 /**
  * True scroll progress of `el` through the viewport (or `root`): 0 when its top
@@ -390,8 +459,15 @@ function getScrollProgress(el, root) {
 /* ------------------------------------------------------------------ */
 /** The animation currently running on an element, so it can be cancelled/replaced. */
 const running = new WeakMap();
+/** Native engine: the scroll-linked exit animation, next to the entrance in `running`. */
+const exits = new WeakMap();
 const timers = new WeakMap();
 function cancelRunning(el) {
+    const exitAnim = exits.get(el);
+    if (exitAnim) {
+        exits.delete(el);
+        exitAnim.cancel();
+    }
     const anim = running.get(el);
     if (anim) {
         running.delete(el);
@@ -502,7 +578,7 @@ function stopAnimation(el, config = {}) {
 function motionDisabled(config) {
     return !!config.disabled || prefersReducedMotion();
 }
-function runAnimation(el, opts, config, staggerIndex = 0) {
+function runAnimation(el, opts, config, staggerIndex = 0, pending) {
     const { duration, delay, stagger, onStart, onComplete } = opts;
     const totalDelay = Math.max(0, delay + staggerIndex * stagger);
     cancelRunning(el);
@@ -518,8 +594,10 @@ function runAnimation(el, opts, config, staggerIndex = 0) {
         el.classList.remove(config.hiddenClass);
         el.classList.add(config.visibleClass);
         onStart(el);
+        pending?.add(el);
         timers.set(el, setTimeout(() => {
             timers.delete(el);
+            pending?.delete(el);
             onComplete(el);
         }, duration + totalDelay));
         return;
@@ -544,7 +622,7 @@ function runAnimation(el, opts, config, staggerIndex = 0) {
     try {
         anim = el.animate(built.keyframes, timing);
     }
-    catch (_a) {
+    catch {
         // Invalid user easing string (WAAPI throws a TypeError): fall back to 'ease'
         anim = el.animate(built.keyframes, { ...timing, easing: 'ease' });
     }
@@ -559,7 +637,7 @@ function runAnimation(el, opts, config, staggerIndex = 0) {
             try {
                 anim.commitStyles();
             }
-            catch (_a) {
+            catch {
                 setStyles(el, preset.to);
             }
             anim.cancel();
@@ -567,6 +645,69 @@ function runAnimation(el, opts, config, staggerIndex = 0) {
         onComplete(el);
     };
 }
+/**
+ * Native engine: attach the preset to a `ViewTimeline` of the element, so the
+ * browser drives it from scroll position. Returns `null` when that fails
+ * (caller falls back to the JS engine).
+ */
+function startNative(el, opts, onFrozen) {
+    if (typeof el.animate !== 'function')
+        return null;
+    const preset = resolvePreset(opts.animation);
+    const built = buildAnimation(preset, opts.easing);
+    let anim;
+    try {
+        const timeline = new globalThis.ViewTimeline({ subject: el, axis: 'block' });
+        const timing = {
+            fill: 'both',
+            easing: built.easing,
+            timeline,
+            rangeStart: opts.viewRange[0],
+            rangeEnd: opts.viewRange[1],
+        };
+        try {
+            anim = el.animate(built.keyframes, timing);
+        }
+        catch {
+            anim = el.animate(built.keyframes, { ...timing, easing: 'linear' });
+        }
+    }
+    catch {
+        return null;
+    }
+    running.set(el, anim);
+    if (opts.exit) {
+        // Reverse keyframes over the `exit` range; `fill: 'forwards'` so it has
+        // no effect before the element starts leaving.
+        const leave = resolvePreset(opts.exit === true ? opts.animation : opts.exit);
+        const out = buildAnimation({ from: leave.to, to: leave.from }, opts.easing);
+        try {
+            const timeline = new globalThis.ViewTimeline({ subject: el, axis: 'block' });
+            const timing = { fill: 'forwards', easing: out.easing, timeline, rangeStart: 'exit 0%', rangeEnd: 'exit 100%' };
+            exits.set(el, el.animate(out.keyframes, timing));
+        }
+        catch {
+            // Exit is cosmetic: ignore if unsupported.
+        }
+    }
+    const keep = opts.repeat || !opts.once;
+    anim.onfinish = () => {
+        // `once`: freeze the end state, so scrolling back up does not reverse it.
+        if (!keep && running.get(el) === anim) {
+            running.delete(el);
+            try {
+                anim.commitStyles();
+            }
+            catch {
+                setStyles(el, preset.to);
+            }
+            anim.cancel();
+            onFrozen?.();
+        }
+        opts.onComplete(el);
+    };
+    return anim;
+}
 function applyParallax(el, progress, parallax) {
     const { x = 0, y = 0, rotate = 0, scale = 1, speed = 1 } = parallax;
     const p = (progress - 0.5) * 2 * speed;
@@ -582,6 +723,26 @@ function applyParallax(el, progress, parallax) {
         transform += ` scale(${1 + (scale - 1) * p})`;
     el.style.transform = transform.trim();
 }
+/** Play the exit animation (entrance or `exit` preset, reversed), ending hidden. */
+function runExit(el, opts, config) {
+    if (config.useClassNames || typeof el.animate !== 'function') {
+        hideElement(el, config);
+        return;
+    }
+    cancelRunning(el);
+    const preset = resolvePreset(opts.exit === true ? opts.animation : opts.exit);
+    const built = buildAnimation({ from: preset.to, to: preset.from }, opts.easing);
+    const timing = { duration: opts.duration, easing: built.easing, fill: 'forwards' };
+    let anim;
+    try {
+        anim = el.animate(built.keyframes, timing);
+    }
+    catch {
+        anim = el.animate(built.keyframes, { ...timing, easing: 'ease' });
+    }
+    // Kept (filling) until the next entrance cancels it.
+    running.set(el, anim);
+}
 function hideElement(el, config) {
     cancelRunning(el);
     if (config.useClassNames) {
@@ -622,6 +783,12 @@ function createScrollAnimate(userConfig = {}) {
     const scrolling = new Set();
     let frame = 0;
     let listening = null;
+    // Active watch() MutationObservers, disconnected by destroy().
+    const watchers = new Set();
+    // Elements with a pending class-name completion timer started by this instance.
+    const pending = new Set();
+    // Elements whose entrance runs on a native scroll-driven timeline.
+    const natives = new Set();
     // Observers are shared between elements with the same root/threshold/rootMargin,
     // instead of one (or two) IntersectionObservers per element.
     const pools = new Map();
@@ -635,14 +802,22 @@ function createScrollAnimate(userConfig = {}) {
         return io;
     }
     function teardown(el, restore) {
-        var _a;
         const record = registry.get(el);
         if (!record)
             return;
         record.observer.unobserve(el);
-        (_a = record.progressObserver) === null || _a === void 0 ? void 0 : _a.unobserve(el);
+        record.progressObserver?.unobserve(el);
         registry.delete(el);
         untrack(el);
+        if (record.engine === 'css') {
+            // A scroll-linked animation would keep following the scroll: stop it and
+            // show the element (unless it finished and is just being released).
+            if (restore) {
+                natives.delete(el);
+                reveal(el, config);
+            }
+            return;
+        }
         // An element that never animated would otherwise stay invisible forever.
         if (restore && !record.animated)
             reveal(el, config);
@@ -656,6 +831,11 @@ function createScrollAnimate(userConfig = {}) {
     function emitProgress(el, record, progress) {
         const opts = record.options;
         opts.onProgress(el, progress);
+        if (opts.progressVar) {
+            const style = el.style;
+            if (style)
+                style.setProperty(opts.progressVar, String(+progress.toFixed(4)));
+        }
         if (hasParallax(opts.parallax) && !motionDisabled(config))
             applyParallax(el, progress, opts.parallax);
     }
@@ -706,7 +886,6 @@ function createScrollAnimate(userConfig = {}) {
     function onIntersect(entries) {
         const staggerCounts = new Map();
         entries.forEach((entry) => {
-            var _a;
             const el = entry.target;
             const record = registry.get(el);
             if (!record)
@@ -716,6 +895,29 @@ function createScrollAnimate(userConfig = {}) {
                 teardown(el, false);
                 return;
             }
+            if (record.engine === 'css') {
+                // The browser drives the animation; only lifecycle bookkeeping here.
+                if (entry.isIntersecting) {
+                    opts.onEnter(el);
+                    if (!record.animated) {
+                        record.animated = true;
+                        opts.onStart(el);
+                    }
+                    if (opts.once && !opts.repeat) {
+                        record.observer.unobserve(el);
+                        if (config.autoUnregister && !record.progressObserver) {
+                            finished.add(el);
+                            teardown(el, false);
+                        }
+                    }
+                }
+                else {
+                    opts.onLeave(el);
+                    if (opts.repeat)
+                        record.animated = false;
+                }
+                return;
+            }
             if (entry.isIntersecting) {
                 opts.onEnter(el);
                 if (record.animated && !opts.repeat)
@@ -725,10 +927,10 @@ function createScrollAnimate(userConfig = {}) {
                 let staggerIndex = 0;
                 if (opts.stagger > 0) {
                     const parent = el.parentElement;
-                    staggerIndex = (_a = staggerCounts.get(parent)) !== null && _a !== void 0 ? _a : 0;
+                    staggerIndex = staggerCounts.get(parent) ?? 0;
                     staggerCounts.set(parent, staggerIndex + 1);
                 }
-                runAnimation(el, opts, config, staggerIndex);
+                runAnimation(el, opts, config, staggerIndex, pending);
                 record.animated = true;
                 if (opts.once && !opts.repeat) {
                     // Keep the progress observer: parallax/onProgress must keep working.
@@ -744,8 +946,12 @@ function createScrollAnimate(userConfig = {}) {
             else {
                 opts.onLeave(el);
                 if (opts.repeat && record.animated) {
-                    if (!motionDisabled(config))
-                        hideElement(el, config);
+                    if (!motionDisabled(config)) {
+                        if (opts.exit)
+                            runExit(el, opts, config);
+                        else
+                            hideElement(el, config);
+                    }
                     record.animated = false;
                 }
             }
@@ -779,12 +985,14 @@ function createScrollAnimate(userConfig = {}) {
         }));
     }
     function attach(el, record, observeMain) {
-        var _a;
         record.observer = getObserver(record.options);
         if (observeMain)
             record.observer.observe(el);
         record.progressObserver = needsProgress(record.options) ? getProgressObserver(record.options) : undefined;
-        (_a = record.progressObserver) === null || _a === void 0 ? void 0 : _a.observe(el);
+        record.progressObserver?.observe(el);
+    }
+    function wantsNative(opts) {
+        return opts.engine !== 'js' && !config.useClassNames && !motionDisabled(config) && supportsScrollTimeline();
     }
     function observeElement(el, opts) {
         if (registry.has(el) || finished.has(el))
@@ -794,12 +1002,23 @@ function createScrollAnimate(userConfig = {}) {
             reveal(el, config);
             return;
         }
-        if (!motionDisabled(config))
+        const record = { element: el, options: opts, animated: false, engine: 'js' };
+        if (wantsNative(opts)) {
+            cancelRunning(el);
+            if (startNative(el, opts, () => natives.delete(el))) {
+                record.engine = 'css';
+                natives.add(el);
+            }
+        }
+        if (record.engine === 'js' && !motionDisabled(config))
             hideElement(el, config);
-        const record = { element: el, options: opts, animated: false };
         registry.set(el, record);
         attach(el, record, true);
     }
+    function observeDataElement(el) {
+        if (!registry.has(el))
+            observeElement(el, parseDataAttributes(el, config));
+    }
     const instance = {
         observe(target, options = {}) {
             pruneDetached();
@@ -813,20 +1032,71 @@ function createScrollAnimate(userConfig = {}) {
             });
         },
         init(rootElement) {
-            const scope = rootElement !== null && rootElement !== void 0 ? rootElement : (hasDOM() ? document : null);
+            const scope = rootElement ?? (hasDOM() ? document : null);
             if (!scope)
                 return;
             pruneDetached();
-            scope.querySelectorAll('[data-sa]').forEach((el) => {
-                if (!registry.has(el))
-                    observeElement(el, parseDataAttributes(el, config));
+            scope.querySelectorAll('[data-sa]').forEach(observeDataElement);
+        },
+        watch(rootElement) {
+            const scope = rootElement ?? (hasDOM() ? document : null);
+            if (!scope || typeof MutationObserver === 'undefined')
+                return noop;
+            instance.init(scope);
+            const observeTree = (node) => {
+                if (node.hasAttribute('data-sa'))
+                    observeDataElement(node);
+                node.querySelectorAll('[data-sa]').forEach(observeDataElement);
+            };
+            const mo = new MutationObserver((records) => {
+                let removed = false;
+                records.forEach((record) => {
+                    if (record.type === 'attributes') {
+                        const target = record.target;
+                        if (target.isConnected !== false)
+                            observeTree(target);
+                        return;
+                    }
+                    record.addedNodes.forEach((node) => {
+                        if (node instanceof Element && node.isConnected !== false)
+                            observeTree(node);
+                    });
+                    if (record.removedNodes.length)
+                        removed = true;
+                });
+                // Free elements that left the DOM (they can't animate any more).
+                if (removed)
+                    pruneDetached();
             });
+            mo.observe(scope, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-sa'] });
+            watchers.add(mo);
+            return () => {
+                mo.disconnect();
+                watchers.delete(mo);
+            };
         },
         destroy() {
+            watchers.forEach((mo) => mo.disconnect());
+            watchers.clear();
+            // Class-name mode: drop completion timers so onComplete never fires after destroy().
+            pending.forEach((el) => {
+                const timer = timers.get(el);
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timers.delete(el);
+                }
+            });
+            pending.clear();
             registry.forEach((record, el) => {
-                if (!record.animated)
+                if (!record.animated && record.engine !== 'css')
+                    reveal(el, config);
+            });
+            // Native scroll-linked animations still running: stop them, show content.
+            natives.forEach((el) => {
+                if (running.has(el))
                     reveal(el, config);
             });
+            natives.clear();
             pools.forEach((pool) => pool.forEach((io) => io.disconnect()));
             pools.clear();
             registry.clear();
@@ -851,7 +1121,7 @@ function createScrollAnimate(userConfig = {}) {
         },
         animate(target, options = {}) {
             const opts = mergeOptions(options, config);
-            resolveTargets(target).forEach((el) => runAnimation(el, opts, config, 0));
+            resolveTargets(target).forEach((el) => runAnimation(el, opts, config, 0, pending));
         },
         getObservedElements() {
             return Array.from(registry.values());
@@ -863,317 +1133,5 @@ function createScrollAnimate(userConfig = {}) {
     return instance;
 }
 
-/**
- * use-scroll-animate - Staggered children
- * Reveal a container's children one after another when the container scrolls
- * into view, optionally also animating children that are added later.
- */
-let fallback$1 = null;
-/**
- * Animate the children of `container` with a stagger once it enters the
- * viewport. Returns a cleanup function. SSR-safe (no-op without a DOM).
- *
- * @example
- * const stop = staggerChildren(document.querySelector('ul'), { stagger: 60, observeChildren: true });
- */
-function staggerChildren(container, options = {}, instance) {
-    if (!container || !hasDOM() || !supportsObserver())
-        return () => undefined; // leave content visible
-    const sa = instance || fallback$1 || (fallback$1 = createScrollAnimate());
-    const { stagger = 80, delay = 0, threshold = 0.1, rootMargin = '0px', observeChildren = false, ...rest } = options;
-    let items = Array.from(container.children);
-    let revealed = false;
-    const late = [];
-    items.forEach((child) => prepareElement(child));
-    const io = new IntersectionObserver((entries) => {
-        if (revealed || !entries.some((entry) => entry.isIntersecting))
-            return;
-        revealed = true;
-        io.disconnect();
-        items.forEach((child, i) => {
-            if (child.parentNode === container)
-                sa.animate(child, { ...rest, delay: delay + i * stagger });
-        });
-        items = [];
-    }, { threshold, rootMargin });
-    io.observe(container);
-    let mo;
-    if (observeChildren && typeof MutationObserver !== 'undefined') {
-        mo = new MutationObserver((records) => {
-            records.forEach((record) => {
-                record.addedNodes.forEach((node) => {
-                    if (!(node instanceof Element) || node.parentNode !== container)
-                        return;
-                    if (!revealed) {
-                        prepareElement(node);
-                        items.push(node);
-                    }
-                    else {
-                        // The core engine staggers siblings relative to the batch that
-                        // enters the viewport together.
-                        late.push(node);
-                        sa.observe(node, { ...rest, delay, stagger, threshold, rootMargin });
-                    }
-                });
-                record.removedNodes.forEach((node) => {
-                    if (!(node instanceof Element))
-                        return;
-                    items = items.filter((el) => el !== node);
-                    const i = late.indexOf(node);
-                    if (i >= 0) {
-                        late.splice(i, 1);
-                        sa.unobserve(node);
-                    }
-                });
-            });
-        });
-        mo.observe(container, { childList: true });
-    }
-    return () => {
-        io.disconnect();
-        mo === null || mo === void 0 ? void 0 : mo.disconnect();
-        late.forEach((el) => sa.unobserve(el));
-        late.length = 0;
-    };
-}
-
-/**
- * use-scroll-animate - Sequence / timeline helper
- * Chain animations on several targets, one after another (or overlapping).
- */
-let fallback = null;
-function plan(steps, defaults) {
-    const out = [];
-    let cursor = 0;
-    steps.forEach((step) => {
-        var _a, _b;
-        const { target, gap = 0, at, ...stepOpts } = step;
-        const opts = { ...defaults, ...stepOpts };
-        const duration = (_a = opts.duration) !== null && _a !== void 0 ? _a : 600;
-        const start = Math.max(0, at !== null && at !== void 0 ? at : cursor + gap) + ((_b = opts.delay) !== null && _b !== void 0 ? _b : 0);
-        let end = Math.max(cursor, start);
-        resolveTargets(target).forEach((el, i) => {
-            var _a;
-            const delay = start + i * ((_a = opts.stagger) !== null && _a !== void 0 ? _a : 0);
-            out.push({ el, opts: { ...opts, duration, delay, stagger: 0 }, end: delay + duration });
-            end = Math.max(end, delay + duration);
-        });
-        cursor = end;
-    });
-    return out;
-}
-/**
- * Build a timeline of animations.
- *
- * @example
- * sequence([
- *   { target: '.title', animation: 'fade-in-up' },
- *   { target: '.subtitle', animation: 'blur-in', gap: -300 },   // overlap by 300ms
- *   { target: '.card', animation: 'scale-up', stagger: 80 },
- * ], { trigger: '.hero' });
- */
-function sequence(steps, options = {}) {
-    var _a, _b;
-    const { trigger, instance, ...defaults } = options;
-    const sa = () => instance || fallback || (fallback = createScrollAnimate());
-    let io;
-    let active = [];
-    let settle;
-    const controller = {
-        play() {
-            controller.cancel();
-            if (!hasDOM())
-                return Promise.resolve();
-            active = plan(steps, defaults);
-            return new Promise((resolve) => {
-                let left = active.length;
-                settle = () => {
-                    settle = undefined;
-                    resolve();
-                };
-                if (!left)
-                    return settle();
-                const run = active;
-                run.forEach(({ el, opts }) => {
-                    const done = opts.onComplete;
-                    sa().animate(el, {
-                        ...opts,
-                        onComplete: (node) => {
-                            done === null || done === void 0 ? void 0 : done(node);
-                            if (run === active && --left === 0)
-                                settle === null || settle === void 0 ? void 0 : settle();
-                        },
-                    });
-                });
-            });
-        },
-        cancel() {
-            io === null || io === void 0 ? void 0 : io.disconnect();
-            io = undefined;
-            active.forEach(({ el }) => stopAnimation(el));
-            active = [];
-            settle === null || settle === void 0 ? void 0 : settle();
-        },
-        duration() {
-            return plan(steps, defaults).reduce((max, p) => Math.max(max, p.end), 0);
-        },
-    };
-    if (trigger && hasDOM() && supportsObserver()) {
-        const el = resolveTargets(trigger)[0];
-        if (el) {
-            plan(steps, defaults).forEach(({ el: target }) => prepareElement(target));
-            io = new IntersectionObserver((entries) => {
-                if (!entries.some((e) => e.isIntersecting))
-                    return;
-                io === null || io === void 0 ? void 0 : io.disconnect();
-                io = undefined;
-                controller.play();
-            }, { threshold: (_a = defaults.threshold) !== null && _a !== void 0 ? _a : 0.1, rootMargin: (_b = defaults.rootMargin) !== null && _b !== void 0 ? _b : '0px' });
-            io.observe(el);
-        }
-    }
-    return controller;
-}
-
-/**
- * use-scroll-animate - React Integration
- * Provides useScrollAnimate and useScrollStagger hooks for React applications.
- * `useScrollStagger({ observeChildren: true })` also animates children added later.
- *
- * Both hooks are thin wrappers around the core engine, so they share its
- * behaviour: `once`, `offset`, custom easing functions, parallax,
- * `prefers-reduced-motion` support, and proper cleanup on unmount.
- */
-const CALLBACKS = ['onStart', 'onComplete', 'onEnter', 'onLeave', 'onProgress'];
-/**
- * Wrap the callbacks that exist at mount so they always call the latest
- * version from the most recent render (avoids stale closures without
- * re-creating observers on every render).
- * @internal
- */
-function withLatestCallbacks(latest) {
-    const initial = latest.current || {};
-    const opts = { ...initial };
-    CALLBACKS.forEach((name) => {
-        if (typeof initial[name] === 'function') {
-            opts[name] = (...args) => { var _a, _b; return (_b = (_a = latest.current) === null || _a === void 0 ? void 0 : _a[name]) === null || _b === void 0 ? void 0 : _b.call(_a, ...args); };
-        }
-    });
-    return opts;
-}
-function createReactHooks(React) {
-    // Created lazily on the client so importing on the server is side-effect free.
-    let instance = null;
-    const getInstance = () => instance || (instance = createScrollAnimate());
-    function useScrollAnimate(options = {}) {
-        const ref = React.useRef(null);
-        const optionsRef = React.useRef(options);
-        optionsRef.current = options;
-        React.useEffect(() => {
-            const el = ref.current;
-            if (!el)
-                return;
-            const sa = getInstance();
-            sa.observe(el, withLatestCallbacks(optionsRef));
-            return () => sa.unobserve(el);
-        }, []);
-        return ref;
-    }
-    function useScrollStagger(options = {}) {
-        const ref = React.useRef(null);
-        const optionsRef = React.useRef(options);
-        optionsRef.current = options;
-        React.useEffect(() => {
-            const container = ref.current;
-            if (!container)
-                return;
-            return staggerChildren(container, withLatestCallbacks(optionsRef), getInstance());
-        }, []);
-        return ref;
-    }
-    return { useScrollAnimate, useScrollStagger };
-}
-
-/**
- * use-scroll-animate - Vue 3 Integration
- * Provides useScrollAnimate and useScrollStagger composables for Vue 3 applications.
- *
- * A thin wrapper around the core engine, so it shares its behaviour: `once`,
- * `offset`, custom easing functions, parallax, `prefers-reduced-motion`
- * support, and cleanup on unmount.
- */
-/** Support refs on components (`$el`) as well as plain elements. */
-function unwrap(value) {
-    if (value && typeof Element !== 'undefined' && !(value instanceof Element) && value.$el instanceof Element) {
-        return value.$el;
-    }
-    return value || null;
-}
-function createVueComposables(Vue) {
-    // Created lazily on the client so importing on the server is side-effect free.
-    let instance = null;
-    const getInstance = () => instance || (instance = createScrollAnimate());
-    function useScrollAnimate(options = {}) {
-        const animateRef = Vue.ref(null);
-        let el = null;
-        Vue.onMounted(() => {
-            const target = unwrap(animateRef.value);
-            if (!target)
-                return;
-            el = target;
-            getInstance().observe(el, options);
-        });
-        Vue.onUnmounted(() => {
-            if (el)
-                getInstance().unobserve(el);
-            el = null;
-        });
-        return { animateRef };
-    }
-    /** Stagger the children of `staggerRef`; `observeChildren: true` also animates children added later. */
-    function useScrollStagger(options = {}) {
-        const staggerRef = Vue.ref(null);
-        let stop;
-        Vue.onMounted(() => {
-            const target = unwrap(staggerRef.value);
-            if (target)
-                stop = staggerChildren(target, options, getInstance());
-        });
-        Vue.onUnmounted(() => {
-            stop === null || stop === void 0 ? void 0 : stop();
-            stop = undefined;
-        });
-        return { staggerRef };
-    }
-    return { useScrollAnimate, useScrollStagger };
-}
-
-/**
- * use-scroll-animate
- *
- * A lightweight, dependency-free scroll animation library for modern web
- * applications. Built with TypeScript, powered by IntersectionObserver and
- * the Web Animations API. Safe to import during SSR.
- *
- * @license MIT
- * @see https://github.com/HarrisonCN/use-scroll-animate
- */
-/**
- * Default singleton instance of ScrollAnimate.
- * Ready to use out of the box with sensible defaults.
- *
- * @example
- * ```js
- * import ScrollAnimate from 'use-scroll-animate';
- *
- * // Auto-initialize all elements with data-sa attribute
- * ScrollAnimate.init();
- *
- * // Or manually observe elements
- * ScrollAnimate.observe('.my-element', { animation: 'fade-in-up' });
- * ```
- */
-const ScrollAnimate = createScrollAnimate();
-
-export { EASING_MAP, PRESETS, createReactHooks, createScrollAnimate, createVueComposables, ScrollAnimate as default, getScrollProgress, resolveEasing, resolvePreset, sequence, staggerChildren };
-//# sourceMappingURL=index.esm.js.map
+export { EASING_MAP as E, PRESETS as P, stopAnimation as a, prefersReducedMotion as b, createScrollAnimate as c, resolveEasing as d, resolvePreset as e, supportsScrollTimeline as f, getScrollProgress as g, hasDOM as h, readOptions as i, prepareElement as p, resolveTargets as r, supportsObserver as s };
+//# sourceMappingURL=core-FUEi4ncH.js.map