@motion.page/sdk 0.1.0

package/dist/triggers/MouseMoveTrigger.d.ts

@@ -0,0 +1,49 @@
+/**
+ * MouseMoveTrigger
+ *
+ * Triggers timelines based on mouse movement:
+ * - distance: progress based on distance from center of viewport/target
+ * - axis: progress based on X/Y position within viewport/target
+ *
+ * Supports:
+ * - Viewport or custom target element tracking
+ * - Optional smoothing (lerp interpolation)
+ * - Custom start/leave progress values
+ * - Per-element triggers with "each" mode
+ */
+import type { MouseMoveConfig } from '../types';
+import type { Timeline } from '../core/Timeline';
+import { BaseTrigger } from './BaseTrigger';
+export declare class MouseMoveTrigger extends BaseTrigger<MouseMoveConfig> {
+    private _targets;
+    private _listeners;
+    private _frozenRects;
+    private _state;
+    private _targetState;
+    private _tickerCallback?;
+    private readonly _defaultStartProgress;
+    private readonly _defaultLeaveProgress;
+    constructor(timeline: Timeline, config: MouseMoveConfig);
+    /**
+     * Set up mouse event listeners once DOM is ready.
+     */
+    protected _onEnable(): void;
+    /**
+     * Remove all event listeners and stop the smoothing ticker.
+     */
+    protected _onDisable(): void;
+    private _addViewportListeners;
+    /**
+     * Re-snapshot frozen rects after layout changes (e.g. window resize).
+     * Called by TriggerManager on resize.
+     */
+    refresh(): void;
+    private _addTargetListeners;
+    private _handleViewportMouseMove;
+    private _handleTargetMouseMove;
+    private _handleMouseLeave;
+    private _applyProgress;
+    private _startSmoothingTicker;
+    private _lerp;
+    private _updateTimelineProgress;
+}

package/dist/triggers/PageExitTrigger.d.ts

@@ -0,0 +1,74 @@
+/**
+ * PageExitTrigger
+ *
+ * Triggers timeline playback when a user clicks a link that would navigate away
+ * from the current page. Intercepts the click, plays the exit animation, then
+ * navigates to the target URL after the timeline completes.
+ *
+ * Supports three link selection modes:
+ * - 'all': intercept all navigation links (default)
+ * - 'include': only intercept links matching specific selectors
+ * - 'exclude': intercept all links except those matching specific selectors
+ *
+ * Supports skipping certain href patterns:
+ * - 'anchor': skip # links (same-page anchors)
+ * - 'javascript': skip javascript: hrefs
+ * - 'mailto': skip mailto: and tel: hrefs
+ *
+ * Works on all websites — no server-side dependencies (PHP, Node, etc.).
+ */
+import type { Timeline } from '../core/Timeline';
+import { BaseTrigger } from './BaseTrigger';
+/** Configuration for PageExitTrigger */
+export interface PageExitTriggerConfig {
+    /** Link selection mode: 'all' (default), 'include', or 'exclude' */
+    mode?: 'all' | 'include' | 'exclude';
+    /** CSS selector(s) for links — required for 'include'/'exclude' modes */
+    selectors?: string;
+    /** Href patterns to skip (never intercept) */
+    skipHref?: ('anchor' | 'javascript' | 'mailto')[];
+}
+export declare class PageExitTrigger extends BaseTrigger<PageExitTriggerConfig> {
+    private _links;
+    private _listeners;
+    private _isNavigating;
+    private _pendingUrl;
+    private _onCompleteHandler;
+    private _pollTimerId;
+    constructor(timeline: Timeline, config: PageExitTriggerConfig);
+    /**
+     * Set up click listeners on qualifying links once DOM is ready.
+     */
+    protected _onEnable(): void;
+    /**
+     * Remove all click listeners and cancel pending navigation.
+     */
+    protected _onDisable(): void;
+    /**
+     * Detect if we're running inside the Motion.page builder iframe.
+     * Exit animations should not intercept clicks in the builder.
+     */
+    private _isInsideBuilder;
+    /**
+     * Resolve which <a> elements should be intercepted based on config mode.
+     */
+    private _resolveLinks;
+    /**
+     * Determine if a link should be intercepted based on its href and skipHref config.
+     * Skips links that don't actually navigate away.
+     */
+    private _shouldIntercept;
+    /**
+     * Attach click listeners to all resolved links.
+     */
+    private _addClickListeners;
+    /**
+     * Wait for the timeline to complete, then navigate.
+     * Uses requestAnimationFrame polling to check timeline progress.
+     */
+    private _waitForCompletion;
+    /**
+     * Navigate to the pending URL.
+     */
+    private _navigate;
+}

