@motion.page/sdk 0.1.0

package/dist/memory/AnimationPool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AnimationPool - Singleton object pool for Animation instances
+ *
+ * Reuses Animation objects to minimize garbage collection overhead
+ */
+import { Animation } from '../core/Animation';
+export declare const AnimationPool: {
+    acquire: () => Animation;
+    release: (animation: Animation) => void;
+    getPoolSize: () => number;
+    getTotalCreated: () => number;
+    clear: () => void;
+};
+export type AnimationPool = typeof AnimationPool;

package/dist/memory/ObjectPool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ObjectPool<T> - Generic object pool for reusable instances
+ *
+ * Reuses objects that implement a `reset()` method to minimize
+ * garbage collection overhead.
+ */
+/** Constraint: pooled objects must be resettable */
+export interface Poolable {
+    reset(): void;
+}
+export declare class ObjectPool<T extends Poolable> {
+    private pool;
+    private totalCreated;
+    private readonly factory;
+    private readonly maxSize;
+    constructor(factory: () => T, maxSize?: number);
+    /**
+     * Acquire an object from the pool or create a new one
+     */
+    acquire(): T;
+    /**
+     * Release an object back to the pool
+     */
+    release(obj: T): void;
+    /**
+     * Get count of pooled objects
+     */
+    getPoolSize(): number;
+    /**
+     * Get total objects created (for stats)
+     */
+    getTotalCreated(): number;
+    /**
+     * Clear the pool (for testing/debugging)
+     */
+    clear(): void;
+}

package/dist/memory/PropTweenPool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * PropTweenPool - Singleton object pool for PropTween instances
+ *
+ * Reuses PropTween objects to minimize garbage collection overhead
+ */
+import { PropTween } from '../core/PropTween';
+export declare const PropTweenPool: {
+    acquire: () => PropTween;
+    release: (propTween: PropTween) => void;
+    getPoolSize: () => number;
+    getTotalCreated: () => number;
+    clear: () => void;
+};
+export type PropTweenPool = typeof PropTweenPool;

package/dist/registries/SDKRegistry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * SDKRegistry - Central registry for all optional SDK modules
+ *
+ * Optional modules register themselves here when loaded.
+ * Core modules access features through this registry with optional chaining.
+ * This enables tree-shaking: unused modules aren't bundled.
+ */
+import type { ParsedFilterFunction } from '../utils/FilterParser';
+import type { ParsedDrawSVG } from '../utils/DrawSVGParser';
+import type { AnimationTarget, StaggerVars, SplitType } from '../types';
+import type { TriggerManager } from '../triggers/TriggerManager';
+interface ColorParserFunctions {
+    parseColor: (color: string, element?: Element) => Float32Array | null;
+    getCurrentColor: (element: Element, property: string) => Float32Array;
+}
+interface FilterParserFunctions {
+    parseFilter: (filter: string) => ParsedFilterFunction[] | null;
+    getCurrentFilter: (element: Element) => ParsedFilterFunction[];
+    mergeFilterArrays: (start: ParsedFilterFunction[], end: ParsedFilterFunction[]) => {
+        start: ParsedFilterFunction[];
+        end: ParsedFilterFunction[];
+    };
+    interpolateFilters: (start: ParsedFilterFunction[], end: ParsedFilterFunction[], progress: number) => ParsedFilterFunction[];
+    filterToString: (filters: ParsedFilterFunction[]) => string;
+}
+interface DrawSVGParserFunctions {
+    parseDrawSVG: (value: string | {
+        start?: number;
+        end?: number;
+    }, element?: Element) => ParsedDrawSVG | null;
+    getCurrentDrawSVG: (element: Element) => ParsedDrawSVG;
+    getPathLength: (element: Element) => number;
+    applyDrawSVG: (element: Element, start: number, end: number, length: number) => void;
+}
+interface TextSplitterFunctions {
+    split: (element: Element, type: SplitType, options?: {
+        mask?: boolean;
+    }) => HTMLElement[];
+    revert: (element: Element) => boolean;
+    isSplit: (element: Element) => boolean;
+}
+interface StyleResetFunctions {
+    registerAnimatedProps: (element: Element, props: string[]) => void;
+    clearAnimationStylesForProps: (element: Element, props: string[]) => void;
+    clearAnimationStylesAndUnregister: (element: Element) => void;
+    clearPinStylesAndUnregister: (element: Element) => void;
+}
+interface FitResolverFunctions {
+    registerPendingSetup(animation: import('../core/Animation').Animation, element: Element, fitConfig: import('../types').FitConfig, propTweenPool: typeof import('../memory/PropTweenPool').PropTweenPool): void;
+}
+/**
+ * Unified registry for all optional SDK features.
+ * Each slot is null until the corresponding module loads and self-registers.
+ */
+export declare const SDKRegistry: {
+    color: ColorParserFunctions | null;
+    filter: FilterParserFunctions | null;
+    drawSVG: DrawSVGParserFunctions | null;
+    stagger: {
+        resolve: (targets: AnimationTarget[], stagger: number | StaggerVars) => number[];
+    } | null;
+    textSplitter: TextSplitterFunctions | null;
+    triggerManager: {
+        getInstance: () => TriggerManager;
+    } | null;
+    styleReset: StyleResetFunctions | null;
+    fit: FitResolverFunctions | null;
+};
+export {};

