af-motion 0.0.0-stage → 1.0.0

package/dist/easing/easings.d.ts

@@ -0,0 +1,44 @@
+import type { EasingFunction } from "../core/animation.js";
+export declare const linear: EasingFunction;
+export declare const easeInQuad: EasingFunction;
+export declare const easeOutQuad: EasingFunction;
+export declare const easeInOutQuad: EasingFunction;
+export declare const easeInCubic: EasingFunction;
+export declare const easeOutCubic: EasingFunction;
+export declare const easeInOutCubic: EasingFunction;
+export declare const easeInSine: EasingFunction;
+export declare const easeOutSine: EasingFunction;
+export declare const easeInOutSine: EasingFunction;
+export declare const easeOutExpo: EasingFunction;
+/** Overshoots 1 mid-animation by design; only the input is clamped. */
+export declare const easeOutBack: EasingFunction;
+export interface EasingRegistry {
+    linear: EasingFunction;
+    easeInQuad: EasingFunction;
+    easeOutQuad: EasingFunction;
+    easeInOutQuad: EasingFunction;
+    easeInCubic: EasingFunction;
+    easeOutCubic: EasingFunction;
+    easeInOutCubic: EasingFunction;
+    easeInSine: EasingFunction;
+    easeOutSine: EasingFunction;
+    easeInOutSine: EasingFunction;
+    easeOutExpo: EasingFunction;
+    easeOutBack: EasingFunction;
+}
+export type EasingName = keyof EasingRegistry;
+export declare const easings: Readonly<EasingRegistry>;
+export type EasingOption = EasingFunction | string;
+export interface EasingRegistryApi {
+    /** Registers or replaces a custom easing by name. Built-in names are reserved. */
+    register(name: string, easing: EasingFunction): void;
+    /** Retrieves a built-in or registered easing; returns undefined when the name is unknown. */
+    get(name: string): EasingFunction | undefined;
+    /** Removes a registered custom easing. Built-ins cannot be removed. */
+    remove(name: string): boolean;
+}
+export declare function registerEasing(name: string, easing: EasingFunction): void;
+export declare function getEasing(name: string): EasingFunction | undefined;
+export declare function removeEasing(name: string): boolean;
+export declare const easingRegistry: Readonly<EasingRegistryApi>;
+export declare function resolveEasing(easing: EasingOption | undefined): EasingFunction;

package/dist/effects/border-beam.d.ts

