@motion.page/sdk 0.1.0

package/dist/core/Animation.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Animation - Individual animation unit
+ *
+ * Manages interpolation of properties over time with easing.
+ * Pooled for performance.
+ */
+import type { AnimationTarget, StaggerVars } from '../types';
+/**
+ * Internal animation configuration (not exported from SDK)
+ */
+export interface InternalAnimationConfig {
+    repeat?: number;
+    repeatDelay?: number;
+    yoyo?: boolean;
+    stagger?: number | StaggerVars;
+    onStart?: () => void;
+    onUpdate?: (progress: number) => void;
+    onComplete?: () => void;
+    onRepeat?: (repeatCount: number) => void;
+    onReverseComplete?: () => void;
+    /**
+     * When true, Engine skips the immediate render(0) for FROM animations.
+     * Used by Timeline._addBuilder so it can capture initial values BEFORE
+     * FROM values are applied to the DOM, then render FROM itself afterward.
+     */
+    _skipInitialRender?: boolean;
+}
+import { PropTween } from './PropTween';
+import { PropTweenPool } from '../memory/PropTweenPool';
+export declare class Animation {
+    private _id;
+    private _targets;
+    private _duration;
+    private _delay;
+    private _time;
+    private _progress;
+    private _timeScale;
+    private _isActive;
+    private _isReversed;
+    private _propTweens;
+    private _lastPropTween;
+    private _easingFn;
+    private _repeat;
+    private _repeatDelay;
+    private _yoyo;
+    private _currentRepeat;
+    private _onStart?;
+    private _onUpdate?;
+    private _onComplete?;
+    private _onRepeat?;
+    private _onReverseComplete?;
+    private _startFired;
+    private _completeFired;
+    private _timelineChild;
+    private _needsStartCapture;
+    private _startCaptured;
+    private _fitSetupFn;
+    private _pendingFitSetup;
+    private _unregisterCallback;
+    /**
+     * Initialize the animation
+     */
+    init(id: number, targets: AnimationTarget[], duration: number, delay: number, ease: string, config?: InternalAnimationConfig): this;
+    /**
+     * Update animation by delta time
+     */
+    update(deltaTime: number): void;
+    /**
+     * Render animation at specific progress (0-1)
+     */
+    render(progress: number): void;
+    /**
+     * Render animation at an absolute time position (seconds)
+     * Handles repeat, repeatDelay, and yoyo for timeline-driven scrubbing.
+     * When driven by a Timeline (_isActive = true), also fires lifecycle callbacks.
+     */
+    renderAtTime(totalTime: number): void;
+    /**
+     * Apply easing function to progress
+     */
+    private applyEasing;
+    /**
+     * Handle animation completion
+     */
+    private handleComplete;
+    /**
+     * Play the animation
+     * - If already playing forward, does nothing
+     * - If paused, resumes from current position
+     */
+    play(from?: number): this;
+    /**
+     * Pause the animation
+     */
+    pause(atTime?: number): this;
+    /**
+     * Reverse the animation
+     */
+    reverse(from?: number): this;
+    /**
+     * Restart the animation
+     */
+    restart(includeDelay?: boolean): this;
+    /**
+     * Seek to specific position
+     */
+    seek(position: number): this;
+    /**
+     * Get/set progress (0-1)
+     */
+    progress(): number;
+    progress(value: number): this;
+    /**
+     * Get/set time in seconds
+     */
+    time(): number;
+    time(value: number): this;
+    /**
+     * Get/set timeScale multiplier
+     */
+    timeScale(): number;
+    timeScale(value: number): this;
+    /**
+     * Get timeScale multiplier (typed getter)
+     */
+    getTimeScale(): number;
+    /**
+     * Kill the animation
+     */
+    kill(): void;
+    /**
+     * Check if animation is active
+     */
+    isActive(): boolean;
+    /**
+     * Check if this animation is a child of a Timeline
+     * When true, Engine won't update or auto-pool this animation
+     */
+    isTimelineChild(): boolean;
+    /**
+     * Set whether this animation is a child of a Timeline
+     * Timeline children are controlled by their parent timeline and
+     * won't be auto-pooled until the timeline is killed
+     */
+    setTimelineChild(isChild: boolean): void;
+    /**
+     * Enable lazy start value capture (for timeline chaining)
+     * When enabled, start values are captured on first render instead of at creation
+     */
+    setLazyStartCapture(enabled: boolean): void;
+    /**
+     * Register a Fit setup function to execute at play time.
+     * Stores both a persistent copy (_fitSetupFn) for replay and an active
+     * copy (_pendingFitSetup) that is consumed by captureStartValues().
+     */
+    setPendingFitSetup(fn: (pool: typeof PropTweenPool) => void): void;
+    /**
+     * Reset for timeline replay
+     * Resets callback state for clean replay but KEEPS captured start values
+     * so TO-only animations replay from their original start position.
+     * Fit animations re-enable their setup so geometry is re-captured on the
+     * next play (picking up any intervening DOM changes).
+     */
+    resetForReplay(): void;
+    /**
+     * Check if this animation needs lazy start capture but hasn't captured yet
+     * Used by Timeline to trigger capture when animation starts
+     */
+    needsStartCapture(): boolean;
+    /**
+     * Check if this animation uses lazy start capture (TO-only animation)
+     * These animations should NEVER render before their start time,
+     * even after values have been captured, to avoid overwriting earlier animations
+     */
+    isLazyCapture(): boolean;
+    /**
+     * Fire the onReverseComplete callback and reset start/complete flags.
+     * Called by Timeline when an active animation exits the start boundary (going in reverse).
+     * Resetting flags allows onStart and onComplete to fire correctly on the next forward play.
+     */
+    fireReverseComplete(): void;
+    /**
+     * Set callback for unregistering from Engine (called on kill)
+     * This avoids circular dependency with Engine
+     */
+    setUnregisterCallback(callback: () => void): void;
+    /**
+     * Capture current element values as start values for all PropTweens
+     * This enables proper chaining in timelines
+     */
+    captureStartValues(): void;
+    /**
+     * Get animation ID
+     */
+    getId(): number;
+    /**
+     * Get animation targets
+     */
+    getTargets(): AnimationTarget[];
+    /**
+     * Get duration
+     */
+    getDuration(): number;
+    /**
+     * Get delay (used by Timeline for stagger positioning)
+     */
+    getDelay(): number;
+    /**
+     * Clear delay (used by Timeline after extracting delay for positioning)
+     */
+    clearDelay(): void;
+    /**
+     * Get the head of the PropTween linked list.
+     * @internal - Use only within sdk package for property inspection (e.g. captureStartValues).
+     */
+    getFirstPropTween(): PropTween | null;
+    /**
+     * Add a property tween to the linked list
+     */
+    addPropTween(propTween: PropTween): void;
+    /**
+     * Get animation duration (including delay and repeats)
+     * Returns Infinity for infinitely repeating animations (_repeat === -1).
+     */
+    totalDuration(): number;
+    /**
+     * Reset for object pooling
+     */
+    reset(): void;
+}