package/dist/render/CSSRenderer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CSSRenderer - Render CSS properties to DOM elements
+ *
+ * Handles:
+ * - Transform properties (x, y, rotate, scale, etc.)
+ * - Standard CSS properties (opacity, backgroundColor, etc.)
+ * - Unit handling (px, %, deg, etc.)
+ * - Auto-batching: queues during animation tick, writes immediately otherwise
+ *
+ * The render system automatically detects context:
+ * - Inside Ticker tick → queue for batch flush at end of frame (performance)
+ * - Outside tick → write immediately to DOM (responsiveness for seek/progress/etc.)
+ */
+import type { ParsedFilterFunction } from '../utils/FilterParser';
+/**
+ * Set a CSS property value on an element
+ * Automatically batches during animation tick, writes immediately otherwise
+ */
+export declare function setCSSProperty(element: Element, property: string, value: number, unit: string): void;
+/**
+ * Set a CSS color property value on an element
+ * Takes RGBA values directly for performance (avoids string formatting in hot path)
+ */
+export declare function setCSSColorProperty(element: Element, property: string, r: number, g: number, b: number, a: number): void;
+/**
+ * Get computed value of a CSS property
+ */
+export declare function getCSSProperty(element: Element, property: string): string;
+/**
+ * Set a CSS filter property value on an element
+ * Interpolates between start and end filter arrays at given progress
+ */
+export declare function setCSSFilterProperty(element: Element, startFilters: ParsedFilterFunction[], endFilters: ParsedFilterFunction[], progress: number): void;

package/dist/render/PathRenderer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PathRenderer - Encapsulates motion path rendering logic
+ *
+ * Extracted from PropTween to improve code organization.
+ * PropTween still holds the data (for pooling), but rendering is delegated here.
+ */
+import type { PathPoint } from '../utils/PathParser';
+interface PathRenderState {
+    pathLUT: PathPoint[];
+    alignOffset: {
+        x: number;
+        y: number;
+    };
+    pathOffset: {
+        x: number;
+        y: number;
+    };
+    pathRotate: boolean;
+}
+/**
+ * Render path position at given progress
+ */
+export declare function renderPath(target: Element, progress: number, state: PathRenderState): void;
+export {};

package/dist/render/RenderBatch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * RenderBatch - Batched DOM write system
+ *
+ * Collects all property changes during a frame and flushes them
+ * in a single batch at frame end. This eliminates layout thrashing
+ * and reduces DOM writes from O(properties) to O(elements).
+ *
+ * Key optimizations:
+ * - One transform string build per element (not per property)
+ * - One DOM write per element for transforms
+ * - Batched CSS property writes
+ * - Zero allocations during animation (uses Sets/Maps)
+ */
+/**
+ * Queue a transform update for an element
+ * Called after setTransformValue updates the cache
+ */
+export declare function queueTransform(element: Element): void;
+/**
+ * Queue a CSS property update for an element
+ */
+export declare function queueStyle(element: Element, property: string, value: string): void;
+/**
+ * Flush all pending DOM writes
+ * Called once at end of each animation frame
+ */
+export declare function flush(): void;