@@ -0,0 +1,28 @@
+import type { AnimateTarget } from "../core/animate.js";
+export interface BorderBeamOptions {
+    /** Beam color. Defaults to violet. */
+    color?: string;
+    /** Angular width of the travelling beam in degrees. Must be in (0, 360]. Defaults to 120. */
+    size?: number;
+    /** Animation duration in milliseconds. Must be > 0. Defaults to 3000. */
+    duration?: number;
+    /** Border thickness in pixels. Must be > 0. Defaults to 1. */
+    borderWidth?: number;
+    /** Border corner radius in pixels. Must be >= 0. Defaults to 16. */
+    radius?: number;
+    /** Starts the beam paused. Defaults to false. */
+    paused?: boolean;
+}
+export interface BorderBeamControls {
+    /** Pauses the travelling beam. Safe to call repeatedly. */
+    pause(): void;
+    /** Resumes the travelling beam unless reduced motion is preferred. Safe to call repeatedly. */
+    resume(): void;
+    /** Removes the beam and restores target styles. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Adds a glowing border beam behind target content. The beam uses the Web Animations API,
+ * and falls back to a subtle static border when reduced motion is enabled.
+ */
+export declare function borderBeam(target: AnimateTarget, options?: BorderBeamOptions): BorderBeamControls;

package/dist/effects/count-up.d.ts

@@ -0,0 +1,30 @@
+import type { AnimateTarget } from "../core/animate.js";
+import type { EasingName } from "../easing/easings.js";
+import type { EasingFunction } from "../core/animation.js";
+export interface CountUpOptions {
+    /** Starting number. Defaults to 0. */
+    from?: number;
+    /** Final number. Defaults to 100. */
+    to?: number;
+    /** Animation duration in milliseconds. Must be >= 0. Defaults to 1000. */
+    duration?: number;
+    /** Number of fractional digits to display. Must be an integer from 0 to 20. Defaults to 0. */
+    decimals?: number;
+    /** Text prepended to the formatted number. Defaults to an empty string. */
+    prefix?: string;
+    /** Text appended to the formatted number. Defaults to an empty string. */
+    suffix?: string;
+    /** Name of an easing in the public registry, or a custom easing function. Defaults to linear. */
+    easing?: EasingName | EasingFunction;
+    /** Fires once after the count animation finishes. */
+    onComplete?: () => void;
+}
+export interface CountUpControls {
+    /** Cancels pending frames and restores each target's original text. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Animates formatted numeric values for every target using one shared requestAnimationFrame
+ * loop. Destroying the effect cancels the frame and restores each element's original text.
+ */
+export declare function countUp(target: AnimateTarget, options?: CountUpOptions): CountUpControls;

package/dist/effects/cursor-trail.d.ts

@@ -0,0 +1,23 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type CursorTrailTarget = AnimateTarget | Document;
+export interface CursorTrailOptions {
+    /** CSS particle color. Defaults to violet. */
+    color?: string;
+    /** Maximum number of simultaneously visible particles. Defaults to 12. */
+    particleCount?: number;
+    /** Particle diameter in pixels. Must be > 0. Defaults to 6. */
+    size?: number;
+    /** Particle lifetime in milliseconds. Must be > 0. Defaults to 500. */
+    duration?: number;
+    /** Track the document, an element, or all elements matching a selector. Defaults to document. */
+    target?: CursorTrailTarget;
+}
+export interface CursorTrailControls {
+    /** Removes listeners, cancels active animations, and removes the overlay. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Emits a fading particle trail from pointer movement. Particle animations are individual
+ * Web Animations; there is no per-frame JavaScript loop.
+ */
+export declare function cursorTrail(options?: CursorTrailOptions): CursorTrailControls;

package/dist/effects/drag.d.ts

@@ -0,0 +1,41 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type DragAxis = "x" | "y" | "both";
+export interface DragPosition {
+    readonly x: number;
+    readonly y: number;
+}
+export interface DragOptions {
+    /** Axes that may move. Defaults to "both". */
+    axis?: DragAxis;
+    /** Optional movement bounds in pixels relative to the starting position. */
+    bounds?: {
+        minX?: number;
+        maxX?: number;
+        minY?: number;
+        maxY?: number;
+    };
+    /**
+     * Element (or selector) the dragged element must stay inside. Measured at the start of each
+     * drag and combined with ounds (the tighter limit wins on each side).
+     */
+    container?: HTMLElement | string;
+    /** Continue with decaying pointer velocity after release. Defaults to true. */
+    inertia?: boolean;
+    /** Exponential velocity decay per second. Must be > 0. Defaults to 8. */
+    friction?: number;
+    /** Called when a primary pointer starts dragging. */
+    onDragStart?: (position: DragPosition) => void;
+    /** Called as the element moves, including during inertia. */
+    onDrag?: (position: DragPosition) => void;
+    /** Called on release or cancellation; cancelled is true for pointer cancellation. */
+    onDragEnd?: (position: DragPosition, cancelled: boolean) => void;
+}
+export interface DragControls {
+    /** Cancels active dragging and momentum, removes listeners, and restores original styles. */
+    destroy(): void;
+}
+/**
+ * Moves elements in response to an active pointer gesture. The transform is a composable layer,
+ * so it can be combined with hover, tilt, and magnetic effects without replacing their transforms.
+ */
+export declare function drag(target: AnimateTarget, options?: DragOptions): DragControls;

package/dist/effects/draw-svg.d.ts

@@ -0,0 +1,19 @@
+import type { AnimateTarget } from "../core/animate.js";
+import type { AnimationControls, AnimationOptions } from "../core/animation.js";
+export interface DrawSVGOptions extends AnimationOptions {
+    /** Extra delay between paths, in milliseconds. Defaults to 0. */
+    stagger?: number;
+    /** Starts fully drawn and animates to the undrawn state. Defaults to false. */
+    reverse?: boolean;
+}
+export interface DrawSVGControls extends AnimationControls {
+    /** Cancels active path animations and restores original dash attributes and styles. */
+    destroy(): void;
+}
+/**
+ * Draws SVG paths by animating their stroke dash offset through the shared animation engine.
+ *
+ * A path or SVG container target is accepted; a selector may match paths or containers.
+ * `destroy()` is idempotent and restores each path's original dash attributes and inline styles.
+ */
+export declare function drawSVG(target: AnimateTarget, options?: DrawSVGOptions): DrawSVGControls;

package/dist/effects/follow-pointer.d.ts

@@ -0,0 +1,19 @@
+import type { AnimateTarget } from "../core/animate.js";
+import type { EasingFunction } from "../core/animation.js";
+export interface FollowPointerOptions {
+    /** Element or selector whose bounds constrain pointer-following movement. */
+    container: AnimateTarget;
+    /** Transition duration in seconds, from 0 (immediate) to 1. Defaults to 0.12. */
+    smoothing?: number;
+    /** Defaults to `easings.easeOutCubic`. */
+    easing?: EasingFunction;
+}
+export interface FollowPointerControls {
+    /** Removes listeners, cancels active transitions, and restores original transforms. */
+    destroy(): void;
+}
+/**
+ * Moves target elements to follow mouse or pen movement inside one container, constrained
+ * so each target stays within the container. Transform contributions compose with other effects.
+ */
+export declare function followPointer(target: AnimateTarget, options: FollowPointerOptions): FollowPointerControls;

package/dist/effects/glow.d.ts

@@ -0,0 +1,25 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type GlowMode = "static" | "pulse" | "hover";
+export type GlowTrigger = "immediate" | "hover";
+export interface GlowOptions {
+    /** CSS glow color. Defaults to violet. */
+    color?: string;
+    /** Glow opacity between 0 and 1. Defaults to 0.7. */
+    intensity?: number;
+    /** Glow blur radius in pixels. Defaults to 24. */
+    blur?: number;
+    /** Static, pulsing, or pointer-hover glow. Defaults to "static". */
+    mode?: GlowMode;
+    /** Pulse period in milliseconds. Defaults to 2000. */
+    duration?: number;
+    /** Activate immediately or only while hovered. Defaults to "immediate". */
+    trigger?: GlowTrigger;
+}
+export interface GlowControls {
+    /** Cancels animations, removes pointer listeners, and restores original inline styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Adds a static, pulsing, or hover-activated glow without replacing existing content or shadows.
+ */
+export declare function glow(target: AnimateTarget, options?: GlowOptions): GlowControls;

package/dist/effects/gradient-text.d.ts

@@ -0,0 +1,22 @@
+import type { AnimateTarget } from "../core/animate.js";
+export interface GradientTextOptions {
+    /** CSS colors used for the text gradient. Defaults to a violet/cyan pair. */
+    colors?: readonly string[];
+    /** Gradient angle in degrees. Defaults to 90. */
+    angle?: number;
+    /** Animation duration in milliseconds. Defaults to 4000. */
+    duration?: number;
+    /** Enables gradient movement. Defaults to false. */
+    animated?: boolean;
+    /** Repeats the animation indefinitely. Defaults to true. */
+    loop?: boolean;
+}
+export interface GradientTextControls {
+    /** Cancels animation and restores the original inline text styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Applies a CSS text gradient and optionally moves it with the Web Animations API.
+ * Original inline styles are restored when destroyed.
+ */
+export declare function gradientText(target: AnimateTarget, options?: GradientTextOptions): GradientTextControls;

package/dist/effects/hover-motion.d.ts

@@ -0,0 +1,32 @@
+import type { AnimateTarget } from "../core/animate.js";
+import type { EasingFunction } from "../core/animation.js";
+export interface HoverMotionValues {
+    /** Horizontal translation in pixels. Defaults to 0. */
+    x?: number;
+    /** Vertical translation in pixels. Defaults to 0. */
+    y?: number;
+    /** Scale multiplier. Defaults to 1. */
+    scale?: number;
+    /** Rotation in degrees. Defaults to 0. */
+    rotate?: number;
+}
+export interface HoverMotionOptions {
+    /** Transform layer applied while the pointer is over an element. */
+    enter?: HoverMotionValues;
+    /** Transform layer applied after leaving; a custom pose remains until re-entry or destroy. */
+    leave?: HoverMotionValues;
+    /** Transition duration in milliseconds. Defaults to 220. */
+    duration?: number;
+    /** Defaults to `easings.easeOutCubic`. */
+    easing?: EasingFunction;
+}
+export interface HoverMotionControls {
+    /** Removes listeners, cancels active transitions, and restores original transforms. */
+    destroy(): void;
+}
+/**
+ * Animates a composable transform layer on pointer enter/leave and keyboard focus/blur.
+ * Mouse and pen pointers are supported; touch and reduced-motion preferences leave elements
+ * at their resting state.
+ */
+export declare function hoverMotion(target: AnimateTarget, options?: HoverMotionOptions): HoverMotionControls;

package/dist/effects/in-view.d.ts

@@ -0,0 +1,14 @@
+import type { ScrollTriggerOptions } from "./scroll-trigger.js";
+import type { AnimateTarget } from "../core/animate.js";
+export type InViewCleanup = () => void;
+export type InViewCallback = (element: HTMLElement, entry: IntersectionObserverEntry) => void | InViewCleanup;
+export type InViewOptions = Pick<ScrollTriggerOptions, "rootMargin" | "threshold" | "once">;
+export interface InViewControls {
+    /** Stops observing targets and runs cleanup for every currently visible target. */
+    destroy(): void;
+}
+/**
+ * Runs a callback when a target enters the viewport, and its optional cleanup when
+ * that target leaves or the observer is destroyed.
+ */
+export declare function inView(target: AnimateTarget, callback: InViewCallback, options?: InViewOptions): InViewControls;

package/dist/effects/magnetic.d.ts

@@ -0,0 +1,40 @@
+import type { AnimateTarget } from "../core/animate.js";
+import type { EasingFunction } from "../core/animation.js";
+export interface MagneticOptions {
+    /** Fraction of the cursor's distance from the element's center to follow. Defaults to 0.25. */
+    strength?: number;
+    /** Maximum translation per axis, in pixels. Defaults to 12. */
+    maxTranslate?: number;
+    /** Maximum pointer distance from the element center to apply attraction. Defaults to unlimited. */
+    distance?: number;
+    /** Duration of each movement tween in milliseconds. Defaults to 200. */
+    duration?: number;
+    /** Defaults to `easings.easeOutCubic`. */
+    easing?: EasingFunction;
+}
+export interface MagneticControls {
+    /** Removes listeners, cancels animations and restores original transforms. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Makes elements drift toward the cursor while it hovers them, then settle back.
+ *
+ * - The movement is appended to the element's existing transform (`<base> translate(x, y)`).
+ *   The base is the inline transform, or the computed one when no inline transform is set
+ *   (read once per hover, never per frame).
+ * - The element's bounding box is measured once when the pointer enters. Pointer moves only
+ *   do arithmetic and start a short tween from the current offset, so there are no layout
+ *   reads per move or per frame. If the page scrolls or layout changes during a hover, the
+ *   center is re-measured on the next enter.
+ * - On leave the element tweens back to rest, then its original inline transform is restored
+ *   exactly (or removed if there was none). Other inline styles are never touched.
+ * - Reduced motion (checked on every pointer event) disables the effect entirely; an element
+ *   that is mid-hover when the preference turns on settles back to rest. Touch pointers are ignored.
+ * - Throws `RangeError` for invalid numbers, `TypeError` for a non-function easing, and the
+ *   same selector/target errors as `animate()`. A target matching no elements returns inert controls.
+ */
+export declare function magnetic(target: AnimateTarget, options?: MagneticOptions): MagneticControls;
+/** Alias for `magnetic()` with the same strength, translation, and distance options. */
+export declare const magneticElement: typeof magnetic;
+export type MagneticElementOptions = MagneticOptions;
+export type MagneticElementControls = MagneticControls;

package/dist/effects/morph-svg.d.ts

@@ -0,0 +1,15 @@
+import type { AnimationControls, AnimationOptions } from "../core/animation.js";
+export type MorphSVGTarget = SVGElement | string;
+export interface MorphSVGOptions extends AnimationOptions {
+}
+export interface MorphSVGControls extends AnimationControls {
+    /** Cancels active morphs and restores each path's original `d` attribute. */
+    destroy(): void;
+}
+/**
+ * Morphs compatible SVG path data. Identical command structures interpolate token by token;
+ * otherwise both paths are normalized to absolute M/L/C/Q/A/Z segments (relative commands, H/V,
+ * S/T, and implicit repeats) and must then match segment by segment. Incompatible structures
+ * are rejected instead of approximated.
+ */
+export declare function morphSVG(target: MorphSVGTarget, toPath: string, options?: MorphSVGOptions): MorphSVGControls;

package/dist/effects/parallax.d.ts

@@ -0,0 +1,42 @@
+import type { AnimateTarget } from "../core/animate.js";
+import type { EasingFunction } from "../core/animation.js";
+export type ParallaxAxis = "x" | "y";
+export interface ParallaxOptions {
+    /**
+     * Fraction of the element's distance from the viewport center that is added as a translation.
+     * Positive values make the layer move slower than the page, negative values faster. May be 0.
+     * Defaults to 0.3.
+     */
+    speed?: number;
+    /** Axis to translate along. Defaults to "y". */
+    axis?: ParallaxAxis;
+    /** Maximum absolute translation in pixels. Must be >= 0. Defaults to 100. */
+    maxOffset?: number;
+    /** Shapes the clamped offset: `easing(|offset| / maxOffset)`. Defaults to linear. */
+    easing?: EasingFunction;
+}
+export interface ParallaxControls {
+    /** Removes listeners, cancels the pending frame and restores original transforms. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Moves elements along one axis as the page scrolls, relative to the viewport center.
+ *
+ * - An element's offset is `-(elementCenter - viewportCenter) * speed`, clamped to `maxOffset` and
+ *   shaped by `easing`. It is 0 when the element is centered in the viewport.
+ * - One passive `scroll` listener and one `requestAnimationFrame` serve every element; at most one
+ *   frame is pending, and nothing runs while the page is idle.
+ * - Layout is read only when the effect starts, on `resize`, and when reduced motion is turned
+ *   back off - never on scroll. Each element's resting position is cached in page coordinates
+ *   (measured with its original transform in place), so scroll frames are pure arithmetic.
+ *   Layout shifts that don't fire `resize` are not noticed until the next resize.
+ * - Styles are written only when the rounded offset changes. The effect writes only `transform`,
+ *   as `<original> translate(x, y)`, where the original is the inline transform, or the computed
+ *   transform when no inline one is set. An element that never needs to move is never written to.
+ * - Reduced motion (checked every frame and watched through `matchMedia` change events) restores
+ *   every original transform and keeps the effect inactive until the preference is turned off.
+ * - Throws `Error` when `window` or `requestAnimationFrame` is unavailable, `RangeError` for invalid
+ *   numbers, `TypeError` for an invalid axis or easing, and the same selector/target errors as
+ *   `animate()`. A target matching no elements returns inert controls.
+ */
+export declare function parallax(target: AnimateTarget, options?: ParallaxOptions): ParallaxControls;

package/dist/effects/pinch.d.ts

@@ -0,0 +1,27 @@
+import type { AnimateTarget } from "../core/animate.js";
+export interface PinchGesture {
+    /** Current pointer distance divided by the distance when the pinch started. */
+    readonly scale: number;
+    readonly distance: number;
+    readonly initialDistance: number;
+    readonly centerX: number;
+    readonly centerY: number;
+    /** True when the gesture ended because the browser cancelled a pointer. */
+    readonly cancelled: boolean;
+}
+export interface PinchOptions {
+    /** Minimum distance in pixels between pointers required to start. Defaults to 10. */
+    minDistance?: number;
+    onStart?: (gesture: PinchGesture) => void;
+    onUpdate?: (gesture: PinchGesture) => void;
+    onEnd?: (gesture: PinchGesture) => void;
+}
+export interface PinchControls {
+    /** Removes listeners, releases pointer capture, and ends any active pinch. */
+    destroy(): void;
+}
+/**
+ * Detects two-pointer pinch gestures on one or more HTML elements and reports
+ * scale relative to the pointer distance when the pinch started.
+ */
+export declare function pinch(target: AnimateTarget, options?: PinchOptions): PinchControls;

package/dist/effects/reveal.d.ts

@@ -0,0 +1,33 @@
+import type { AnimatableProperties, AnimateTarget } from "../core/animate.js";
+import type { EasingFunction } from "../core/animation.js";
+export interface RevealOptions {
+    /** `[from, to]` pairs passed to `animate()`. Defaults to a fade-and-rise. */
+    properties?: AnimatableProperties;
+    /** Duration in milliseconds. Defaults to 600. */
+    duration?: number;
+    /** Delay in milliseconds. Defaults to 0. */
+    delay?: number;
+    easing?: EasingFunction;
+    /** IntersectionObserver threshold (0..1 or a list). Defaults to 0.15. */
+    threshold?: number | number[];
+    /** IntersectionObserver rootMargin. Defaults to "0px". */
+    rootMargin?: string;
+    /** Animate each element only the first time it is revealed. Defaults to true. */
+    once?: boolean;
+}
+export interface RevealControls {
+    /** Disconnects the observer and cancels running animations. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Animates elements the first time (or every time, with `once: false`) they scroll into view.
+ *
+ * - Elements are put in their `from` state immediately so they don't flash before
+ *   being revealed. With reduced motion, `animate()` skips this and content stays visible,
+ *   then jumps to its final state when revealed.
+ * - Options and properties are validated up front; errors are thrown synchronously
+ *   from `reveal()` rather than later inside an observer callback.
+ * - Throws `Error` if `IntersectionObserver` is unavailable.
+ * - A target matching no elements returns inert controls.
+ */
+export declare function reveal(target: AnimateTarget, options?: RevealOptions): RevealControls;

package/dist/effects/ripple.d.ts

@@ -0,0 +1,21 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type RippleOrigin = "pointer" | "center";
+export interface RippleOptions {
+    /** CSS color of the expanding wave. Defaults to translucent white. */
+    color?: string;
+    /** Wave animation duration in milliseconds. Must be > 0. Defaults to 600. */
+    duration?: number;
+    /** Final scale relative to the calculated circle size. Must be > 0. Defaults to 2. */
+    scale?: number;
+    /** Center the wave or use the click position. Defaults to "pointer". */
+    origin?: RippleOrigin;
+}
+export interface RippleControls {
+    /** Cancels active waves, removes click listeners, and restores target styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Creates expanding, fading click waves at the pointer or target center.
+ * Click events are observed without preventing default behavior or stopping propagation.
+ */
+export declare function ripple(target: AnimateTarget, options?: RippleOptions): RippleControls;

package/dist/effects/scroll-animate.d.ts

@@ -0,0 +1,23 @@
+import type { AnimatableProperties, AnimateTarget } from "../core/animate.js";
+import type { EasingOption } from "../easing/easings.js";
+export interface ScrollAnimateOptions {
+    /** Window or scrollable element to track. Defaults to window. */
+    scrollTarget?: Window | AnimateTarget;
+    /** Maps scroll progress through the same easing registry used by `animate()`. */
+    easing?: EasingOption;
+    /** Reverses the mapping so scroll start applies the `to` values. Defaults to false. */
+    reverse?: boolean;
+    /** Called after the animated values are updated for a new scroll progress. */
+    onUpdate?: (progress: number) => void;
+}
+export interface ScrollAnimateControls {
+    /** Pauses scroll-driven writes while retaining the latest progress. */
+    pause(): void;
+    /** Resumes scroll-driven writes at the latest measured progress. */
+    resume(): void;
+    /** Returns the latest normalized scroll progress. */
+    getProgress(): number;
+    /** Removes scroll listeners and cancels pending work. Safe to repeat. */
+    destroy(): void;
+}
+export declare function scrollAnimate(target: AnimateTarget, properties: AnimatableProperties, options?: ScrollAnimateOptions): ScrollAnimateControls;

package/dist/effects/scroll-direction.d.ts

@@ -0,0 +1,19 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type ScrollDirection = "up" | "down" | "idle";
+export interface ScrollDirectionOptions {
+    /** Minimum accumulated scroll movement in pixels before changing direction. Defaults to 12. */
+    threshold?: number;
+    /** Window, an element, or a selector resolving to exactly one scrollable element. Defaults to window. */
+    target?: Window | AnimateTarget;
+    /** Called only when the detected direction changes. */
+    onChange: (direction: ScrollDirection) => void;
+}
+export interface ScrollDirectionControls {
+    /** Cancels a pending measurement and removes the scroll listener. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Detects scroll direction only after movement crosses a pixel threshold.
+ * Passive events are batched into one animation frame, and no animation is created.
+ */
+export declare function scrollDirection(options: ScrollDirectionOptions): ScrollDirectionControls;

package/dist/effects/scroll-progress.d.ts

@@ -0,0 +1,29 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type ScrollProgressPosition = "top" | "bottom";
+export interface ScrollProgressOptions {
+    /** Viewport edge for the fixed bar. Defaults to "top". */
+    position?: ScrollProgressPosition;
+    /** Bar color. Defaults to violet. */
+    color?: string;
+    /** Bar thickness in pixels. Must be > 0. Defaults to 3. */
+    height?: number;
+    /** CSS transition smoothing duration in seconds. Must be between 0 and 2. Defaults to 0.15. */
+    smoothing?: number;
+    /** Alias for smoothing, matching the original API example. */
+    easing?: number;
+    /** Scrollable element (or selector resolving to exactly one element) to track instead of the page. */
+    target?: AnimateTarget;
+    /** Called when the measured normalized scroll progress changes. */
+    onUpdate?: (progress: number) => void;
+}
+export interface ScrollProgressControls {
+    /** Returns the latest measured normalized scroll progress. */
+    getProgress(): number;
+    /** Cancels pending updates, removes listeners and the generated bar. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Displays page or element scroll progress in a fixed bar. Scroll/resize events are batched
+ * into at most one animation frame; reduced motion updates the bar immediately.
+ */
+export declare function scrollProgress(options?: ScrollProgressOptions): ScrollProgressControls;

package/dist/effects/scroll-trigger.d.ts

@@ -0,0 +1,22 @@
+import type { AnimateTarget } from "../core/animate.js";
+export interface ScrollTriggerOptions {
+    /** Called when an observed element enters the configured viewport region. */
+    onEnter?: (element: HTMLElement, entry: IntersectionObserverEntry) => void;
+    /** Called when an element that entered leaves the configured viewport region. */
+    onLeave?: (element: HTMLElement, entry: IntersectionObserverEntry) => void;
+    /** IntersectionObserver root margin. Defaults to "0px". */
+    rootMargin?: string;
+    /** IntersectionObserver threshold (0..1 or a list). Defaults to 0. */
+    threshold?: number | number[];
+    /** Observe one enter/leave cycle per element. Defaults to true. */
+    once?: boolean;
+}
+export interface ScrollTriggerControls {
+    /** Stops observing all targets. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Calls transition callbacks as elements enter and leave an observer's viewport region.
+ * In one-time mode, each element is observed through its first complete visible cycle.
+ */
+export declare function scrollTrigger(target: AnimateTarget, options?: ScrollTriggerOptions): ScrollTriggerControls;

package/dist/effects/scroll-velocity.d.ts

@@ -0,0 +1,29 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type ScrollVelocityDirection = "up" | "down" | "idle";
+export interface ScrollVelocityData {
+    /** Smoothed scroll velocity in pixels per second. */
+    velocity: number;
+    /** Direction of the latest scroll movement, or "idle" when position is unchanged. */
+    direction: ScrollVelocityDirection;
+    /** Current scroll position in pixels. */
+    position: number;
+    /** Current normalized scroll position from 0 to 1. */
+    progress: number;
+}
+export interface ScrollVelocityOptions {
+    /** Fraction of the previous velocity retained per update, from 0 (no smoothing) to 1 (maximum smoothing). Defaults to 0.2. */
+    smoothing?: number;
+    /** Window, an element, or a selector resolving to exactly one scrollable element. Defaults to window. */
+    target?: Window | AnimateTarget;
+    /** Receives scroll measurements after each scheduled update and the initial state, including decay frames after scrolling stops until velocity settles at 0. */
+    onUpdate: (data: ScrollVelocityData) => void;
+}
+export interface ScrollVelocityControls {
+    /** Cancels pending measurements and removes listeners. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Tracks scroll direction, normalized progress, and smoothed velocity in px/s.
+ * Scroll events are passively observed and measurements are batched through requestAnimationFrame.
+ */
+export declare function scrollVelocity(options: ScrollVelocityOptions): ScrollVelocityControls;

package/dist/effects/shine.d.ts

@@ -0,0 +1,23 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type ShineTrigger = "hover" | "continuous" | "click";
+export interface ShineOptions {
+    /** CSS color of the glossy sweep. Defaults to translucent white. */
+    color?: string;
+    /** Direction angle of the diagonal sweep in degrees. Defaults to 120. */
+    angle?: number;
+    /** Duration of a sweep in milliseconds. Must be > 0. Defaults to 1200. */
+    duration?: number;
+    /** Overlay opacity between 0 and 1. Defaults to 0.7. */
+    intensity?: number;
+    /** Sweep continuously, on hover, or on click. Defaults to "hover". */
+    trigger?: ShineTrigger;
+}
+export interface ShineControls {
+    /** Cancels animations, removes listeners/overlays, and restores target styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Adds a diagonal glossy sweep using a pointer-transparent overlay.
+ * Motion is driven by the Web Animations API, never a JavaScript animation loop.
+ */
+export declare function shine(target: AnimateTarget, options?: ShineOptions): ShineControls;