@motion.page/sdk 0.1.0

package/dist/core/Ticker.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Ticker Singleton - Single RAF loop for all animations
+ *
+ * Manages the requestAnimationFrame loop with:
+ * - Lag smoothing (cap delta when tab backgrounded)
+ * - Priority-based listener ordering
+ * - Automatic start/stop based on listener count
+ * - Batched DOM writes at end of frame via RenderBatch
+ */
+/**
+ * Fast check if we're inside a tick (exported for hot path performance)
+ * Use this instead of Ticker.getInstance().isInTick() in render code
+ */
+export declare function isInTick(): boolean;
+/**
+ * Run a callback in "tick mode" — writes are batched, then flushed at the end.
+ *
+ * Use this when updating timeline progress from outside the RAF loop
+ * (e.g. scroll event handlers) to avoid layout thrashing from immediate
+ * per-property DOM writes. The callback's DOM mutations are queued via
+ * RenderBatch and flushed in a single pass after the callback returns.
+ */
+export declare function runBatched(callback: () => void): void;
+type TickerListener = (deltaTime: number, elapsedTime: number) => void;
+export declare class Ticker {
+    private static instance;
+    private listeners;
+    private _listenersDirty;
+    private _listenersSnapshot;
+    private _isRunning;
+    private rafId;
+    private lastTime;
+    private elapsedTime;
+    private lagThreshold;
+    private maxDelta;
+    private fpsFrames;
+    private fpsTime;
+    private currentFPS;
+    private lastFrameTime;
+    private constructor();
+    /**
+     * Get the singleton Ticker instance
+     */
+    static getInstance(): Ticker;
+    /**
+     * Add a listener to the ticker
+     * @param callback Function to call on each tick
+     * @param priority Higher priority callbacks execute first (default: 0)
+     */
+    add(callback: TickerListener, priority?: number): void;
+    /**
+     * Remove a listener from the ticker
+     * @param callback Function to remove
+     */
+    remove(callback: TickerListener): void;
+    /**
+     * Start the RAF loop
+     */
+    private start;
+    /**
+     * Stop the RAF loop
+     */
+    private stop;
+    /**
+     * Pause the ticker (for debug purposes)
+     */
+    pause(): void;
+    /**
+     * Resume the ticker (for debug purposes)
+     */
+    resume(): void;
+    /**
+     * Main tick function called by RAF
+     */
+    private tick;
+    /**
+     * Update FPS calculation
+     */
+    private updateFPS;
+    /**
+     * Get current FPS
+     */
+    getFPS(): number;
+    /**
+     * Get last frame delta time in ms
+     */
+    getLastDelta(): number;
+    /**
+     * Check if ticker is running
+     */
+    isRunning(): boolean;
+    /**
+     * Check if we're currently inside a tick
+     * Used by render system to decide: queue (in tick) or write immediately (outside tick)
+     * Note: For hot path performance, use the exported isInTick() function instead
+     */
+    isInTick(): boolean;
+    /**
+     * Get listener count
+     */
+    getListenerCount(): number;
+    /**
+     * Remove all listeners (for testing)
+     */
+    removeAll(): void;
+}
+export {};