package/dist/render/TransformCache.d.ts

@@ -0,0 +1,54 @@
+/**
+ * TransformCache - Optimized transform value storage
+ *
+ * Uses Float32Array for fast transform value storage per element.
+ * Separate array for units (string per property).
+ * Dirty flag bitmask to skip unchanged properties.
+ * Cached transform string to avoid rebuilding.
+ */
+interface TransformData {
+    values: Float32Array;
+    units: string[];
+    dirty: number;
+    used: number;
+    cachedString: string;
+    pinDirty: boolean;
+}
+/**
+ * Get or create transform data for an element
+ */
+export declare function getTransformData(element: Element): TransformData;
+/**
+ * Set a transform value and unit, mark as dirty
+ */
+export declare function setTransformValue(element: Element, property: string, value: number, unit?: string): void;
+/**
+ * Get a transform value
+ */
+export declare function getTransformValue(element: Element, property: string): number;
+/**
+ * Get a transform unit
+ */
+export declare function getTransformUnit(element: Element, property: string): string;
+/**
+ * Register a pin offset for an element.
+ * The pin offset is prepended to the animation transform in buildTransformString().
+ * Call this instead of writing directly to element.style.transform from PinManager
+ * so that both pin position and animation values are composed into a single write.
+ */
+export declare function setPinOffset(element: Element, x: number, y: number, z: number): void;
+/**
+ * Remove the pin offset for an element (call when element exits pin zone).
+ * Marks the cached transform string as stale so the next build omits the offset.
+ */
+export declare function clearPinOffset(element: Element): void;
+/**
+ * Build the CSS transform string from cached values
+ */
+export declare function buildTransformString(element: Element): string;
+/**
+ * Clear transform cache for an element
+ * @param clearInlineStyle - If true, also clears element's inline transform to prevent hydration from reading stale values
+ */
+export declare function clearTransformCache(element: Element, clearInlineStyle?: boolean): void;
+export {};

package/dist/stagger/StaggerResolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * StaggerResolver - Calculates stagger delays for multiple targets
+ */
+import type { StaggerVars, AnimationTarget } from '../types';
+export declare class StaggerResolver {
+    /**
+     * Calculate stagger delays for an array of targets
+     * Works with both DOM elements and plain objects
+     */
+    static resolve(targets: AnimationTarget[], stagger: number | StaggerVars): number[];
+    /**
+     * Resolve complex stagger configuration with from, grid, etc.
+     */
+    private static resolveComplexStagger;
+    /**
+     * Get target ordering based on 'from' parameter
+     */
+    private static getOrdering;
+    /**
+     * Get ordering for grid-based stagger
+     */
+    private static getGridOrdering;
+    /**
+     * Auto-detect grid dimensions from element positions
+     * Only works with DOM elements. For plain objects, falls back to linear arrangement.
+     */
+    private static detectGrid;
+}