package/dist/core/AnimationBuilder.d.ts

@@ -0,0 +1,125 @@
+/**
+ * AnimationBuilder - Config-based animation creator
+ *
+ * Creates animations from configuration objects.
+ * Used internally by Motion() function.
+ */
+import type { AnimationVars, AnimationTarget, TargetInput, StaggerVars, SplitType, AnimationConfig, FitConfig } from '../types';
+/**
+ * Internal builder configuration for cloning (not exported from SDK)
+ */
+interface BuilderConfig {
+    fromVars?: AnimationVars;
+    toVars?: AnimationVars;
+    duration: number;
+    delay: number;
+    ease: string;
+    axis?: 'x' | 'y';
+    fit?: FitConfig;
+    split?: SplitType;
+    mask?: boolean;
+    stagger?: number | StaggerVars;
+    repeat?: number;
+    repeatDelay?: number;
+    yoyo?: boolean;
+    onStart?: () => void;
+    onUpdate?: (progress: number) => void;
+    onComplete?: () => void;
+    onRepeat?: (repeatCount: number) => void;
+    onReverseComplete?: () => void;
+}
+import { Animation } from './Animation';
+export declare class AnimationBuilder {
+    /**
+     * Callback to create animations via Engine (set by Engine to avoid circular dependency)
+     * Engine→Timeline→AnimationBuilder→Engine cycle is broken by this callback.
+     */
+    private static _createAnimationCallback;
+    static setCreateAnimationCallback(callback: typeof AnimationBuilder._createAnimationCallback): void;
+    private _targets;
+    private _originalTargets;
+    private _fromVars?;
+    private _toVars?;
+    private _duration;
+    private _delay;
+    private _ease;
+    private _animation;
+    private _animations;
+    private _built;
+    private _splitType?;
+    private _mask?;
+    private _repeat?;
+    private _repeatDelay?;
+    private _yoyo?;
+    private _stagger?;
+    private _axis?;
+    private _fitConfig?;
+    private _onStart?;
+    private _onUpdate?;
+    private _onComplete?;
+    private _onRepeat?;
+    private _onReverseComplete?;
+    private _skipInitialFromRender;
+    private _plainObjectInitialValues;
+    private _expectedAnimationIds;
+    private _propsToAnimate;
+    /**
+     * Create an animation builder
+     * @param targets - Elements or objects to animate
+     * @param config - Animation configuration
+     */
+    constructor(targets: TargetInput, config?: AnimationConfig);
+    /**
+     * Apply animation config
+     */
+    private _applyAnimationConfig;
+    /**
+     * Capture initial values from plain object targets
+     */
+    private _capturePlainObjectValues;
+    /**
+     * Restore plain object targets to initial values
+     */
+    private _restorePlainObjectValues;
+    private _ensureBuilt;
+    /**
+     * Check if animations have been invalidated (pooled or reused)
+     */
+    private _isInvalidated;
+    /**
+     * Rebuild if animations were pooled
+     */
+    rebuildIfPooled(): void;
+    private _build;
+    getAnimation(): Animation | null;
+    getAnimations(): Animation[];
+    getTargets(): AnimationTarget[];
+    /**
+     * Get the original (pre-split) targets. When text splitting is used,
+     * _targets holds the split fragments; _originalTargets holds the source elements.
+     */
+    getOriginalTargets(): AnimationTarget[];
+    /**
+     * Whether this builder uses text splitting
+     */
+    hasSplit(): boolean;
+    private _resetBuildState;
+    /**
+     * Get builder configuration for cloning (used by Timeline's each mode)
+     */
+    getConfig(): BuilderConfig;
+    /**
+     * Set axis for mouse movement binding
+     */
+    setAxis(axis: 'x' | 'y'): void;
+    /**
+     * Get axis binding
+     */
+    getAxis(): 'x' | 'y' | undefined;
+    /**
+     * Tell Engine to skip the immediate FROM render (animation.render(0)).
+     * Used by Timeline so it can capture initial values BEFORE FROM is applied.
+     */
+    setSkipInitialFromRender(skip: boolean): void;
+}
+export {};