package/dist/core/Timeline.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Timeline for sequencing animations
+ *
+ * Features:
+ * - Named timeline registry (create/retrieve by name)
+ * - Position parameter support (absolute, +=, -=, <, >)
+ * - Nested timelines
+ * - Callback scheduling
+ * - Control methods (play, pause, reverse, seek, etc.)
+ * - Trigger system integration
+ */
+import type { HoverConfig, ClickConfig, ScrollConfig, MouseMoveConfig, GestureConfig, CursorConfig, PageExitConfig, TargetInput, AnimationConfig } from '../types';
+import { Animation } from './Animation';
+export declare class Timeline {
+    /** Monotonic counter for generating unique each-mode instance names */
+    private static _eachCounter;
+    /**
+     * Static callback for registering named timelines with Engine.
+     * Set by Engine.getInstance() to break circular dependency.
+     * @internal
+     */
+    private static _registerWithEngine;
+    /**
+     * Set the engine registration callback. Called once by Engine during initialization.
+     * @internal
+     */
+    static setEngineRegisterCallback(callback: (name: string, timeline: Timeline) => void): void;
+    private _name?;
+    private _children;
+    private _duration;
+    private _time;
+    private _progress;
+    private _timeScale;
+    private _isActive;
+    private _isReversed;
+    private _killed;
+    private _onStart?;
+    private _onUpdate?;
+    private _onComplete?;
+    private _startFired;
+    /**
+     * Reference to attached trigger (for cleanup in kill()).
+     * @internal
+     */
+    _trigger?: {
+        disable(): void;
+    };
+    /** @internal */
+    private _unregisterCallback?;
+    /**
+     * Set unregister callback for cleanup. Called by Engine after registration.
+     * @internal
+     */
+    setUnregisterCallback(callback: () => void): void;
+    private _previousStart;
+    private _previousEnd;
+    private _eachInstances?;
+    private _eachDuration?;
+    private _initialValues;
+    private _initialTransforms;
+    private _transformElements;
+    private _savedTransitions;
+    private _transitionsDisabled;
+    private _savedWillChange;
+    constructor(name?: string);
+    /**
+     * Get timeline duration
+     */
+    duration(): number;
+    /**
+     * Clear timeline state for rebuild (used for re-triggerable animations)
+     * Kills existing animations, clears children, resets state
+     */
+    clear(): this;
+    /**
+     * Capture initial values for an animation's properties (called once per property per element)
+     */
+    private _captureInitialValues;
+    /**
+     * Restore all elements to their initial property values (used when seeking to position 0)
+     */
+    private _restoreInitialValues;
+    /**
+     * Disable CSS transitions on all animated elements.
+     * Called when the timeline starts playing to prevent CSS transitions
+     * from fighting frame-by-frame SDK rendering.
+     */
+    private _disableTransitions;
+    /**
+     * Restore original CSS transition values on all animated elements.
+     * Called on timeline completion and kill to re-enable CSS hover/focus
+     * transitions after the SDK animation is done.
+     */
+    private _restoreTransitions;
+    /**
+     * Clear all saved transition data (for kill/clear).
+     */
+    private _clearTransitionData;
+    /**
+     * Restore original will-change values on elements promoted for transforms.
+     */
+    private _restoreWillChange;
+    /**
+     * Internal: Add animation entry (used by Motion function)
+     * @internal
+     */
+    _addEntry(target: TargetInput, config: AnimationConfig, position?: string | number): this;
+    /**
+     * Internal method to add an AnimationBuilder directly
+     */
+    private _addBuilder;
+    /**
+     * Call function at position
+     */
+    call(callback: (...args: unknown[]) => void, params?: unknown[], position?: string | number): this;
+    /**
+     * Get the first animation's target element for trigger inference
+     * Note: Returns only DOM Elements, not plain objects
+     */
+    private _getFirstAnimationTarget;
+    /**
+     * Get all target elements from the first animation (for each mode)
+     * Note: Returns only DOM Elements, not plain objects
+     *
+     * When the builder uses text splitting (split: 'words' etc.), the animation's
+     * targets are the split fragments — but for each-mode we need the ORIGINAL
+     * pre-split elements so each gets its own ScrollTrigger. The cloned builder
+     * will re-split inside that element independently.
+     */
+    private _getAllAnimationTargets;
+    /**
+     * Create a timeline instance for a single element (for each mode)
+     * This clones the timeline structure but only targets the specific element.
+     */
+    private _createInstanceForElement;
+    /**
+     * Create a timeline instance for multiple elements (for each mode with explicit container target).
+     * This is a sibling of _createInstanceForElement — the only difference is that it accepts an
+     * Element[] and passes the array directly to AnimationBuilder instead of a single element.
+     */
+    private _createInstanceForElements;
+    /**
+     * Resolve a CSS selector string or Element into an array of DOM elements.
+     */
+    private _resolveTargetElements;
+    /**
+     * Generic helper for each-mode setup: resolve targets, create instances, register triggers.
+     * The setupTrigger callback receives each (instance, element) pair for trigger-specific registration.
+     */
+    private _setupEachModeGeneric;
+    /**
+     * Set up each-mode: create independent timeline instances for each target element
+     */
+    private _setupEachMode;
+    /**
+     * Trigger timeline on hover (mouseenter plays, mouseleave configurable)
+     */
+    onHover(config?: HoverConfig): this;
+    /**
+     * Trigger timeline on click
+     */
+    onClick(config?: ClickConfig): this;
+    /**
+     * Trigger timeline on scroll
+     */
+    onScroll(config?: ScrollConfig): this;
+    /**
+     * Trigger timeline on mouse movement
+     * Drives animation progress based on mouse position (axis mode) or distance from center (distance mode)
+     */
+    onMouseMove(config?: MouseMoveConfig): this;
+    /**
+     * Set up each-mode for mouse movement: create independent timeline instances for each target element
+     */
+    private _setupMouseMoveEachMode;
+    /**
+     * Trigger timeline on page load
+     */
+    onPageLoad(): this;
+    /**
+     * Trigger timeline when user navigates away from the page (clicks a link).
+     * Intercepts the click, plays the exit animation, then navigates to the target URL.
+     */
+    onPageExit(config?: PageExitConfig): this;
+    /**
+     * Trigger timeline based on user gestures (pointer, touch, wheel, scroll)
+     * Maps directional callbacks to timeline actions
+     */
+    onGesture(config: GestureConfig): this;
+    /**
+     * Set up each-mode for gesture: create independent instances for each target element
+     */
+    private _setupGestureEachMode;
+    /**
+     * Attach cursor behavior to this timeline's target element
+     * Creates a custom cursor that follows mouse with smooth tracking and state-based animations
+     */
+    onCursor(config: CursorConfig): this;
+    /**
+     * Update a callback child: fire when time crosses its position
+     */
+    private _updateCallbackChild;
+    /**
+     * Update an animation child: seek/activate/deactivate based on parent time
+     */
+    private _updateAnimationChild;
+    /**
+     * Update a nested timeline child: seek/activate/deactivate based on parent time
+     */
+    private _updateTimelineChild;
+    /**
+     * Update timeline by delta time
+     */
+    update(deltaTime: number): void;
+    /**
+     * Play timeline from position.
+     * If already playing forward, continues from current position.
+     */
+    play(from?: number): this;
+    /**
+     * Pause timeline at time
+     */
+    pause(atTime?: number): this;
+    /**
+     * Reverse timeline from position.
+     * If already reversing, continues from current position.
+     */
+    reverse(from?: number): this;
+    /**
+     * Restart timeline
+     */
+    restart(): this;
+    /**
+     * Render only position-0 (non-lazy) animations at their start state
+     */
+    private _renderPositionZeroAnimations;
+    /**
+     * Seek to position
+     */
+    seek(position: number): this;
+    /**
+     * Set progress for animations bound to a specific axis (for mouse movement trigger)
+     * Only affects animations that have .axis() set to the specified axis.
+     * @param axis - 'x' or 'y'
+     * @param value - Progress value (0-1)
+     */
+    setAxisProgress(axis: 'x' | 'y', value: number): this;
+    /**
+     * Set callback for when timeline starts playing
+     */
+    onStart(callback: () => void): this;
+    /**
+     * Set callback for progress updates (called every frame while active)
+     * @param callback - Receives (progress: 0-1, time: seconds)
+     */
+    onUpdate(callback: (progress: number, time: number) => void): this;
+    /**
+     * Set callback for when timeline completes
+     */
+    onComplete(callback: () => void): this;
+    /**
+     * Get or set progress (0-1)
+     */
+    progress(): number;
+    progress(value: number): this;
+    /**
+     * Get or set time in seconds
+     */
+    time(): number;
+    time(value: number): this;
+    /**
+     * Get or set time scale (speed multiplier)
+     */
+    timeScale(): number;
+    timeScale(value: number): this;
+    /**
+     * Kill timeline and all children, reset all state
+     * @param clearProps - If true (default), restore elements to their initial CSS values
+     */
+    kill(clearProps?: boolean): void;
+    /**
+     * Check if timeline is currently active
+     */
+    isActive(): boolean;
+    /**
+     * Get timeline name
+     */
+    getName(): string | undefined;
+    /**
+     * Get first child animation (for trigger target resolution).
+     * @internal
+     */
+    getFirstChildAnimation(): Animation | null;
+}

package/dist/easing/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Easing Functions
+ *
+ * All easings are based on Robert Penner's easing equations
+ * and normalized to accept/return values in the 0-1 range
+ */
+import type { EasingFunction } from '../types';
+export declare const linear: (t: number) => number;
+export declare const none: (t: number) => number;
+export declare const power1: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const power2: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const power3: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const power4: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const sine: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const expo: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const circ: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const back: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const elastic: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const bounce: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+/**
+ * Get an easing function by string name
+ * @param name Easing name (case insensitive)
+ * @returns Easing function, or power1.out if not found
+ */
+export declare function getEasing(name: string): EasingFunction;

package/dist/fit/FitResolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * FitResolver — SDK-native Fit animation geometry resolution
+ *
+ * Captures source and target element bounding rects at play time,
+ * computes position and scale deltas, and creates PropTweens that
+ * animate the source element toward the target's geometry.
+ *
+ * Non-absolute mode (default): animates CSS transforms (x, y, scaleX, scaleY)
+ * Resize mode: animates CSS transforms (x, y) + width/height properties (no content distortion)
+ * Absolute mode: animates CSS left/top/width/height properties
+ */
+export {};