package/dist/triggers/PageLoadTrigger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PageLoadTrigger
+ *
+ * Triggers timelines based on page load events:
+ * - timing: 'before' - plays immediately (before DOMContentLoaded)
+ * - timing: 'during' - plays on DOMContentLoaded
+ * - timing: 'after' - plays on window load event
+ */
+import type { Timeline } from '../core/Timeline';
+import type { PageLoadTriggerConfig } from './TriggerManager';
+export declare class PageLoadTrigger {
+    private _registrations;
+    private _domContentLoaded;
+    private _windowLoaded;
+    private _initialized;
+    constructor();
+    private _initialize;
+    /**
+     * Register a timeline with pageLoad trigger
+     */
+    register(timeline: Timeline, config: PageLoadTriggerConfig): void;
+    /**
+     * Unregister a timeline from page load trigger
+     */
+    unregister(timeline: Timeline): void;
+    /**
+     * Clear all registrations
+     */
+    clear(): void;
+    private _triggerDuring;
+    private _triggerAfter;
+    /**
+     * Reset for testing - DO NOT USE IN PRODUCTION
+     * @internal
+     */
+    _reset(): void;
+}

package/dist/triggers/PinManager.d.ts

@@ -0,0 +1,131 @@
+/**
+ * PinManager
+ *
+ * Handles element pinning during scroll animations.
+ * Extracted from ScrollTrigger for better separation of concerns.
+ *
+ * Two pinning strategies based on scroller type:
+ * 1. Window scroller: position:fixed (seamless, no jitter)
+ * 2. Custom scroller: translate3d (counters scroll movement)
+ *
+ * State machine: before → pinned → after
+ */
+export type PinState = 'before' | 'pinned' | 'after';
+export declare class PinManager {
+    private static _registry;
+    private static _users;
+    /**
+     * Get or create a shared PinManager for the given element.
+     * If another ScrollTrigger already pinned this element, returns that same
+     * PinManager so no additional spacer is created. Tracks `id` as a user.
+     */
+    static getOrCreate(id: number, element: HTMLElement): PinManager;
+    /**
+     * Release a ScrollTrigger's reference to a pinned element's PinManager.
+     * When the last user releases, cleanup() is called and registry entries removed.
+     */
+    static release(id: number, element: HTMLElement): void;
+    private _id;
+    private _element;
+    private _originalStyles;
+    private _spacer;
+    private _currentState;
+    private _pinStart;
+    private _pinEnd;
+    private _pinDistance;
+    private _useFixedPin;
+    private _pinSpacing;
+    private _elementHeight;
+    private _fixedTop;
+    private _fixedLeft;
+    private _width;
+    constructor(id: number);
+    /**
+     * Setup pinning for an element
+     *
+     * @param element - The element to pin
+     * @param pinStart - Scroll position where pin starts
+     * @param pinEnd - Scroll position where pin ends
+     * @param scrollerStartOffset - Viewport offset for fixed positioning
+     * @param useFixedPin - true for window scroller (position:fixed), false for custom (transform)
+     */
+    setup(element: HTMLElement, pinStart: number, pinEnd: number, scrollerStartOffset: number, useFixedPin: boolean, pinSpacing?: boolean | 'margin' | 'padding'): void;
+    /**
+     * Update pin state based on scroll position
+     */
+    update(scrollTop: number): void;
+    /**
+     * Clean up pin - restore original styles and remove spacer
+     */
+    cleanup(): void;
+    /**
+     * Get the pinned element
+     */
+    getElement(): HTMLElement | null;
+    /**
+     * Get the pin distance (scroll range over which element is pinned)
+     */
+    getPinDistance(): number;
+    /**
+     * Get current pin state
+     */
+    getState(): PinState;
+    /**
+     * Get a layout rect for trigger-position calculations.
+     *
+     * Used by ScrollTrigger._calculateTriggerPositions() and refresh() to obtain the
+     * correct document-relative position of the pinned element when it is position:fixed
+     * — querying the element itself in that state returns viewport-relative coordinates,
+     * which produce incorrect trigger positions.
+     *
+     * Returns a synthetic rect that combines:
+     *   - top/left/width from the spacer (document-flow position)
+     *   - height from _elementHeight (the element's natural content height)
+     *
+     * The spacer's own BCR height is NOT used because it includes padding-bottom
+     * (= pinDistance, added for pin spacing), which would inflate callers' end-position
+     * calculations and grow the pinDistance on every refresh cycle.
+     *
+     * Returns `null` when the spacer is not in the DOM (transform-pin strategy or
+     * before first setup), signalling the caller to fall back to the element's own rect.
+     */
+    getLayoutRect(): {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+        bottom: number;
+        right: number;
+    } | null;
+    /**
+     * Check if using fixed pin strategy
+     */
+    isFixedPin(): boolean;
+    /**
+     * Resolve pinSpacing config to a concrete value
+     */
+    private _resolvePinSpacing;
+    /**
+     * Fixed positioning for window scroller (seamless pinning)
+     *
+     * Wrapper pattern: the spacer wraps the element at all times (created in
+     * setup, removed in cleanup).  State changes only toggle styles on the
+     * element — no spacer insertion/removal between states.
+     *
+     * Layout math (wrapper):
+     *   Spacer content-height = elementHeight
+     *   Spacer padding-bottom = pinDistance (when pinSpacing enabled)
+     *   Spacer total box      = elementHeight + pinDistance
+     *
+     *   'before': element in flow inside spacer at top — no offset
+     *   'pinned': element position:fixed, spacer holds space
+     *   'after':  element back in flow at spacer top, translateY(pinDistance)
+     *             moves it visually to (originalPos + pinDistance) — seamless
+     *             transition with the next section
+     */
+    private _updateFixed;
+    /**
+     * Transform-based pinning for custom scroll containers
+     */
+    private _updateTransform;
+}