package/dist/core/Engine.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Engine Singleton - Central animation registry and coordinator
+ *
+ * Manages:
+ * - Global animation registry
+ * - Named timeline registry
+ * - Object pool coordination
+ * - Ticker integration
+ * - Render queue routing
+ */
+import { Ticker } from './Ticker';
+import { Animation } from './Animation';
+import { Timeline } from './Timeline';
+import { AnimationPool } from '../memory/AnimationPool';
+import { PropTweenPool } from '../memory/PropTweenPool';
+import type { AnimationVars, AnimationTarget } from '../types';
+import type { InternalAnimationConfig } from './Animation';
+export declare class Engine {
+    private static instance;
+    private animations;
+    private animationIdToIndex;
+    private nextAnimationId;
+    private totalCreated;
+    private _animationSnapshot;
+    private timelines;
+    private ticker;
+    private animationPool;
+    private propTweenPool;
+    private constructor();
+    /**
+     * Get the singleton Engine instance
+     */
+    static getInstance(): Engine;
+    /**
+     * Main update loop called by Ticker
+     */
+    private update;
+    /**
+     * Create a new animation (called by AnimationBuilder)
+     * Returns either a single Animation or an array of Animations (for stagger)
+     */
+    createAnimation(targets: AnimationTarget[], vars: AnimationVars, duration: number, delay: number, ease: string, isFrom: boolean, fromVars?: AnimationVars, config?: InternalAnimationConfig): Animation | Animation[];
+    /**
+     * Create staggered animations - one animation per target
+     */
+    private createStaggeredAnimations;
+    /**
+     * Set up property tweens for an animation
+     */
+    private setupPropertyTweens;
+    /**
+     * Register an animation with the engine
+     */
+    registerAnimation(animation: Animation): number;
+    /**
+     * Unregister an animation from the engine
+     * Uses swap-and-pop for O(1) removal
+     */
+    unregisterAnimation(id: number): void;
+    /**
+     * Get an animation by ID
+     */
+    getAnimation(id: number): Animation | undefined;
+    /**
+     * Kill all animations
+     */
+    killAll(): void;
+    /**
+     * Kill all animations targeting specific elements
+     * Used by Motion.reset() to stop animations before clearing styles
+     */
+    killAnimationsForTargets(targets: Element[]): void;
+    /**
+     * Get active animation count
+     */
+    getActiveCount(): number;
+    /**
+     * Get total animations created
+     */
+    getTotalCreated(): number;
+    /**
+     * Get or create a named timeline
+     */
+    getTimeline(name: string): Timeline;
+    /**
+     * Check if timeline exists
+     */
+    hasTimeline(name: string): boolean;
+    /**
+     * Register a timeline
+     */
+    registerTimeline(name: string, timeline: Timeline): void;
+    /**
+     * Get timeline count
+     */
+    getTimelineCount(): number;
+    /**
+     * Get all timeline names
+     */
+    getTimelineNames(): string[];
+    /**
+     * Remove a timeline from registry (called after kill)
+     */
+    removeTimeline(name: string): void;
+    /**
+     * Kill all timelines and their triggers
+     */
+    killAllTimelines(): void;
+    /**
+     * Kill everything - all animations, all timelines, and cleanup resources
+     */
+    killEverything(): void;
+    /**
+     * Get animation pool
+     */
+    getAnimationPool(): AnimationPool;
+    /**
+     * Get PropTween pool
+     */
+    getPropTweenPool(): PropTweenPool;
+    /**
+     * Get pool statistics
+     */
+    getPoolStats(): {
+        animations: number;
+        propTweens: number;
+    };
+    /**
+     * Clear all pools (for debugging)
+     */
+    clearPools(): void;
+    /**
+     * Get memory estimate in bytes
+     */
+    getMemoryEstimate(): number;
+    /**
+     * Get ticker reference
+     */
+    getTicker(): Ticker;
+}