package/dist/triggers/BaseTrigger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * BaseTrigger - Abstract base class for all standard trigger types
+ *
+ * Extracts the common enable/disable lifecycle pattern shared by
+ * ScrollTrigger, EventTrigger, MouseMoveTrigger, GestureTrigger, and CursorTrigger.
+ *
+ * Provides:
+ * - enable/disable guards with _enabled flag
+ * - DOM-ready gating via whenDOMReady
+ * - Shared helper methods for selector resolution and listener cleanup
+ *
+ * NOT used by PageLoadTrigger (which has a different lifecycle pattern).
+ */
+import type { Timeline } from '../core/Timeline';
+export declare abstract class BaseTrigger<TConfig> {
+    protected _timeline: Timeline;
+    protected _config: TConfig;
+    protected _enabled: boolean;
+    constructor(timeline: Timeline, config: TConfig);
+    /**
+     * Enable the trigger. Guards against double-enable and waits for DOM ready.
+     * Calls _onEnable() once the DOM is ready (or immediately if already ready).
+     */
+    enable(): void;
+    /**
+     * Disable the trigger. Guards against double-disable.
+     * Calls _onDisable() immediately (no DOM-ready gating needed for teardown).
+     */
+    disable(): void;
+    /**
+     * Subclass: set up event listeners, resolve targets, start ticker loops, etc.
+     * Called once per enable cycle after DOM is ready.
+     */
+    protected abstract _onEnable(): void;
+    /**
+     * Subclass: remove event listeners, clear state, stop ticker loops, etc.
+     * Called once per disable cycle.
+     */
+    protected abstract _onDisable(): void;
+    /**
+     * Resolve a single element from a string selector or Element reference.
+     * Returns the fallback (defaults to null) if selector is undefined, not found, or invalid.
+     *
+     * Note: non-string values are treated as direct element references without an instanceof
+     * check, so this works with both real DOM elements and mock objects in tests.
+     */
+    protected _resolveElement(selector: string | Element | undefined, fallback?: EventTarget | null): HTMLElement | EventTarget | null;
+    /**
+     * Resolve multiple elements from a string selector or single Element reference.
+     * Returns an empty array if selector is undefined, not found, or invalid.
+     *
+     * Note: non-string values are treated as direct element references without an instanceof
+     * check, so this works with both real DOM elements and mock objects in tests.
+     */
+    protected _resolveElements(selector: string | Element | undefined): Element[];
+    /**
+     * Remove all event listeners tracked in a nested listener map and clear the map.
+     * Accepts Map<EventTarget, Map<eventName, listener>>.
+     */
+    protected _cleanupListenerMap(listeners: Map<EventTarget, Map<string, EventListener>>): void;
+}

package/dist/triggers/CursorTrigger.d.ts

@@ -0,0 +1,86 @@
+/**
+ * CursorTrigger - Custom cursor controller
+ *
+ * Features:
+ * - Smooth position tracking with configurable lag
+ * - State-based animations (default, hover, click)
+ * - Velocity-based squeeze effect
+ * - Text and media cursor variants
+ */
+import type { CursorConfig } from '../types';
+import { Timeline } from '../core/Timeline';
+import { BaseTrigger } from './BaseTrigger';
+type CursorState = 'default' | 'hover' | 'click';
+export declare class CursorTrigger extends BaseTrigger<CursorConfig> {
+    private _element;
+    private _innerElement;
+    private _mousePos;
+    private _cursorPos;
+    private _xSetter;
+    private _ySetter;
+    private _squeezeSetter;
+    private _squeezeConfig;
+    private _state;
+    private _stateTimelines;
+    private _parsedStates;
+    private _textElement;
+    private _mediaElement;
+    private _tickerCallback?;
+    private _boundMouseMove?;
+    private _boundMouseDown?;
+    private _boundMouseUp?;
+    private _hoverFrozenRects;
+    private _isHoveringCursorTarget;
+    private _boundHoverTargetMoveHandler;
+    private _hoverListeners;
+    private _attributeListeners;
+    constructor(timeline: Timeline, config: CursorConfig);
+    private _parseStateConfig;
+    /**
+     * Set up the cursor: resolve element, create setters, attach listeners, start ticker.
+     *
+     * Architecture (mirrors original GSAP cursor):
+     * - Container (_element): position:fixed, zero-size, moved via x/y QuickSetters
+     * - Inner element (_innerElement): centered via translate(-50%, -50%),
+     *   receives all visual CSS properties and state transitions
+     */
+    protected _onEnable(): void;
+    /**
+     * Tear down the cursor: remove ticker, restore native cursor, remove listeners.
+     */
+    protected _onDisable(): void;
+    private _getTargetElement;
+    private _applyProperties;
+    private _createStateTimelines;
+    /**
+     * Expand CSS transform shorthand in state properties into individual
+     * SDK transform properties that the animation system can interpolate.
+     * E.g., {transform: 'scale(2)', width: '80px'} → {scale: 2, width: '80px'}
+     */
+    private static _expandStateProperties;
+    /**
+     * Parse CSS transform shorthand string into individual SDK transform properties.
+     * Handles: scale, scaleX/Y, rotate, rotateX/Y/Z, skewX/Y
+     * E.g., "scale(2)" → {scale: 2}
+     *       "scale(2, 3)" → {scaleX: 2, scaleY: 3}
+     *       "scale(2) rotate(45deg)" → {scale: 2, rotate: 45}
+     */
+    private static _expandTransformShorthand;
+    private _setupEventListeners;
+    private _setupHoverTargets;
+    private _setupTextCursor;
+    private _setupMediaCursor;
+    private _removeEventListeners;
+    private _setState;
+    private _tick;
+    private _calculateSqueeze;
+    /**
+     * Get the cursor element
+     */
+    getElement(): HTMLElement | null;
+    /**
+     * Get current state
+     */
+    getState(): CursorState;
+}
+export {};