package/dist/triggers/ScrollTrigger.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ScrollTrigger
+ *
+ * Triggers timelines based on scroll position:
+ * - start/end parameters define trigger zone (GSAP-style)
+ * - scrub links animation progress to scroll position
+ * - scrub: number adds smooth lag (in seconds)
+ * - scroller: custom scroll container (default: window)
+ * - pin: fix element in place during animation
+ * - markers shows debug markers (optional)
+ *
+ * Pin implementation:
+ * - Window scroller: uses position:fixed (seamless, no jitter)
+ * - Custom scroller: uses transform (slight lag unavoidable)
+ *
+ * Start/End format: "<element_position> <scroller_position>"
+ * - Keywords: top, center, bottom
+ * - Units: 100px, 50%, 20vh
+ * - Relative: +=500px (for end only)
+ */
+import type { ScrollConfig } from '../types';
+import type { Timeline } from '../core/Timeline';
+import { BaseTrigger } from './BaseTrigger';
+export declare class ScrollTrigger extends BaseTrigger<ScrollConfig> {
+    private static _nextId;
+    private _id;
+    private static readonly _SCRUB_TICKER_PRIORITY;
+    private static _activeInstances;
+    private static _loadListenerAdded;
+    private _scrollListener?;
+    private _scrubTickListener;
+    private _currentProgress;
+    private _targetProgress;
+    private _scrubLag;
+    private _scroller;
+    private _triggerStart;
+    private _triggerEnd;
+    private _pinManager;
+    private _markerManager;
+    private _triggerState;
+    private _toggleActions;
+    private _initializing;
+    constructor(timeline: Timeline, config: ScrollConfig);
+    /**
+     * Register the global window.load listener (once).
+     * After all resources finish loading, refresh every active ScrollTrigger
+     * so trigger positions account for layout shifts caused by images/fonts.
+     */
+    private static _ensureLoadListener;
+    private _resolveScroller;
+    private _resolvePinElement;
+    /**
+     * Default start position — matches GSAP behavior:
+     * - With pin:    'top top'    (element top hits viewport top)
+     * - Without pin: 'top bottom' (element top hits viewport bottom)
+     */
+    private _defaultStart;
+    /**
+     * Default end position — matches GSAP behavior:
+     * 'bottom top' (element bottom hits viewport top)
+     */
+    private _defaultEnd;
+    private _getFirstAnimatedElement;
+    /**
+     * Resolve the trigger element from config or first animation
+     */
+    private _resolveTriggerElement;
+    /**
+     * Calculate trigger start/end scroll positions based on config.
+     *
+     * Pin distance equals the trigger range (triggerEnd - triggerStart).
+     * The PinManager spacer adds exactly that many pixels of scroll room to the
+     * page, so the animation always plays over the full configured distance while
+     * the element is pinned — no separate "extension" step is needed.
+     *
+     * When refresh() is called while the element is position:fixed (pinned), we
+     * use the spacer's rect instead of the element's rect.  A position:fixed
+     * element returns viewport-relative coordinates from getBoundingClientRect(),
+     * which would produce incorrect document-relative trigger positions.  The
+     * spacer sits in the element's original place in the document flow, so its
+     * rect always reflects the correct base for the calculation.
+     */
+    private _calculateTriggerPositions;
+    protected _onEnable(): void;
+    protected _onDisable(): void;
+    /**
+     * Refresh trigger positions (call after layout changes like resize)
+     */
+    refresh(): void;
+    private _getViewportHeight;
+    private _getScrollTop;
+    private _getScrollHeight;
+    private _onScroll;
+    /**
+     * Apply snap to a raw progress value based on config.snap.
+     * - number: snap to evenly-spaced increments (e.g. 0.25 → 0, 0.25, 0.5, 0.75, 1)
+     * - number[]: snap to nearest value in array
+     * - function: custom snap function
+     */
+    private _applySnap;
+    private _startSmoothScrollLoop;
+    private _stopSmoothScrollLoop;
+}