package/dist/core/Motion.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Motion API - Unified entry point for animations
+ *
+ * All animations are named timelines. Config-based API for consistency.
+ *
+ * @example Single animation
+ * Motion('fadeIn', '.box', {
+ *   from: { opacity: 0 },
+ *   to: { opacity: 1 },
+ *   duration: 0.5
+ * }).play()
+ *
+ * @example Multi-animation timeline
+ * Motion('hero', [
+ *   { target: '.title', from: { y: 50 }, to: { y: 0 }, duration: 1 },
+ *   { target: '.subtitle', from: { opacity: 0 }, to: { opacity: 1 }, position: 0.5 }
+ * ]).play()
+ *
+ * @example With trigger
+ * Motion('scroll', '.box', { from: { x: -100 }, to: { x: 0 } })
+ *   .onScroll({ scrub: true })
+ *
+ * @example Replay
+ * Motion('fadeIn').play()
+ */
+import type { TargetInput, AnimationConfig, AnimationEntry, AnimationVars } from '../types';
+import { Timeline } from './Timeline';
+/**
+ * Motion function overloads
+ */
+declare function MotionFunction(name: string): Timeline;
+declare function MotionFunction(name: string, target: TargetInput, config: AnimationConfig): Timeline;
+declare function MotionFunction(name: string, animations: AnimationEntry[]): Timeline;
+declare namespace MotionFunction {
+    var reset: (targets: TargetInput) => void;
+    var set: (target: TargetInput, vars: AnimationVars) => void;
+    var get: (name: string) => Timeline | undefined;
+    var has: (name: string) => boolean;
+    var getNames: () => string[];
+    var kill: (name: string) => void;
+    var killAll: () => void;
+    var refreshScrollTriggers: () => void;
+    var cleanup: () => void;
+    var utils: {
+        readonly toArray: typeof import("../utils/MotionUtils").toArray;
+        readonly clamp: typeof import("../utils/MotionUtils").clamp;
+        readonly random: typeof import("../utils/MotionUtils").random;
+        readonly snap: typeof import("../utils/MotionUtils").snap;
+        readonly interpolate: typeof import("../utils/MotionUtils").interpolate;
+        readonly mapRange: typeof import("../utils/MotionUtils").mapRange;
+        readonly normalize: typeof import("../utils/MotionUtils").normalize;
+        readonly wrap: typeof import("../utils/MotionUtils").wrap;
+    };
+}
+export declare const Motion: typeof MotionFunction;
+export {};

