# @motion.page/sdk

> Zero-dependency animation SDK with named timelines, 8 trigger types, text splitting, FLIP morphing, custom cursors, and SVG drawing. Browser-only (requires document/window).

For complete SDK documentation, install the motion-page skill: `npx skills add motion-page/claude-plugin`

## Getting Started

- **Installation**: npm install @motion.page/sdk; ESM, CJS, and browser IIFE builds
- **Quick Start**: Basic fade-in, scroll-triggered, and multi-step timeline examples
- **Core Concept**: Named timelines — Motion(name) retrieves or creates; same name = same instance
- **Implicit Values**: from-only resolves current CSS as to; to-only resolves current CSS as from; natural defaults (opacity:1, x:0, y:0, scale:1) are auto-filled

## Core API

- **Motion()**: Factory with 3 overloads — retrieve timeline, single animation, multi-step array
- **Motion.set()**: Instant property setting (zero duration)
- **Motion.kill() / killAll()**: Destroy named timelines; killAll for SPA cleanup
- **Motion.reset()**: Kill tweens on targets and revert text splits
- **Motion.refreshScrollTriggers()**: Recalculate scroll positions after DOM changes
- **Motion.cleanup()**: Remove ScrollTrigger spacer/marker DOM nodes
- **Motion.utils**: toArray, clamp, random, snap, interpolate, mapRange, normalize, wrap — all support currying

## Timeline

- **Playback Control**: play, pause, reverse, restart, seek
- **State**: progress, time, timeScale, duration, isActive — getter/setter pattern
- **Lifecycle Callbacks**: onStart, onUpdate(progress, time), onComplete
- **Sequencing**: tl.call(fn, params, position) — fire functions at timeline positions

## Triggers

- **.onPageLoad()**: Auto-play when DOM ready
- **.onScroll(config)**: start, end, scrub, pin, pinSpacing, markers, toggleActions, snap, scroller
- **.onHover(config)**: target, each, onLeave (reverse/pause/stop/restart/none), leaveDelay
- **.onClick(config)**: target, each, toggle (reverse/restart/play), secondTarget, preventDefault
- **.onMouseMove(config)**: type (distance/axis), smooth, startProgress, leaveProgress
- **.onGesture(config)**: types (pointer/touch/wheel/scroll), events map, tolerance, dragMinimum, lockAxis
- **.onCursor(config)**: type (basic/text/media), smooth, squeeze, hideNative, default/hover/click states
- **.onPageExit(config)**: mode (all/include/exclude), selectors, skipHref

## Animation Config

- **AnimationConfig**: from, to, duration, delay, ease, stagger, repeat, split, mask, maskPadding, fit, axis, callbacks
- **AnimationVars**: Transforms, opacity, colors, CSS properties, filter, clip-path, drawSVG, path, custom properties
- **Easing**: power1-4, sine, expo, circ, back, elastic, bounce — .in/.out/.inOut
- **Stagger**: each, amount, from (start/center/edges/random/end/index), grid, axis, ease
- **Position Parameter**: Absolute (number), relative (+=/-=), anchored (<, >, <0.2, >-0.1)

## Features

- **Text Splitting**: split: chars/words/lines; mask: true for clip reveals; maskPadding: number|string|{inline,block} to prevent cursive/display glyph clipping; data-split-* attributes
- **FLIP Morphing**: fit: { target, scale, resize, absolute } — animate between element states
- **DrawSVG**: String format ("0% 100%") or object ({ start, end } as 0-100 percentages)
- **Clip Path**: Animate clip-path/clipPath between matching shapes (circle, ellipse, inset, polygon, rect, xywh); same shape on both ends; polygon vertex counts must match; cross-shape hard-swaps at progress >= 0.5; renderer also writes -webkit-clip-path
- **Motion Path**: path: { target, align, start, end, rotate }
- **Custom Cursors**: type: basic/text/media; mp-cursor-text and mp-cursor-media HTML attributes

## Optional

- **Types Reference**: All exported TypeScript types and interfaces
- **Browser Build**: IIFE bundle exposing window.Motion and window.MotionTimeline
- **SPA Cleanup**: Motion.killAll() + Motion.cleanup() on route change
- **Migration from GSAP**: gsap.to → Motion(name, target, {to}).play(); ScrollTrigger → .onScroll()
- **Migration from Framer Motion**: motion.div → Motion(name, selector, config); whileHover → .onHover()