package/dist/triggers/EventTrigger.d.ts

@@ -0,0 +1,48 @@
+/**
+ * EventTrigger
+ *
+ * Triggers timelines based on DOM events:
+ * - hover: plays on mouseenter, reverses on mouseleave
+ * - click: plays on click with optional toggle behavior (reverse/restart on 2nd click)
+ */
+import type { Timeline } from '../core/Timeline';
+import { BaseTrigger } from './BaseTrigger';
+/** Internal config for EventTrigger */
+export interface EventTriggerConfig {
+    type: 'hover' | 'click';
+    target?: string | Element;
+    secondTarget?: string | Element;
+    toggle?: 'reverse' | 'restart' | 'play';
+    preventDefault?: boolean;
+    onLeave?: 'reverse' | 'pause' | 'stop' | 'restart' | 'none';
+    leaveDelay?: number;
+}
+export declare class EventTrigger extends BaseTrigger<EventTriggerConfig> {
+    private _targets;
+    private _secondTargets;
+    private _listeners;
+    private _isForward;
+    private _frozenRects;
+    private _wasHovering;
+    private _hoverLeaveTimeout;
+    private _boundMouseMoveHandler;
+    constructor(timeline: Timeline, config: EventTriggerConfig);
+    /**
+     * Set up event listeners once DOM is ready.
+     */
+    protected _onEnable(): void;
+    /**
+     * Remove all event listeners and cancel pending timers.
+     */
+    protected _onDisable(): void;
+    /**
+     * Re-snapshot frozen rects after layout changes (e.g. window resize).
+     * Called by TriggerManager.refreshScrollTriggers() on resize.
+     */
+    refresh(): void;
+    private _resolveTargets;
+    private _addHoverListeners;
+    private _handleLeaveAction;
+    private _addClickListeners;
+    private _handleSecondClick;
+}

package/dist/triggers/GestureTrigger.d.ts