package/dist/core/PropTween.d.ts

@@ -0,0 +1,81 @@
+/**
+ * PropTween - Individual property interpolation unit
+ *
+ * Linked list node for animating a single property.
+ * Pooled for performance.
+ * Supports scalar values, color (RGBA), and filter interpolation.
+ */
+import type { AnimationTarget } from '../types';
+import type { ParsedFilterFunction } from '../utils/FilterParser';
+import type { ParsedDrawSVG } from '../utils/DrawSVGParser';
+import { type PathPoint } from '../utils/PathParser';
+type PropTweenValueType = 'scalar' | 'color' | 'filter' | 'drawSVG' | 'path';
+export declare class PropTween {
+    target: AnimationTarget | null;
+    property: string;
+    startValue: number;
+    endValue: number;
+    change: number;
+    unit: string;
+    next: PropTween | null;
+    valueType: PropTweenValueType;
+    startColor: Float32Array | null;
+    endColor: Float32Array | null;
+    changeColor: Float32Array;
+    startFilters: ParsedFilterFunction[] | null;
+    endFilters: ParsedFilterFunction[] | null;
+    startDraw: ParsedDrawSVG | null;
+    endDraw: ParsedDrawSVG | null;
+    pathLength: number;
+    pathData: string | null;
+    motionPathLength: number;
+    startProgress: number;
+    endProgress: number;
+    pathRotate: boolean;
+    alignOffset: {
+        x: number;
+        y: number;
+    } | null;
+    pathOffset: {
+        x: number;
+        y: number;
+    } | null;
+    pathLUT: PathPoint[] | null;
+    private _isElement;
+    /**
+     * Initialize the PropTween with scalar values
+     */
+    init(target: AnimationTarget, property: string, startValue: number, endValue: number, unit?: string): this;
+    /**
+     * Initialize the PropTween with color values
+     */
+    initColor(target: AnimationTarget, property: string, startColor: Float32Array, endColor: Float32Array): this;
+    /**
+     * Initialize the PropTween with filter values
+     */
+    initFilter(target: AnimationTarget, property: string, startFilters: ParsedFilterFunction[], endFilters: ParsedFilterFunction[]): this;
+    /**
+     * Initialize the PropTween with drawSVG values
+     */
+    initDrawSVG(target: AnimationTarget, property: string, startDraw: ParsedDrawSVG, endDraw: ParsedDrawSVG, pathLength: number): this;
+    /**
+     * Initialize the PropTween with path (motion path) values
+     * Pre-samples the path into a lookup table for O(1) rendering
+     */
+    initPath(target: AnimationTarget, property: string, pathData: string, pathLength: number, startProgress: number, endProgress: number, rotate: boolean, alignOffset: {
+        x: number;
+        y: number;
+    }, pathOffset: {
+        x: number;
+        y: number;
+    }): this;
+    /**
+     * Render the property at given progress (0-1)
+     */
+    render(progress: number): void;
+    /**
+     * Reset for object pooling
+     */
+    reset(): void;
+}
+export {};