package/dist/triggers/TriggerManager.d.ts

@@ -0,0 +1,133 @@
+/**
+ * TriggerManager
+ *
+ * Coordinates all trigger types (pageLoad, pageExit, scroll, hover, click, mouseMove, gesture)
+ * and activates timelines based on trigger conditions.
+ *
+ * Uses a registry pattern for trigger classes to avoid importing them directly.
+ * Each trigger module registers itself via TriggerManager.registerTrigger() when loaded.
+ * This enables tree-shaking: only trigger types included in the bundle are available.
+ */
+import type { ScrollConfig, MouseMoveConfig, GestureConfig, HoverConfig, ClickConfig, CursorConfig, PageExitConfig } from '../types';
+import type { Timeline } from '../core/Timeline';
+/** Config for page load trigger */
+export interface PageLoadTriggerConfig {
+    timing?: 'before' | 'during' | 'after';
+}
+/** Interface that trigger instances must satisfy for cleanup */
+interface TriggerInstance {
+    enable(): void;
+    disable(): void;
+}
+/** Interface for PageLoadTrigger specifically */
+interface PageLoadTriggerInstance {
+    register(timeline: Timeline, config: PageLoadTriggerConfig): void;
+    unregister(timeline: Timeline): void;
+    clear(): void;
+    _reset(): void;
+}
+/** Trigger class constructors stored in registry */
+type TriggerFactory = new (...args: any[]) => TriggerInstance;
+export declare class TriggerManager {
+    private static _instance;
+    /** Registry for trigger class constructors - populated by each trigger module on load */
+    private static _triggerRegistry;
+    /** PageLoadTrigger factory - separate because it has a different interface */
+    private static _pageLoadTriggerFactory;
+    /** Debounce delay (ms) for the window resize → refreshScrollTriggers handler */
+    private static readonly _RESIZE_DEBOUNCE_MS;
+    private _pageLoadTrigger;
+    private _scrollTriggers;
+    private _eventTriggers;
+    private _mouseMoveTriggers;
+    private _gestureTriggers;
+    private _cursorTriggers;
+    private _pageExitTriggers;
+    /** Bound resize handler (created once, reused for add/removeEventListener) */
+    private _resizeHandler;
+    /** Timer id for debounced resize */
+    private _resizeTimer;
+    /** All trigger maps — used by unregister() and killAll() for bulk iteration */
+    private get _allTriggerMaps();
+    private constructor();
+    static getInstance(): TriggerManager;
+    /**
+     * Register a trigger class. Called by each trigger module when it loads.
+     * @internal
+     */
+    static registerTrigger(type: string, factory: TriggerFactory): void;
+    /**
+     * Register the PageLoadTrigger class. Called by PageLoadTrigger module when it loads.
+     * @internal
+     */
+    static registerPageLoadTrigger(factory: new () => PageLoadTriggerInstance): void;
+    /** Get or create the PageLoadTrigger instance */
+    private _getPageLoadTrigger;
+    /** Create a trigger instance from the registry */
+    private _createTrigger;
+    /**
+     * Register a pageLoad trigger
+     */
+    registerPageLoad(timeline: Timeline, config: PageLoadTriggerConfig): void;
+    /**
+     * Attach a debounced window resize listener that refreshes all scroll triggers.
+     * Called lazily when the first scroll trigger is registered.
+     * @internal
+     */
+    private _attachResizeListener;
+    /**
+     * Detach the window resize listener.
+     * Called when the last scroll trigger is removed or killAll() is invoked.
+     * @internal
+     */
+    private _detachResizeListener;
+    /**
+     * Register a scroll trigger
+     */
+    registerScroll(timeline: Timeline, config: ScrollConfig): void;
+    /**
+     * Register a hover trigger
+     */
+    registerHover(timeline: Timeline, config: HoverConfig): void;
+    /**
+     * Register a click trigger
+     */
+    registerClick(timeline: Timeline, config: ClickConfig): void;
+    /**
+     * Register a mouseMove trigger
+     */
+    registerMouseMove(timeline: Timeline, config: MouseMoveConfig): void;
+    /**
+     * Register a gesture trigger
+     */
+    registerGesture(timeline: Timeline, config: GestureConfig): void;
+    /**
+     * Register a cursor trigger
+     */
+    registerCursor(timeline: Timeline, config: CursorConfig): void;
+    /**
+     * Register a page exit trigger
+     */
+    registerPageExit(timeline: Timeline, config: PageExitConfig): void;
+    /**
+     * Unregister a timeline
+     */
+    unregister(timeline: Timeline): void;
+    /**
+     * Refresh all position-based triggers after layout changes (e.g. window resize).
+     * This includes scroll triggers, hover event triggers, gesture triggers, and
+     * mouseMove triggers — all of which cache element bounds at setup time.
+     */
+    refreshScrollTriggers(): void;
+    /**
+     * Kill all triggers
+     */
+    killAll(): void;
+    /**
+     * Reset for testing - DO NOT USE IN PRODUCTION
+     * Resets the singleton instance
+     * @internal
+     */
+    static _reset(): void;
+}
+export {};