@motion.page/sdk 0.1.0

package/README.md

@@ -0,0 +1,817 @@
+# @motion/sdk
+
+A high-performance CSS animation SDK with a declarative, config-based API. Zero runtime dependencies.
+
+![Version](https://img.shields.io/badge/version-0.1.0-blue) ![Bundle Size](https://img.shields.io/badge/bundle-TBD-green) ![License](https://img.shields.io/badge/license-Proprietary-red)
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concept](#core-concept)
+- [API Reference](#api-reference)
+  - [Motion()](#motion-function)
+  - [Motion Static Methods](#motion-static-methods)
+  - [Motion.utils](#motionutils)
+  - [Timeline](#timeline)
+  - [Triggers](#triggers)
+  - [Lifecycle Callbacks](#lifecycle-callbacks)
+- [AnimationConfig](#animationconfig)
+- [Easing](#easing)
+- [Types](#types)
+- [Browser Build](#browser-build)
+- [Browser Support](#browser-support)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+# Not published to npm — used internally within the Motion.page monorepo.
+# The package name is @motion/sdk
+```
+
+For direct browser use, see [Browser Build](#browser-build).
+
+---
+
+## Quick Start
+
+### Basic Animation
+
+```ts
+import { Motion } from '@motion/sdk';
+
+// Fade in and slide up
+Motion('hero-intro', '#hero', {
+  from: { opacity: 0, y: 50 },
+  to:   { opacity: 1, y: 0 },
+  duration: 0.8,
+  ease: 'power2.out',
+}).play();
+```
+
+### Scroll-Triggered Animation
+
+```ts
+// Scrub animation progress to scroll position
+Motion('scroll-reveal', '.card', {
+  from: { opacity: 0, y: 40 },
+  to:   { opacity: 1, y: 0 },
+  duration: 0.6,
+}).onScroll({ scrub: true, start: 'top 80%', end: 'top 30%' });
+```
+
+### Hover Effect
+
+```ts
+// Play on hover, reverse on leave
+Motion('btn-hover', '.btn', {
+  to: { scale: 1.05, backgroundColor: '#0099ff' },
+  duration: 0.3,
+  ease: 'power2.out',
+}).onHover({ onLeave: 'reverse' });
+```
+
+### Multi-Step Timeline with Stagger
+
+```ts
+// Sequence multiple targets; each entry has its own target and position
+Motion('intro-sequence', [
+  {
+    target: '.title',
+    from: { opacity: 0, y: -30 },
+    to:   { opacity: 1, y: 0 },
+    duration: 0.6,
+  },
+  {
+    target: '.cards',
+    from: { opacity: 0, y: 20 },
+    to:   { opacity: 1, y: 0 },
+    duration: 0.5,
+    stagger: { each: 0.1, from: 'start' },
+    position: '+=0.1',   // starts 0.1s after the previous entry ends
+  },
+  {
+    target: '.cta',
+    from: { opacity: 0, scale: 0.9 },
+    to:   { opacity: 1, scale: 1 },
+    duration: 0.4,
+    position: '<',        // starts at the same time as the previous entry
+  },
+]).onPageLoad();
+```
+
+### Replay an Existing Timeline
+
+```ts
+// Retrieve a previously created timeline by name and replay it
+Motion('hero-intro').restart();
+```
+
+---
+
+## Core Concept
+
+Every animation in the SDK is a **named timeline**. The name is the first argument to `Motion()` and acts as a registry key — calling `Motion('same-name')` always returns the same `Timeline` instance.
+
+Timelines are built declaratively via config objects; there are no `.to()` / `.from()` method calls. Animation state (targets, transforms, styles) is managed internally by the engine.
+
+---
+
+## API Reference
+
+### Motion Function
+
+Three overloads:
+
+```ts
+// 1. Retrieve an existing named timeline
+Motion(name: string): Timeline
+
+// 2. Create a single-animation timeline
+Motion(name: string, target: TargetInput, config: AnimationConfig): Timeline
+
+// 3. Create a multi-step timeline from an array of entries
+Motion(name: string, animations: AnimationEntry[]): Timeline
+```
+
+**`TargetInput`** accepts: CSS selector string, `string[]`, `Element`, `NodeList`, `Element[]`, or a plain object / array of plain objects (for object tweening).
+
+Calling `Motion()` with the same name on an already-existing timeline returns it unchanged (the retrieve overload). To rebuild a timeline, call `.kill()` on the old one first.
+
+---
+
+### Motion Static Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Motion.set` | `(target: TargetInput, vars: AnimationVars): void` | Immediately apply CSS / transform properties with no animation (like `gsap.set`). Values are written synchronously. |
+| `Motion.get` | `(name: string): Timeline \| undefined` | Get a timeline by name; returns `undefined` if none exists. |
+| `Motion.has` | `(name: string): boolean` | Check whether a named timeline is registered. |
+| `Motion.getNames` | `(): string[]` | Return the names of all registered timelines. |
+| `Motion.kill` | `(name: string): void` | Kill a single timeline by name. Restores initial CSS. |
+| `Motion.killAll` | `(): void` | Kill every timeline and animation managed by the engine. |
+| `Motion.reset` | `(targets: TargetInput): void` | Kill animations targeting those elements, revert text splits, clear transform cache and inline animation styles. |
+| `Motion.refreshScrollTriggers` | `(): void` | Recalculate all scroll trigger start/end positions (call after layout changes). |
+| `Motion.cleanup` | `(): void` | Remove ScrollTrigger spacer and marker DOM nodes from the document. |
+
+#### Examples
+
+```ts
+// Immediately hide an element before animating it in
+Motion.set('#hero', { opacity: 0, y: -20 });
+
+// Check and conditionally replay
+if (Motion.has('hero-intro')) {
+  Motion('hero-intro').restart();
+}
+
+// Tear down everything (e.g., on page navigation)
+Motion.killAll();
+Motion.cleanup();
+
+// Reset a specific element to its original state
+Motion.reset('.animated-card');
+```
+
+---
+
+### Motion.utils
+
+GSAP-compatible utility functions accessible via `Motion.utils`. These are drop-in replacements for `gsap.utils.*` helpers.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `toArray` | `(target, scope?) → Element[]` | Convert CSS selector, NodeList, HTMLCollection, or Element to a flat array. Drop-in for `gsap.utils.toArray()`. |
+| `clamp` | `(min, max, value?) → number \| fn` | Clamp a value between min and max. Curried if value omitted. |
+| `random` | `(min, max, snap?) → number` | Random number between min and max. Optional snap increment. |
+| `snap` | `(snapTo, value?) → number \| fn` | Snap to nearest increment or array value. Curried if value omitted. |
+| `interpolate` | `(start, end, progress) → number` | Linear interpolation (lerp) between two values. |
+| `mapRange` | `(inMin, inMax, outMin, outMax, value?) → number \| fn` | Map a value from one range to another. Curried if value omitted. |
+| `normalize` | `(min, max, value?) → number \| fn` | Normalize a value to 0–1 within a range. Curried if value omitted. |
+| `wrap` | `(min, max, value?) → number \| fn` | Wrap a value within a range (modular arithmetic). Curried if value omitted. |
+
+#### Examples
+
+```ts
+// Convert selector to array (replaces gsap.utils.toArray)
+const sections = Motion.utils.toArray('.section');
+console.log(sections.length); // number of matching elements
+
+// Clamp
+Motion.utils.clamp(0, 100, 150);     // 100
+const clamp01 = Motion.utils.clamp(0, 1);
+clamp01(1.5);                         // 1
+
+// Snap to increment
+Motion.utils.snap(5, 13);            // 15
+Motion.utils.snap([0, 25, 50], 30);  // 25
+
+// Random with snap
+Motion.utils.random(0, 100, 10);     // 0, 10, 20, ..., 100
+
+// Map between ranges
+Motion.utils.mapRange(0, 100, 0, 1, 50);  // 0.5
+
+// Normalize to 0–1
+Motion.utils.normalize(0, 255, 128);  // ~0.502
+
+// Wrap (modular)
+Motion.utils.wrap(0, 360, 450);       // 90
+
+// Interpolate (lerp)
+Motion.utils.interpolate(0, 100, 0.5); // 50
+```
+
+#### Migration from GSAP
+
+| GSAP | Motion SDK |
+|------|------------|
+| `gsap.utils.toArray('.el')` | `Motion.utils.toArray('.el')` |
+| `gsap.utils.clamp(0, 1, v)` | `Motion.utils.clamp(0, 1, v)` |
+| `gsap.utils.random(0, 100)` | `Motion.utils.random(0, 100)` |
+| `gsap.utils.snap(5, v)` | `Motion.utils.snap(5, v)` |
+| `gsap.utils.mapRange(0, 1, 0, 100, v)` | `Motion.utils.mapRange(0, 1, 0, 100, v)` |
+| `gsap.utils.normalize(0, 100, v)` | `Motion.utils.normalize(0, 100, v)` |
+| `gsap.utils.wrap(0, 360, v)` | `Motion.utils.wrap(0, 360, v)` |
+| `gsap.utils.interpolate(0, 100, 0.5)` | `Motion.utils.interpolate(0, 100, 0.5)` |
+
+---
+
+### Timeline
+
+`Timeline` is the object returned by every `Motion()` call. All playback and trigger methods return `this` for chaining.
+
+#### Playback Control
+
+```ts
+tl.play(from?: number): this      // Play forward; optional start time in seconds
+tl.pause(atTime?: number): this   // Pause; optional snap-to time
+tl.reverse(from?: number): this   // Play backward; optional start time
+tl.restart(): this                // Seek to t=0, restore initial CSS, then play forward
+tl.seek(position: number): this   // Jump to a time (seconds) without playing
+```
+
+#### State — Getter / Setter
+
+Calling with no argument reads the value; calling with an argument sets it and returns `this`.
+
+```ts
+tl.duration(): number                      // Read total duration in seconds
+tl.progress(value?: number): number | this // Get or set normalized progress (0–1)
+tl.time(value?: number): number | this     // Get or set current time in seconds
+tl.timeScale(value?: number): number | this // Get or set playback speed multiplier
+tl.isActive(): boolean                     // Is the timeline currently animating?
+tl.getName(): string | undefined           // Registered name, or undefined for anonymous
+```
+
+```ts
+// Read
+const p = tl.progress();   // e.g. 0.5
+
+// Write (chainable)
+tl.progress(0.5).play();
+tl.timeScale(2).restart();  // play at 2× speed
+```
+
+#### Inserting Callbacks at a Position
+
+```ts
+tl.call(
+  callback: (...args: unknown[]) => void,
+  params?: unknown[],
+  position?: string | number,
+): this
+```
+
+**Position syntax** (same rules apply to `AnimationEntry.position`):
+
+| Value | Meaning |
+|-------|---------|
+| `0.5` | 0.5 s from start (absolute) |
+| `"+=0.5"` | 0.5 s after the previous entry ends |
+| `"-=0.3"` | 0.3 s before the previous entry ends |
+| `"<"` | At the same start time as the previous entry |
+| `">"` | Immediately after the previous entry ends |
+
+```ts
+Motion('demo', '.box', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 1 })
+  .call(() => console.log('halfway'), [], 0.5)
+  .call(() => console.log('done'), [], '>');
+```
+
+#### Cleanup
+
+```ts
+tl.kill(clearProps?: boolean): void
+// Destroy the timeline. clearProps=true (default) restores initial CSS on all targets.
+
+tl.clear(): this
+// Reset and rebuild the timeline without destroying it.
+```
+
+---
+
+### Triggers
+
+All trigger methods are chainable and attach behaviour to the timeline without requiring you to manage event listeners manually.
+
+#### `.onHover(config?)`
+
+Play on `mouseenter`, react on `mouseleave`.
+
+```ts
+interface HoverConfig {
+  target?: string | Element;              // Defaults to animation target(s)
+  each?: boolean;                         // Apply trigger to each matched element individually
+  onLeave?: 'reverse' | 'pause' | 'stop' | 'restart' | 'none';
+  leaveDelay?: number;                    // Seconds to wait before triggering onLeave
+}
+```
+
+```ts
+Motion('card-hover', '.card', {
+  to: { y: -8, boxShadow: '0 12px 24px rgba(0,0,0,0.15)' },
+  duration: 0.3,
+  ease: 'power2.out',
+}).onHover({ each: true, onLeave: 'reverse' });
+```
+
+#### `.onClick(config?)`
+
+Toggle animation on click.
+
+```ts
+interface ClickConfig {
+  target?: string | Element;
+  each?: boolean;
+  secondTarget?: string | Element;        // Alternative click target
+  toggle?: 'reverse' | 'restart' | 'play';
+  preventDefault?: boolean;
+}
+```
+
+```ts
+Motion('menu-toggle', '#menu', {
+  from: { height: 0, opacity: 0 },
+  to:   { height: 'auto', opacity: 1 },
+  duration: 0.4,
+  ease: 'power2.inOut',
+}).onClick({ target: '#menu-btn', toggle: 'reverse' });
+```
+
+#### `.onScroll(config?)`
+
+Scrub or snap animation to scroll position.
+
+```ts
+interface ScrollConfig {
+  target?: string | Element;
+  start?: string;                         // e.g. 'top 80%'
+  end?: string;                           // e.g. 'bottom 20%'
+  scrub?: boolean | number;               // true = instant, number = smoothing seconds
+  snap?: number | number[] | ((progress: number) => number);  // Snap scroll progress
+  markers?: boolean | MarkerConfig;       // Debug markers
+  scroller?: string | Element;            // Custom scroll container
+  pin?: boolean | string;                 // Pin the element during scroll
+  pinSpacing?: boolean | 'margin' | 'padding';
+  each?: boolean;
+  toggleActions?: string;                 // e.g. 'play none none reverse'
+}
+```
+
+**`snap`** controls how scroll progress snaps to discrete values:
+
+- **Number** — fractional increment to snap to. E.g. `snap: 0.25` snaps to 0, 0.25, 0.5, 0.75, 1.
+- **Array** — explicit progress values to snap to. E.g. `snap: [0, 0.33, 0.66, 1]`.
+- **Function** — custom snap logic. Receives raw progress (0–1), returns snapped value.
+
+Common pattern for horizontal scroll with equal sections:
+
+```ts
+const sections = Motion.utils.toArray('.section');
+Motion('h-scroll', '.panel', {
+  to: { x: `-${(sections.length - 1) * 100}%` },
+  duration: 1,
+}).onScroll({
+  scrub: true,
+  snap: 1 / (sections.length - 1),
+  pin: true,
+  start: 'top top',
+  end: `+=${sections.length * 100}%`,
+});
+```
+
+```ts
+Motion('parallax', '.hero-bg', {
+  from: { y: 0 },
+  to:   { y: -100 },
+}).onScroll({ scrub: 1, start: 'top top', end: 'bottom top' });
+```
+
+#### `.onMouseMove(config?)`
+
+Drive animation progress from mouse position.
+
+```ts
+interface MouseMoveConfig {
+  type?: 'distance' | 'axis';
+  target?: string | Element;              // Element whose bounds define the movement area
+  each?: boolean;
+  smooth?: number;                        // Smoothing factor (higher = slower follow)
+  startProgress?: number;                 // Progress value at rest (0–1)
+  leaveProgress?: number;                 // Progress to animate to on mouse leave
+}
+```
+
+```ts
+Motion('parallax-depth', '.layer', {
+  from: { x: -20, y: -20 },
+  to:   { x: 20, y: 20 },
+  axis: 'x',  // bind to horizontal axis only
+}).onMouseMove({ type: 'axis', smooth: 0.1 });
+```
+
+#### `.onPageLoad()`
+
+Play the animation automatically when the page finishes loading.
+
+```ts
+Motion('page-intro', [
+  { target: '.logo',  from: { opacity: 0 }, to: { opacity: 1 }, duration: 0.5 },
+  { target: '.nav',   from: { y: -20, opacity: 0 }, to: { y: 0, opacity: 1 }, duration: 0.4 },
+]).onPageLoad();
+```
+
+#### `.onGesture(config)`
+
+Respond to pointer, touch, wheel, or scroll gestures with fine-grained event-to-action mapping.
+
+```ts
+type GestureInputType = 'pointer' | 'touch' | 'wheel' | 'scroll';
+
+type GestureEvent =
+  | 'Up' | 'Down' | 'Left' | 'Right'
+  | 'UpComplete' | 'DownComplete' | 'LeftComplete' | 'RightComplete'
+  | 'Change' | 'ChangeX' | 'ChangeY'
+  | 'ToggleX' | 'ToggleY'
+  | 'Press' | 'Release' | 'PressInit'
+  | 'Drag' | 'DragEnd'
+  | 'Stop' | 'Hover' | 'HoverEnd';
+
+type GestureAction =
+  | 'play' | 'pause' | 'reverse' | 'restart' | 'toggle' | 'reset' | 'complete' | 'kill'
+  | 'playReverse' | 'progressUp' | 'progressDown' | 'playNext' | 'playPrevious';
+
+interface GestureConfig {
+  target?: string | Element;
+  types: GestureInputType[];
+  events: Partial<Record<GestureEvent, GestureAction>>;
+  tolerance?: number;
+  dragMinimum?: number;
+  wheelSpeed?: number;
+  scrollSpeed?: number;
+  preventDefault?: boolean;
+  lockAxis?: boolean;
+  each?: boolean;
+  stopDelay?: number;
+  animationStep?: number | Partial<Record<GestureEvent, number>>;
+  smooth?: number;
+}
+```
+
+```ts
+Motion('swipe-gallery', '.gallery', {
+  from: { x: 0 },
+  to:   { x: -100 },
+}).onGesture({
+  types: ['pointer', 'touch'],
+  events: {
+    Left:  'playNext',
+    Right: 'playPrevious',
+  },
+  dragMinimum: 40,
+  lockAxis: true,
+});
+```
+
+#### `.onCursor(config)`
+
+Replace the native cursor with a fully animated custom cursor.
+
+```ts
+interface CursorConfig {
+  target?: string | Element;
+  type?: 'basic' | 'text' | 'media';
+  smooth?: number;
+  squeeze?: boolean | { min?: number; max?: number; multiplier?: number };
+  hideNative?: boolean;
+  default: CursorStateVars;             // Required: default cursor appearance
+  hover?: CursorStateVars;              // State when hovering interactive elements
+  click?: CursorStateVars;             // State while pressing
+  text?: Record<string, string | number>;
+  media?: Record<string, string | number>;
+}
+```
+
+```ts
+Motion('custom-cursor', 'body', {
+  to: { opacity: 1 },
+  duration: 0,
+}).onCursor({
+  target: '#cursor-dot',
+  smooth: 0.08,
+  hideNative: true,
+  default: { width: 12, height: 12, borderRadius: '50%', backgroundColor: '#fff' },
+  hover:   { width: 40, height: 40, backgroundColor: 'transparent', borderColor: '#fff' },
+  click:   { scale: 0.8 },
+});
+```
+
+---
+
+### Lifecycle Callbacks
+
+Attach callbacks via the `AnimationConfig` object or directly on the `Timeline` instance. Both approaches are chainable.
+
+#### Via `AnimationConfig`
+
+```ts
+Motion('slide-in', '.card', {
+  from: { opacity: 0, x: -40 },
+  to:   { opacity: 1, x: 0 },
+  duration: 0.6,
+  onStart:           () => console.log('started'),
+  onUpdate:          (progress) => console.log('progress:', progress),
+  onComplete:        () => console.log('done'),
+  onRepeat:          (count) => console.log('repeat #', count),
+  onReverseComplete: () => console.log('reversed'),
+  repeat: { times: 2, yoyo: true, delay: 0.5 },
+});
+```
+
+#### Via `Timeline` Methods
+
+```ts
+Motion('slide-in', '.card', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 0.6 })
+  .onStart(() => console.log('started'))
+  .onUpdate((progress, time) => console.log(progress, time))
+  .onComplete(() => console.log('done'));
+```
+
+| Callback | Timeline method | AnimationConfig field | Arguments |
+|----------|-----------------|-----------------------|-----------|
+| Start | `.onStart(cb)` | `onStart` | none |
+| Update | `.onUpdate(cb)` | `onUpdate` | `(progress: number, time: number)` via method; `(progress: number)` via config |
+| Complete | `.onComplete(cb)` | `onComplete` | none |
+| Repeat | — | `onRepeat` | `(repeatCount: number)` |
+| Reverse complete | — | `onReverseComplete` | none |
+
+---
+
+## AnimationConfig
+
+Full shape of the config object used for both single-animation (`Motion(name, target, config)`) and each entry in a multi-step timeline (`AnimationEntry`).
+
+```ts
+interface AnimationConfig {
+  from?:     AnimationVars;          // Initial values (animated FROM these)
+  to?:       AnimationVars;          // Target values (animated TO these)
+  duration?: number;                 // Seconds (default: engine default)
+  delay?:    number;                 // Seconds before animation begins
+  ease?:     string;                 // Easing name string, see Easing section
+  stagger?:  number | StaggerVars;  // Per-element stagger delay
+  repeat?:   RepeatConfig;           // Loop/yoyo configuration
+  split?:    SplitType;             // Text splitting for per-char/word/line animation
+  axis?:     'x' | 'y';            // Axis binding for onMouseMove animations
+
+  // Lifecycle
+  onStart?:           () => void;
+  onUpdate?:          (progress: number) => void;
+  onComplete?:        () => void;
+  onRepeat?:          (repeatCount: number) => void;
+  onReverseComplete?: () => void;
+}
+```
+
+### AnimationVars
+
+All animatable properties:
+
+```ts
+// Transforms
+x, y, z                                    // number | string (px default)
+rotate, rotateX, rotateY, rotateZ          // number | string (deg default)
+scale, scaleX, scaleY, scaleZ              // number
+skewX, skewY                               // number | string
+perspective                                // number | string
+
+// Visual
+opacity                                    // number (0–1)
+backgroundColor, color                     // string (CSS color)
+filter                                     // string (CSS filter)
+transformOrigin                            // string
+
+// Layout
+width, height                              // number | string
+top, left, right, bottom                   // number | string
+margin, marginTop, marginRight, marginBottom, marginLeft
+padding, paddingTop, paddingRight, paddingBottom, paddingLeft
+
+// Typography
+fontSize, lineHeight, letterSpacing        // number | string
+borderRadius                               // number | string
+zIndex                                     // number
+backgroundPosition                         // string
+
+// Border / outline colors
+borderColor, borderTopColor, borderRightColor, borderBottomColor, borderLeftColor
+outlineColor, textDecorationColor, caretColor
+
+// SVG
+fill, stroke                               // string (CSS color)
+drawSVG                                    // string | { start?: number; end?: number }
+
+// Motion path
+path: {
+  target:   string | Element;             // SVG <path> selector or element
+  align?:   string | Element;             // Align bounding box to this element
+  alignAt?: [number, number];             // Origin point [x%, y%], default [50, 50]
+  start?:   number;                       // Path start (0–1), default 0
+  end?:     number;                       // Path end (0–1), default 1
+  rotate?:  boolean;                      // Auto-rotate along tangent
+}
+```
+
+### StaggerVars
+
+```ts
+interface StaggerVars {
+  each?:   number;                         // Seconds between each element
+  amount?: number;                         // Total stagger spread (alternative to each)
+  from?:   'start' | 'center' | 'edges' | 'random' | 'end' | number;
+  grid?:   'auto' | [number, number];     // 2D grid stagger
+  axis?:   'x' | 'y';                    // Grid stagger axis
+  ease?:   string;                         // Easing applied to the stagger distribution
+}
+```
+
+### RepeatConfig
+
+```ts
+interface RepeatConfig {
+  times: number;      // Number of additional repetitions (-1 = infinite)
+  delay?: number;     // Seconds between repetitions
+  yoyo?: boolean;     // Alternate direction each cycle
+}
+```
+
+### SplitType
+
+```ts
+type SplitType =
+  | 'chars'
+  | 'words'
+  | 'lines'
+  | 'chars,words'
+  | 'words,lines'
+  | 'chars,words,lines';
+```
+
+Text is split into wrapper `<span>` elements before animating. `Motion.reset()` reverts the DOM.
+
+```ts
+Motion('text-reveal', '.headline', {
+  from:     { opacity: 0, y: 20 },
+  to:       { opacity: 1, y: 0 },
+  duration: 0.5,
+  split:    'chars',
+  stagger:  { each: 0.03, from: 'start' },
+}).onPageLoad();
+```
+
+---
+
+## Easing
+
+Easing names are **case-insensitive** strings. Pass them to `AnimationConfig.ease` or `StaggerVars.ease`.
+
+| Family | Variants |
+|--------|----------|
+| `linear`, `none` | — |
+| `power1` | `power1.in` · `power1.out` · `power1.inout` |
+| `power2` | `power2.in` · `power2.out` · `power2.inout` |
+| `power3` | `power3.in` · `power3.out` · `power3.inout` |
+| `power4` | `power4.in` · `power4.out` · `power4.inout` |
+| `sine` | `sine.in` · `sine.out` · `sine.inout` |
+| `expo` | `expo.in` · `expo.out` · `expo.inout` |
+| `circ` | `circ.in` · `circ.out` · `circ.inout` |
+| `back` | `back.in` · `back.out` · `back.inout` |
+| `elastic` | `elastic.in` · `elastic.out` · `elastic.inout` |
+| `bounce` | `bounce.in` · `bounce.out` · `bounce.inout` |
+
+Unknown strings fall back to `power1.out`.
+
+```ts
+Motion('spring-in', '.box', {
+  from: { scale: 0 },
+  to:   { scale: 1 },
+  duration: 0.8,
+  ease: 'elastic.out',
+}).play();
+```
+
+---
+
+## Types
+
+All types are re-exported from the package entry point.
+
+```ts
+import type {
+  // Core
+  AnimationVars,
+  AnimationConfig,
+  AnimationEntry,
+  TargetInput,
+  ObjectTarget,
+  AnimationTarget,
+  EasingFunction,
+
+  // Animation options
+  StaggerVars,
+  RepeatConfig,
+  SplitType,
+  PathConfig,
+
+  // Triggers
+  HoverConfig,
+  ClickConfig,
+  ScrollConfig,
+  MouseMoveConfig,
+  MarkerConfig,
+
+  // Gesture
+  GestureConfig,
+  GestureEvent,
+  GestureAction,
+  GestureInputType,
+
+  // Cursor
+  CursorConfig,
+  CursorStateVars,
+  CursorSqueezeConfig,
+} from '@motion/sdk';
+
+// Namespace import
+import { Types } from '@motion/sdk';
+```
+
+---
+
+## Browser Build
+
+A pre-built IIFE bundle is generated at `dist/motion-sdk.browser.js` for direct `<script>` tag usage:
+
+```html
+<script src="motion-sdk.browser.js"></script>
+<script>
+  // Globals are exposed on window:
+  const { Motion, MotionTimeline } = window;
+
+  Motion('fade-in', '.hero', {
+    from: { opacity: 0 },
+    to:   { opacity: 1 },
+    duration: 1,
+  }).onPageLoad();
+</script>
+```
+
+To regenerate the browser bundle:
+
+```bash
+bun run packages/sdk/scripts/build-iife.ts
+```
+
+---
+
+## Browser Support
+
+Modern evergreen browsers:
+
+| Browser | Minimum |
+|---------|---------|
+| Chrome | 90+ |
+| Firefox | 90+ |
+| Safari | 15+ |
+| Edge | 90+ |
+
+---
+
+## License
+
+Proprietary — see [LICENSE](../../LICENSE) for details.