use-scroll-animate 3.9.0 → 4.0.1

package/dist/index.cjs

@@ -4,114 +4,8 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var core = require('./chunks/core-qpECfEkb.cjs');
 var stagger = require('./chunks/stagger-CLc3j58T.cjs');
-
-/**
- * use-scroll-animate - Sequence / timeline helper
- * Chain animations on several targets, one after another (or overlapping).
- */
-let fallback = null;
-let warned = false;
-function plan(steps, defaults) {
-    const out = [];
-    let cursor = 0;
-    steps.forEach((step) => {
-        const { target, gap = 0, at, ...stepOpts } = step;
-        const opts = { ...defaults, ...stepOpts };
-        const duration = opts.duration ?? 600;
-        const start = Math.max(0, at ?? cursor + gap) + (opts.delay ?? 0);
-        let end = Math.max(cursor, start);
-        core.resolveTargets(target).forEach((el, i) => {
-            const delay = start + i * (opts.stagger ?? 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.
- *
- * @deprecated since 3.9, removed in 4.0 — use `timeline()` (`.to(target, preset, { at: '-=300' })`).
- *
- * @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 = {}) {
-    if (!warned && typeof console !== 'undefined') {
-        warned = true;
-        console.warn("[use-scroll-animate] sequence() is deprecated and will be removed in 4.0 — use timeline() from 'use-scroll-animate/components/timeline' (also exported from 'use-scroll-animate' in 4.0). See docs/upgrading-4.md.");
-    }
-    const { trigger, instance, ...defaults } = options;
-    const sa = () => instance || fallback || (fallback = core.createScrollAnimate());
-    let io;
-    let active = [];
-    let settle;
-    // Targets hidden while waiting for `trigger`; revealed if cancelled before it fires.
-    let prepared = [];
-    const controller = {
-        play() {
-            controller.cancel();
-            if (!core.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?.(node);
-                            if (run === active && --left === 0)
-                                settle?.();
-                        },
-                    });
-                });
-            });
-        },
-        cancel() {
-            io?.disconnect();
-            io = undefined;
-            prepared.forEach((el) => core.stopAnimation(el));
-            prepared = [];
-            active.forEach(({ el }) => core.stopAnimation(el));
-            active = [];
-            settle?.();
-        },
-        duration() {
-            return plan(steps, defaults).reduce((max, p) => Math.max(max, p.end), 0);
-        },
-    };
-    if (trigger && core.hasDOM() && core.supportsObserver()) {
-        const el = core.resolveTargets(trigger)[0];
-        if (el) {
-            prepared = plan(steps, defaults).map(({ el: target }) => target);
-            prepared.forEach((target) => core.prepareElement(target));
-            io = new IntersectionObserver((entries) => {
-                if (!entries.some((e) => e.isIntersecting))
-                    return;
-                io?.disconnect();
-                io = undefined;
-                prepared = []; // play() takes over from here
-                controller.play();
-            }, { threshold: defaults.threshold ?? 0.1, rootMargin: defaults.rootMargin ?? '0px' });
-            io.observe(el);
-        }
-    }
-    return controller;
-}
+var core$1 = require('./chunks/core-DXqZm5Il.cjs');
+require('./chunks/base-CXx7jZ-o.cjs');
 
 /**
  * use-scroll-animate - parallax() helper
@@ -242,7 +136,9 @@ exports.resolveEasing = core.resolveEasing;
 exports.resolvePreset = core.resolvePreset;
 exports.supportsScrollTimeline = core.supportsScrollTimeline;
 exports.staggerChildren = stagger.staggerChildren;
+exports.TIMELINE_PRESETS = core$1.TIMELINE_PRESETS;
+exports.resolvePosition = core$1.resolvePosition;
+exports.timeline = core$1.timeline;
 exports.default = ScrollAnimate;
 exports.parallax = parallax;
-exports.sequence = sequence;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/sequence.ts","../src/parallax.ts","../src/index.ts"],"sourcesContent":["/**\n * use-scroll-animate - Sequence / timeline helper\n * Chain animations on several targets, one after another (or overlapping).\n */\n\nimport type { AnimateOptions, ScrollAnimateInstance } from './types';\nimport { createScrollAnimate, hasDOM, prepareElement, resolveTargets, stopAnimation, supportsObserver } from './core';\n\nexport interface SequenceStep extends AnimateOptions {\n  /** Selector, Element, NodeList or Element[] to animate in this step */\n  target: string | Element | NodeList | Element[];\n  /** Pause (ms) after the previous step ends before this one starts. Negative values overlap. (default: 0) */\n  gap?: number;\n  /** Absolute start time (ms) on the timeline; overrides `gap` */\n  at?: number;\n}\n\nexport interface SequenceOptions extends AnimateOptions {\n  /** Play automatically (once) when this element/selector enters the viewport */\n  trigger?: string | Element;\n  /** Instance whose global config (easing, classes, `disabled`) is used */\n  instance?: ScrollAnimateInstance;\n}\n\nexport interface SequenceController {\n  /** Play (or replay) the timeline. Resolves when every step has completed, or on `cancel()`. */\n  play(): Promise<void>;\n  /** Stop the trigger and running animations; elements are left visible. */\n  cancel(): void;\n  /** Total duration of the timeline in ms (computed for the current DOM). */\n  duration(): number;\n}\n\nlet fallback: ScrollAnimateInstance | null = null;\nlet warned = false;\n\ntype Planned = { el: Element; opts: AnimateOptions; end: number };\n\nfunction plan(steps: SequenceStep[], defaults: AnimateOptions): Planned[] {\n  const out: Planned[] = [];\n  let cursor = 0;\n  steps.forEach((step) => {\n    const { target, gap = 0, at, ...stepOpts } = step;\n    const opts = { ...defaults, ...stepOpts };\n    const duration = opts.duration ?? 600;\n    const start = Math.max(0, at ?? cursor + gap) + (opts.delay ?? 0);\n    let end = Math.max(cursor, start);\n    resolveTargets(target).forEach((el, i) => {\n      const delay = start + i * (opts.stagger ?? 0);\n      out.push({ el, opts: { ...opts, duration, delay, stagger: 0 }, end: delay + duration });\n      end = Math.max(end, delay + duration);\n    });\n    cursor = end;\n  });\n  return out;\n}\n\n/**\n * Build a timeline of animations.\n *\n * @deprecated since 3.9, removed in 4.0 — use `timeline()` (`.to(target, preset, { at: '-=300' })`).\n *\n * @example\n * sequence([\n *   { target: '.title', animation: 'fade-in-up' },\n *   { target: '.subtitle', animation: 'blur-in', gap: -300 },   // overlap by 300ms\n *   { target: '.card', animation: 'scale-up', stagger: 80 },\n * ], { trigger: '.hero' });\n */\nexport function sequence(steps: SequenceStep[], options: SequenceOptions = {}): SequenceController {\n  if (!warned && typeof console !== 'undefined') {\n    warned = true;\n    console.warn(\"[use-scroll-animate] sequence() is deprecated and will be removed in 4.0 — use timeline() from 'use-scroll-animate/components/timeline' (also exported from 'use-scroll-animate' in 4.0). See docs/upgrading-4.md.\");\n  }\n  const { trigger, instance, ...defaults } = options;\n  const sa = () => instance || fallback || (fallback = createScrollAnimate());\n  let io: IntersectionObserver | undefined;\n  let active: Planned[] = [];\n  let settle: (() => void) | undefined;\n  // Targets hidden while waiting for `trigger`; revealed if cancelled before it fires.\n  let prepared: Element[] = [];\n\n  const controller: SequenceController = {\n    play() {\n      controller.cancel();\n      if (!hasDOM()) return Promise.resolve();\n      active = plan(steps, defaults);\n      return new Promise<void>((resolve) => {\n        let left = active.length;\n        settle = () => {\n          settle = undefined;\n          resolve();\n        };\n        if (!left) return settle();\n        const run = active;\n        run.forEach(({ el, opts }) => {\n          const done = opts.onComplete;\n          sa().animate(el, {\n            ...opts,\n            onComplete: (node) => {\n              done?.(node);\n              if (run === active && --left === 0) settle?.();\n            },\n          });\n        });\n      });\n    },\n\n    cancel() {\n      io?.disconnect();\n      io = undefined;\n      prepared.forEach((el) => stopAnimation(el));\n      prepared = [];\n      active.forEach(({ el }) => stopAnimation(el));\n      active = [];\n      settle?.();\n    },\n\n    duration() {\n      return plan(steps, defaults).reduce((max, p) => Math.max(max, p.end), 0);\n    },\n  };\n\n  if (trigger && hasDOM() && supportsObserver()) {\n    const el = resolveTargets(trigger)[0];\n    if (el) {\n      prepared = plan(steps, defaults).map(({ el: target }) => target);\n      prepared.forEach((target) => prepareElement(target));\n      io = new IntersectionObserver(\n        (entries) => {\n          if (!entries.some((e) => e.isIntersecting)) return;\n          io?.disconnect();\n          io = undefined;\n          prepared = []; // play() takes over from here\n          controller.play();\n        },\n        { threshold: defaults.threshold ?? 0.1, rootMargin: defaults.rootMargin ?? '0px' }\n      );\n      io.observe(el);\n    }\n  }\n\n  return controller;\n}\n","/**\n * use-scroll-animate - parallax() helper\n *\n * Moves elements at a different speed than the page while they cross the\n * viewport. Built on the same scroll progress as `progressVar` (0 when the\n * element's top enters at the bottom, 1 when its bottom leaves at the top):\n * the progress is written to a CSS custom property (default `--sa-parallax`)\n * and the offset is applied with the individual `translate` property, so it\n * composes with entrance animations and other `transform`s.\n */\n\nimport { getScrollProgress, hasDOM, prefersReducedMotion, resolveTargets, supportsObserver } from './core';\n\nexport interface ParallaxHelperOptions {\n  /**\n   * Total distance the element shifts while it crosses the viewport, as a\n   * fraction of the viewport size (`0.2` = 20vh on the y axis). Positive values\n   * lag behind the scroll (background-like), negative values move ahead of it\n   * (foreground-like). (default: `0.2`)\n   */\n  speed?: number;\n  /** `'y'` (default) or `'x'` (horizontal drift, in `vw`) */\n  axis?: 'x' | 'y';\n  /** CSS custom property receiving the progress (default: `'--sa-parallax'`) */\n  progressVar?: string;\n  /** Scroll container (default: the viewport) */\n  root?: Element | null;\n  /**\n   * Under `prefers-reduced-motion: reduce` no offset is applied (the progress\n   * variable is still written). Set to `false` to move anyway. (default: `true`)\n   */\n  respectReducedMotion?: boolean;\n}\n\nconst PASSIVE: AddEventListenerOptions = { passive: true };\n\n/**\n * Apply a scroll parallax to `target` (selector, Element, NodeList or array).\n * Returns a function that stops it and removes the inline styles it set.\n * SSR-safe (no-op without a DOM / IntersectionObserver).\n *\n * @example\n * const stop = parallax('.hero-bg', { speed: 0.3 });\n * parallax('.badge', { speed: -0.15, axis: 'x' });\n */\nexport function parallax(\n  target: string | Element | NodeList | Element[],\n  options: ParallaxHelperOptions = {}\n): () => void {\n  const els = resolveTargets(target);\n  if (!els.length || !hasDOM() || !supportsObserver()) return () => undefined;\n  const { speed = 0.2, axis = 'y', root = null, respectReducedMotion = true } = options;\n  const name = options.progressVar ? (options.progressVar.startsWith('--') ? options.progressVar : `--${options.progressVar}`) : '--sa-parallax';\n  const unit = axis === 'x' ? 'vw' : 'vh';\n  const visible = new Set<Element>();\n  let frame = 0;\n  let listening = false;\n  const scroller: EventTarget = root || window;\n\n  const apply = (el: Element) => {\n    const style = (el as HTMLElement).style;\n    if (!style) return;\n    const p = getScrollProgress(el, root);\n    style.setProperty(name, String(+p.toFixed(4)));\n    if (respectReducedMotion && prefersReducedMotion()) {\n      style.removeProperty('translate');\n      return;\n    }\n    const offset = `${+((p - 0.5) * speed * 100).toFixed(3)}${unit}`;\n    style.setProperty('translate', axis === 'x' ? `${offset} 0px` : `0px ${offset}`);\n  };\n\n  const update = () => {\n    frame = 0;\n    visible.forEach(apply);\n  };\n  const schedule = () => {\n    if (!frame) frame = requestAnimationFrame(update);\n  };\n  const listen = (on: boolean) => {\n    if (on === listening) return;\n    listening = on;\n    const method = on ? 'addEventListener' : 'removeEventListener';\n    scroller[method]('scroll', schedule, PASSIVE);\n    window[method]('resize', schedule, PASSIVE);\n    if (!on && frame) {\n      cancelAnimationFrame(frame);\n      frame = 0;\n    }\n  };\n\n  const io = new IntersectionObserver(\n    (entries) => {\n      entries.forEach((entry) => {\n        if (entry.isIntersecting) visible.add(entry.target);\n        else visible.delete(entry.target);\n        apply(entry.target); // report the edges even on fast scrolls\n      });\n      listen(visible.size > 0);\n    },\n    { threshold: 0, root }\n  );\n  els.forEach((el) => {\n    apply(el); // no jump before the first observer callback\n    io.observe(el);\n  });\n\n  return () => {\n    io.disconnect();\n    listen(false);\n    visible.clear();\n    els.forEach((el) => {\n      const style = (el as HTMLElement).style;\n      if (!style) return;\n      style.removeProperty('translate');\n      style.removeProperty(name);\n    });\n  };\n}\n","/**\n * use-scroll-animate\n *\n * A lightweight, dependency-free scroll animation library for modern web\n * applications. Built with TypeScript, powered by IntersectionObserver and\n * the Web Animations API (or the native scroll-driven timeline). Safe to\n * import during SSR. Framework integrations live in the subpath entries:\n * `use-scroll-animate/react`, `/vue`, `/svelte`, `/solid`, `/element`.\n *\n * @license MIT\n * @see https://github.com/HarrisonCN/use-scroll-animate\n */\n\nexport { createScrollAnimate, getScrollProgress, supportsScrollTimeline } from './core';\nexport { staggerChildren } from './stagger';\nexport { sequence } from './sequence';\nexport { parallax } from './parallax';\nexport { PRESETS, resolvePreset, resolveEasing, EASING_MAP } from './presets';\nexport type {\n  AnimationPreset,\n  EasingType,\n  AnimationKeyframe,\n  CustomAnimation,\n  ProgressMode,\n  ScrollEngine,\n  AnimateOptions,\n  ScrollAnimateConfig,\n  AnimatedElement,\n  ScrollAnimateInstance,\n} from './types';\nexport type { StaggerOptions } from './stagger';\nexport type { ParallaxHelperOptions } from './parallax';\nexport type { SequenceStep, SequenceOptions, SequenceController } from './sequence';\n\n// Default export: a ready-to-use singleton instance\nimport { createScrollAnimate } from './core';\n\n/**\n * Default singleton instance of ScrollAnimate.\n * Ready to use out of the box with sensible defaults.\n *\n * @example\n * ```js\n * import ScrollAnimate from 'use-scroll-animate';\n *\n * // Auto-initialize all elements with data-sa attribute\n * ScrollAnimate.init();\n *\n * // Or manually observe elements\n * ScrollAnimate.observe('.my-element', { animation: 'fade-in-up' });\n * ```\n */\nconst ScrollAnimate = /* @__PURE__ */ createScrollAnimate();\nexport default ScrollAnimate;\n"],"names":["resolveTargets","createScrollAnimate","hasDOM","stopAnimation","supportsObserver","prepareElement","getScrollProgress","prefersReducedMotion"],"mappings":"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"}
+{"version":3,"file":"index.cjs","sources":["../src/parallax.ts","../src/index.ts"],"sourcesContent":["/**\n * use-scroll-animate - parallax() helper\n *\n * Moves elements at a different speed than the page while they cross the\n * viewport. Built on the same scroll progress as `progressVar` (0 when the\n * element's top enters at the bottom, 1 when its bottom leaves at the top):\n * the progress is written to a CSS custom property (default `--sa-parallax`)\n * and the offset is applied with the individual `translate` property, so it\n * composes with entrance animations and other `transform`s.\n */\n\nimport { getScrollProgress, hasDOM, prefersReducedMotion, resolveTargets, supportsObserver } from './core';\n\nexport interface ParallaxHelperOptions {\n  /**\n   * Total distance the element shifts while it crosses the viewport, as a\n   * fraction of the viewport size (`0.2` = 20vh on the y axis). Positive values\n   * lag behind the scroll (background-like), negative values move ahead of it\n   * (foreground-like). (default: `0.2`)\n   */\n  speed?: number;\n  /** `'y'` (default) or `'x'` (horizontal drift, in `vw`) */\n  axis?: 'x' | 'y';\n  /** CSS custom property receiving the progress (default: `'--sa-parallax'`) */\n  progressVar?: string;\n  /** Scroll container (default: the viewport) */\n  root?: Element | null;\n  /**\n   * Under `prefers-reduced-motion: reduce` no offset is applied (the progress\n   * variable is still written). Set to `false` to move anyway. (default: `true`)\n   */\n  respectReducedMotion?: boolean;\n}\n\nconst PASSIVE: AddEventListenerOptions = { passive: true };\n\n/**\n * Apply a scroll parallax to `target` (selector, Element, NodeList or array).\n * Returns a function that stops it and removes the inline styles it set.\n * SSR-safe (no-op without a DOM / IntersectionObserver).\n *\n * @example\n * const stop = parallax('.hero-bg', { speed: 0.3 });\n * parallax('.badge', { speed: -0.15, axis: 'x' });\n */\nexport function parallax(\n  target: string | Element | NodeList | Element[],\n  options: ParallaxHelperOptions = {}\n): () => void {\n  const els = resolveTargets(target);\n  if (!els.length || !hasDOM() || !supportsObserver()) return () => undefined;\n  const { speed = 0.2, axis = 'y', root = null, respectReducedMotion = true } = options;\n  const name = options.progressVar ? (options.progressVar.startsWith('--') ? options.progressVar : `--${options.progressVar}`) : '--sa-parallax';\n  const unit = axis === 'x' ? 'vw' : 'vh';\n  const visible = new Set<Element>();\n  let frame = 0;\n  let listening = false;\n  const scroller: EventTarget = root || window;\n\n  const apply = (el: Element) => {\n    const style = (el as HTMLElement).style;\n    if (!style) return;\n    const p = getScrollProgress(el, root);\n    style.setProperty(name, String(+p.toFixed(4)));\n    if (respectReducedMotion && prefersReducedMotion()) {\n      style.removeProperty('translate');\n      return;\n    }\n    const offset = `${+((p - 0.5) * speed * 100).toFixed(3)}${unit}`;\n    style.setProperty('translate', axis === 'x' ? `${offset} 0px` : `0px ${offset}`);\n  };\n\n  const update = () => {\n    frame = 0;\n    visible.forEach(apply);\n  };\n  const schedule = () => {\n    if (!frame) frame = requestAnimationFrame(update);\n  };\n  const listen = (on: boolean) => {\n    if (on === listening) return;\n    listening = on;\n    const method = on ? 'addEventListener' : 'removeEventListener';\n    scroller[method]('scroll', schedule, PASSIVE);\n    window[method]('resize', schedule, PASSIVE);\n    if (!on && frame) {\n      cancelAnimationFrame(frame);\n      frame = 0;\n    }\n  };\n\n  const io = new IntersectionObserver(\n    (entries) => {\n      entries.forEach((entry) => {\n        if (entry.isIntersecting) visible.add(entry.target);\n        else visible.delete(entry.target);\n        apply(entry.target); // report the edges even on fast scrolls\n      });\n      listen(visible.size > 0);\n    },\n    { threshold: 0, root }\n  );\n  els.forEach((el) => {\n    apply(el); // no jump before the first observer callback\n    io.observe(el);\n  });\n\n  return () => {\n    io.disconnect();\n    listen(false);\n    visible.clear();\n    els.forEach((el) => {\n      const style = (el as HTMLElement).style;\n      if (!style) return;\n      style.removeProperty('translate');\n      style.removeProperty(name);\n    });\n  };\n}\n","/**\n * use-scroll-animate\n *\n * A lightweight, dependency-free scroll animation library for modern web\n * applications. Built with TypeScript, powered by IntersectionObserver and\n * the Web Animations API (or the native scroll-driven timeline). Safe to\n * import during SSR. Framework integrations live in the subpath entries:\n * `use-scroll-animate/react`, `/vue`, `/svelte`, `/solid`, `/element`.\n *\n * @license MIT\n * @see https://github.com/HarrisonCN/use-scroll-animate\n */\n\nexport { createScrollAnimate, getScrollProgress, supportsScrollTimeline } from './core';\nexport { staggerChildren } from './stagger';\nexport { timeline, resolvePosition, TIMELINE_PRESETS } from './components/timeline/core';\nexport { parallax } from './parallax';\nexport { PRESETS, resolvePreset, resolveEasing, EASING_MAP } from './presets';\nexport type {\n  AnimationPreset,\n  EasingType,\n  AnimationKeyframe,\n  CustomAnimation,\n  ProgressMode,\n  ScrollEngine,\n  AnimateOptions,\n  ScrollAnimateConfig,\n  AnimatedElement,\n  ScrollAnimateInstance,\n} from './types';\nexport type { StaggerOptions } from './stagger';\nexport type { ParallaxHelperOptions } from './parallax';\nexport type { Timeline, TimelineOptions, TimelineStepOptions, TimelinePosition, ScrubOptions } from './components/timeline/core';\n\n// Default export: a ready-to-use singleton instance\nimport { createScrollAnimate } from './core';\n\n/**\n * Default singleton instance of ScrollAnimate.\n * Ready to use out of the box with sensible defaults.\n *\n * @example\n * ```js\n * import ScrollAnimate from 'use-scroll-animate';\n *\n * // Auto-initialize all elements with data-sa attribute\n * ScrollAnimate.init();\n *\n * // Or manually observe elements\n * ScrollAnimate.observe('.my-element', { animation: 'fade-in-up' });\n * ```\n */\nconst ScrollAnimate = /* @__PURE__ */ createScrollAnimate();\nexport default ScrollAnimate;\n"],"names":["resolveTargets","hasDOM","supportsObserver","getScrollProgress","prefersReducedMotion","createScrollAnimate"],"mappings":"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"}

package/dist/index.d.cts

@@ -219,45 +219,85 @@ interface StaggerOptions extends AnimateOptions {
 declare function staggerChildren(container: Element | null | undefined, options?: StaggerOptions, instance?: ScrollAnimateInstance): () => void;
 
 /**
- * use-scroll-animate - Sequence / timeline helper
- * Chain animations on several targets, one after another (or overlapping).
+ * Where a step starts on a timeline:
+ * - a number: absolute time in ms
+ * - `'>'` (default): when the previous step ends · `'<'`: when it starts
+ * - `'+=200'` / `'-=200'`: after / overlapping the previous end
+ * - `'<+=100'`: 100ms after the previous step's start
+ * - `'intro'` / `'intro+=150'`: at (or relative to) a label
  */
-
-interface SequenceStep extends AnimateOptions {
-    /** Selector, Element, NodeList or Element[] to animate in this step */
-    target: string | Element | NodeList | Element[];
-    /** Pause (ms) after the previous step ends before this one starts. Negative values overlap. (default: 0) */
-    gap?: number;
-    /** Absolute start time (ms) on the timeline; overrides `gap` */
-    at?: number;
+type TimelinePosition = number | string;
+interface TimelineStepOptions {
+    /** Duration in ms (default: timeline default, 600). */
+    duration?: number;
+    /** CSS easing (default `cubic-bezier(0.22, 1, 0.36, 1)`). */
+    easing?: string;
+    /** Start position, see `TimelinePosition`. */
+    at?: TimelinePosition;
+    /** ms between targets when the selector matches several elements. */
+    stagger?: number;
 }
-interface SequenceOptions extends AnimateOptions {
-    /** Play automatically (once) when this element/selector enters the viewport */
-    trigger?: string | Element;
-    /** Instance whose global config (easing, classes, `disabled`) is used */
-    instance?: ScrollAnimateInstance;
+interface TimelineOptions {
+    /** Defaults for every step. */
+    defaults?: Pick<TimelineStepOptions, 'duration' | 'easing' | 'stagger'>;
+    /** Playback rate (1 = normal). */
+    speed?: number;
+    /** Called after `play()` reaches the end (or the start when reversed). */
+    onComplete?: () => void;
+    /** Called on every frame with progress 0–1. */
+    onUpdate?: (progress: number) => void;
 }
-interface SequenceController {
-    /** Play (or replay) the timeline. Resolves when every step has completed, or on `cancel()`. */
-    play(): Promise<void>;
-    /** Stop the trigger and running animations; elements are left visible. */
+interface ScrubOptions {
+    /** Scroll offset (px) before the source's top reaches the viewport bottom where progress starts. */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). */
+    smooth?: number;
+}
+interface Timeline {
+    /** Total length in ms. */
+    readonly duration: number;
+    /** Label positions in ms. */
+    readonly labels: Readonly<Record<string, number>>;
+    /** Current playhead in ms. */
+    readonly time: number;
+    /** Add a step: animate `target` with keyframes or a preset name (`fade-up`, `scale`…). */
+    to(target: string | Element | Element[] | NodeList, frames: Keyframe[] | string, options?: TimelineStepOptions): Timeline;
+    /** Name a position (default: the current end). */
+    label(name: string, at?: TimelinePosition): Timeline;
+    /** Run `fn` when the playhead passes `at`. */
+    call(fn: () => void, at?: TimelinePosition): Timeline;
+    /** Play forwards from the playhead (from 0 when at the end). Resolves at the end. */
+    play(from?: TimelinePosition): Promise<void>;
+    /** Play backwards to 0. */
+    reverse(): Promise<void>;
+    pause(): Timeline;
+    /** Jump to a time (ms) or label. */
+    seek(to: TimelinePosition): Timeline;
+    /** Get or set progress 0–1. */
+    progress(p?: number): number;
+    /** Tie progress to the scroll position of `source` (it moves through the viewport). Returns a stop function. */
+    scrub(source: Element, options?: ScrubOptions): () => void;
+    /** Stop and drop every animation (elements keep their last frame). */
     cancel(): void;
-    /** Total duration of the timeline in ms (computed for the current DOM). */
-    duration(): number;
 }
+/** Keyframe presets usable by name in `to()` and `data-tl`. */
+declare const TIMELINE_PRESETS: Record<string, Keyframe[]>;
+/** Resolve a position against the previous step and labels (pure). */
+declare function resolvePosition(pos: TimelinePosition | undefined, end: number, prevStart: number, labels?: Record<string, number>): number;
 /**
- * Build a timeline of animations.
- *
- * @deprecated since 3.9, removed in 4.0 — use `timeline()` (`.to(target, preset, { at: '-=300' })`).
+ * Choreograph animations on one clock: chain, overlap, label, seek, reverse and
+ * scrub them with scroll. Built on WAAPI (paused animations driven by one
+ * playhead); without WAAPI or under reduced motion it jumps to the end state.
  *
  * @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' });
+ * const tl = timeline({ defaults: { duration: 500 } })
+ *   .to('.title', 'fade-up')
+ *   .label('cards')
+ *   .to('.card', 'scale', { stagger: 80, at: '-=200' })
+ *   .to('.cta', [{ opacity: 0 }, { opacity: 1 }], { at: 'cards+=400' });
+ * tl.play();             // or tl.scrub(document.querySelector('.hero'))
  */
-declare function sequence(steps: SequenceStep[], options?: SequenceOptions): SequenceController;
+declare function timeline(options?: TimelineOptions): Timeline;
 
 /**
  * use-scroll-animate - parallax() helper
@@ -332,5 +372,5 @@ declare function resolveEasing(easing: EasingType): string;
  */
 declare const ScrollAnimate: ScrollAnimateInstance;
 
-export { EASING_MAP, PRESETS, createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, resolveEasing, resolvePreset, sequence, staggerChildren, supportsScrollTimeline };
-export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxHelperOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, ScrollEngine, SequenceController, SequenceOptions, SequenceStep, StaggerOptions };
+export { EASING_MAP, PRESETS, TIMELINE_PRESETS, createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, resolveEasing, resolvePosition, resolvePreset, staggerChildren, supportsScrollTimeline, timeline };
+export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxHelperOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, ScrollEngine, ScrubOptions, StaggerOptions, Timeline, TimelineOptions, TimelinePosition, TimelineStepOptions };

package/dist/index.d.ts

@@ -219,45 +219,85 @@ interface StaggerOptions extends AnimateOptions {
 declare function staggerChildren(container: Element | null | undefined, options?: StaggerOptions, instance?: ScrollAnimateInstance): () => void;
 
 /**
- * use-scroll-animate - Sequence / timeline helper
- * Chain animations on several targets, one after another (or overlapping).
+ * Where a step starts on a timeline:
+ * - a number: absolute time in ms
+ * - `'>'` (default): when the previous step ends · `'<'`: when it starts
+ * - `'+=200'` / `'-=200'`: after / overlapping the previous end
+ * - `'<+=100'`: 100ms after the previous step's start
+ * - `'intro'` / `'intro+=150'`: at (or relative to) a label
  */
-
-interface SequenceStep extends AnimateOptions {
-    /** Selector, Element, NodeList or Element[] to animate in this step */
-    target: string | Element | NodeList | Element[];
-    /** Pause (ms) after the previous step ends before this one starts. Negative values overlap. (default: 0) */
-    gap?: number;
-    /** Absolute start time (ms) on the timeline; overrides `gap` */
-    at?: number;
+type TimelinePosition = number | string;
+interface TimelineStepOptions {
+    /** Duration in ms (default: timeline default, 600). */
+    duration?: number;
+    /** CSS easing (default `cubic-bezier(0.22, 1, 0.36, 1)`). */
+    easing?: string;
+    /** Start position, see `TimelinePosition`. */
+    at?: TimelinePosition;
+    /** ms between targets when the selector matches several elements. */
+    stagger?: number;
 }
-interface SequenceOptions extends AnimateOptions {
-    /** Play automatically (once) when this element/selector enters the viewport */
-    trigger?: string | Element;
-    /** Instance whose global config (easing, classes, `disabled`) is used */
-    instance?: ScrollAnimateInstance;
+interface TimelineOptions {
+    /** Defaults for every step. */
+    defaults?: Pick<TimelineStepOptions, 'duration' | 'easing' | 'stagger'>;
+    /** Playback rate (1 = normal). */
+    speed?: number;
+    /** Called after `play()` reaches the end (or the start when reversed). */
+    onComplete?: () => void;
+    /** Called on every frame with progress 0–1. */
+    onUpdate?: (progress: number) => void;
 }
-interface SequenceController {
-    /** Play (or replay) the timeline. Resolves when every step has completed, or on `cancel()`. */
-    play(): Promise<void>;
-    /** Stop the trigger and running animations; elements are left visible. */
+interface ScrubOptions {
+    /** Scroll offset (px) before the source's top reaches the viewport bottom where progress starts. */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). */
+    smooth?: number;
+}
+interface Timeline {
+    /** Total length in ms. */
+    readonly duration: number;
+    /** Label positions in ms. */
+    readonly labels: Readonly<Record<string, number>>;
+    /** Current playhead in ms. */
+    readonly time: number;
+    /** Add a step: animate `target` with keyframes or a preset name (`fade-up`, `scale`…). */
+    to(target: string | Element | Element[] | NodeList, frames: Keyframe[] | string, options?: TimelineStepOptions): Timeline;
+    /** Name a position (default: the current end). */
+    label(name: string, at?: TimelinePosition): Timeline;
+    /** Run `fn` when the playhead passes `at`. */
+    call(fn: () => void, at?: TimelinePosition): Timeline;
+    /** Play forwards from the playhead (from 0 when at the end). Resolves at the end. */
+    play(from?: TimelinePosition): Promise<void>;
+    /** Play backwards to 0. */
+    reverse(): Promise<void>;
+    pause(): Timeline;
+    /** Jump to a time (ms) or label. */
+    seek(to: TimelinePosition): Timeline;
+    /** Get or set progress 0–1. */
+    progress(p?: number): number;
+    /** Tie progress to the scroll position of `source` (it moves through the viewport). Returns a stop function. */
+    scrub(source: Element, options?: ScrubOptions): () => void;
+    /** Stop and drop every animation (elements keep their last frame). */
     cancel(): void;
-    /** Total duration of the timeline in ms (computed for the current DOM). */
-    duration(): number;
 }
+/** Keyframe presets usable by name in `to()` and `data-tl`. */
+declare const TIMELINE_PRESETS: Record<string, Keyframe[]>;
+/** Resolve a position against the previous step and labels (pure). */
+declare function resolvePosition(pos: TimelinePosition | undefined, end: number, prevStart: number, labels?: Record<string, number>): number;
 /**
- * Build a timeline of animations.
- *
- * @deprecated since 3.9, removed in 4.0 — use `timeline()` (`.to(target, preset, { at: '-=300' })`).
+ * Choreograph animations on one clock: chain, overlap, label, seek, reverse and
+ * scrub them with scroll. Built on WAAPI (paused animations driven by one
+ * playhead); without WAAPI or under reduced motion it jumps to the end state.
  *
  * @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' });
+ * const tl = timeline({ defaults: { duration: 500 } })
+ *   .to('.title', 'fade-up')
+ *   .label('cards')
+ *   .to('.card', 'scale', { stagger: 80, at: '-=200' })
+ *   .to('.cta', [{ opacity: 0 }, { opacity: 1 }], { at: 'cards+=400' });
+ * tl.play();             // or tl.scrub(document.querySelector('.hero'))
  */
-declare function sequence(steps: SequenceStep[], options?: SequenceOptions): SequenceController;
+declare function timeline(options?: TimelineOptions): Timeline;
 
 /**
  * use-scroll-animate - parallax() helper
@@ -332,5 +372,5 @@ declare function resolveEasing(easing: EasingType): string;
  */
 declare const ScrollAnimate: ScrollAnimateInstance;
 
-export { EASING_MAP, PRESETS, createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, resolveEasing, resolvePreset, sequence, staggerChildren, supportsScrollTimeline };
-export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxHelperOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, ScrollEngine, SequenceController, SequenceOptions, SequenceStep, StaggerOptions };
+export { EASING_MAP, PRESETS, TIMELINE_PRESETS, createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, resolveEasing, resolvePosition, resolvePreset, staggerChildren, supportsScrollTimeline, timeline };
+export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxHelperOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, ScrollEngine, ScrubOptions, StaggerOptions, Timeline, TimelineOptions, TimelinePosition, TimelineStepOptions };

package/dist/index.js

@@ -1,114 +1,8 @@
-import { h as hasDOM, s as supportsObserver, b as resolveTargets, p as prepareElement, a as stopAnimation, c as createScrollAnimate, g as getScrollProgress, d as prefersReducedMotion } from './chunks/core-mV_TPgG_.js';
+import { b as resolveTargets, h as hasDOM, s as supportsObserver, g as getScrollProgress, d as prefersReducedMotion, c as createScrollAnimate } from './chunks/core-mV_TPgG_.js';
 export { E as EASING_MAP, P as PRESETS, e as resolveEasing, f as resolvePreset, i as supportsScrollTimeline } from './chunks/core-mV_TPgG_.js';
 export { s as staggerChildren } from './chunks/stagger-BFAhKknX.js';
-
-/**
- * use-scroll-animate - Sequence / timeline helper
- * Chain animations on several targets, one after another (or overlapping).
- */
-let fallback = null;
-let warned = false;
-function plan(steps, defaults) {
-    const out = [];
-    let cursor = 0;
-    steps.forEach((step) => {
-        const { target, gap = 0, at, ...stepOpts } = step;
-        const opts = { ...defaults, ...stepOpts };
-        const duration = opts.duration ?? 600;
-        const start = Math.max(0, at ?? cursor + gap) + (opts.delay ?? 0);
-        let end = Math.max(cursor, start);
-        resolveTargets(target).forEach((el, i) => {
-            const delay = start + i * (opts.stagger ?? 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.
- *
- * @deprecated since 3.9, removed in 4.0 — use `timeline()` (`.to(target, preset, { at: '-=300' })`).
- *
- * @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 = {}) {
-    if (!warned && typeof console !== 'undefined') {
-        warned = true;
-        console.warn("[use-scroll-animate] sequence() is deprecated and will be removed in 4.0 — use timeline() from 'use-scroll-animate/components/timeline' (also exported from 'use-scroll-animate' in 4.0). See docs/upgrading-4.md.");
-    }
-    const { trigger, instance, ...defaults } = options;
-    const sa = () => instance || fallback || (fallback = createScrollAnimate());
-    let io;
-    let active = [];
-    let settle;
-    // Targets hidden while waiting for `trigger`; revealed if cancelled before it fires.
-    let prepared = [];
-    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?.(node);
-                            if (run === active && --left === 0)
-                                settle?.();
-                        },
-                    });
-                });
-            });
-        },
-        cancel() {
-            io?.disconnect();
-            io = undefined;
-            prepared.forEach((el) => stopAnimation(el));
-            prepared = [];
-            active.forEach(({ el }) => stopAnimation(el));
-            active = [];
-            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) {
-            prepared = plan(steps, defaults).map(({ el: target }) => target);
-            prepared.forEach((target) => prepareElement(target));
-            io = new IntersectionObserver((entries) => {
-                if (!entries.some((e) => e.isIntersecting))
-                    return;
-                io?.disconnect();
-                io = undefined;
-                prepared = []; // play() takes over from here
-                controller.play();
-            }, { threshold: defaults.threshold ?? 0.1, rootMargin: defaults.rootMargin ?? '0px' });
-            io.observe(el);
-        }
-    }
-    return controller;
-}
+export { T as TIMELINE_PRESETS, r as resolvePosition, t as timeline } from './chunks/core-Co-6AL0h.js';
+import './chunks/base-ZARFccur.js';
 
 /**
  * use-scroll-animate - parallax() helper
@@ -231,5 +125,5 @@ function parallax(target, options = {}) {
  */
 const ScrollAnimate = /* @__PURE__ */ createScrollAnimate();
 
-export { createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, sequence };
+export { createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax };
 //# sourceMappingURL=index.js.map