@@ -0,0 +1,137 @@
+/**
+ * GestureTrigger
+ *
+ * Detects user gestures (pointer, touch, wheel, scroll) and triggers
+ * timeline actions based on directional movement and interaction events.
+ *
+ * Performance optimizations:
+ * - RAF synchronization for callback execution
+ * - Throttled scroll/wheel event processing
+ * - Cached config values
+ * - Minimal allocations in hot paths
+ */
+import type { GestureConfig } from '../types';
+import type { Timeline } from '../core/Timeline';
+import { BaseTrigger } from './BaseTrigger';
+export declare class GestureTrigger extends BaseTrigger<GestureConfig> {
+    private _target;
+    private _tolerance;
+    private _dragMinimum;
+    private _dragMinimumSquared;
+    private _wheelSpeed;
+    private _scrollSpeed;
+    private _stopDelay;
+    private _preventDefault;
+    private _lockAxis;
+    private _animationStep;
+    private _smooth;
+    private _startX;
+    private _startY;
+    private _deltaX;
+    private _deltaY;
+    private _lockedAxis;
+    private _isPressed;
+    private _isDragging;
+    private _lastDirectionX;
+    private _lastDirectionY;
+    private _lastScrollX;
+    private _lastScrollY;
+    private _stopTimeout;
+    private _isMoving;
+    private _lastActivityTime;
+    private _pendingActions;
+    private _rafScheduled;
+    private _rafId;
+    private _wheelAccumulatorX;
+    private _wheelAccumulatorY;
+    private _wheelRafId;
+    private _scrollRafId;
+    private _lastPointerX;
+    private _lastPointerY;
+    private _activatedDirections;
+    private _targetProgress;
+    private _currentProgress;
+    private _interpolationRafId;
+    private _siblings;
+    private _index;
+    private static _sequenceStates;
+    private _boundHandlers;
+    private _frozenHoverRect;
+    private _gestureHoverActive;
+    private _boundHoverMoveHandler;
+    constructor(timeline: Timeline, config: GestureConfig);
+    /**
+     * Resolve target and attach gesture listeners once DOM is ready.
+     */
+    protected _onEnable(): void;
+    /**
+     * Cancel all pending timers/RAF and remove all event listeners.
+     */
+    protected _onDisable(): void;
+    private _addPointerListeners;
+    private _handlePointerDown;
+    private _handlePointerMove;
+    private _handlePointerUp;
+    private _addTouchListeners;
+    private _handleTouchStart;
+    private _handleTouchMove;
+    private _handleTouchEnd;
+    /**
+     * Shared start logic for pointer and touch input.
+     */
+    private _handleInputStart;
+    /**
+     * Shared move logic for pointer and touch input.
+     * Returns true if movement was processed (caller should preventDefault if needed).
+     */
+    private _handleInputMove;
+    /**
+     * Shared end logic for pointer and touch input.
+     */
+    private _handleInputEnd;
+    private _addWheelListener;
+    private _handleWheel;
+    private _addScrollListener;
+    private _handleScroll;
+    private _processScroll;
+    private _addHoverListeners;
+    /**
+     * Re-snapshot frozen hover rect after layout changes (e.g. window resize).
+     * Called by TriggerManager on resize.
+     */
+    refresh(): void;
+    private _updateDeltas;
+    /**
+     * Check and fire directional callbacks.
+     * @param instant - If true (wheel/scroll), skips axis-lock checks and direction tracking.
+     *                  If false (pointer/touch), respects axis locking and tracks activated directions.
+     */
+    private _checkDirectionAndFire;
+    /**
+     * Check for direction toggle (reversal)
+     */
+    private _checkToggle;
+    private _checkDragStart;
+    private _scheduleStopCheck;
+    private _fireEvent;
+    private _scheduleRAF;
+    private _getStepForEvent;
+    private _executeAction;
+    /**
+     * Play next or previous item in sequence (for each mode)
+     * @param direction 1 for next, -1 for previous
+     */
+    private _playSequenceItem;
+    /**
+     * Smoothly interpolate progress by the given delta.
+     * Uses lerp for continuous scrolling (responsive) with natural ease-out when stopping.
+     */
+    private _interpolateProgress;
+    private _startInterpolationLoop;
+    /**
+     * Fire directional Complete callbacks for any directions that were activated
+     * during this gesture, then clear the tracking set.
+     */
+    private _fireCompleteCallbacks;
+    private _resetGestureState;
+}

package/dist/triggers/MarkerManager.d.ts

@@ -0,0 +1,42 @@
+/**
+ * MarkerManager
+ *
+ * Manages debug markers for ScrollTrigger visualization.
+ * Shows 4 markers:
+ * - scroller-start/end: Fixed position lines showing where triggers fire
+ * - start/end: Element-relative lines showing trigger points on the element
+ */
+import type { MarkerConfig } from '../types';
+interface MarkerSetupConfig {
+    scroller: Element | Window;
+    triggerElement: HTMLElement | null;
+    startConfig: string;
+    endConfig: string;
+    markerConfig: MarkerConfig | boolean;
+    viewportHeight: number;
+}
+export declare class MarkerManager {
+    private _id;
+    private _markers?;
+    private _markerContainer?;
+    private _triggerElement?;
+    private _scrollerStartOffset;
+    private _scrollerEndOffset;
+    private _scroller;
+    private _startConfig;
+    private _endConfig;
+    constructor(triggerId: number);
+    /**
+     * Create debug markers showing trigger positions
+     */
+    setup(config: MarkerSetupConfig): void;
+    /**
+     * Update marker positions on scroll
+     */
+    update(scrollTop: number, triggerElement: HTMLElement | null, viewportHeight: number): void;
+    /**
+     * Remove all markers
+     */
+    cleanup(): void;
+}
+export {};