@motion.page/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,10 @@
-# @motion/sdk
+# @motion.page/sdk
 
-A high-performance CSS animation SDK with a declarative, config-based API. Zero runtime dependencies.
+A high-performance animation SDK with a declarative API. Scroll-triggered animations, page transitions, custom cursors, gesture controls, text splitting, and more — 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)
+[![npm version](https://img.shields.io/npm/v/@motion.page/sdk)](https://www.npmjs.com/package/@motion.page/sdk)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@motion.page/sdk)](https://bundlephobia.com/package/@motion.page/sdk)
+[![License](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue)](./LICENSE)
 
 ---
 
@@ -11,6 +13,7 @@ A high-performance CSS animation SDK with a declarative, config-based API. Zero
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Core Concept](#core-concept)
+- [Implicit Values](#implicit-values)
 - [API Reference](#api-reference)
   - [Motion()](#motion-function)
   - [Motion Static Methods](#motion-static-methods)
@@ -30,11 +33,20 @@ A high-performance CSS animation SDK with a declarative, config-based API. Zero
 ## Installation
 
 ```bash
-# Not published to npm — used internally within the Motion.page monorepo.
-# The package name is @motion/sdk
+npm install @motion.page/sdk
+# or
+bun add @motion.page/sdk
+# or
+yarn add @motion.page/sdk
+# or
+pnpm add @motion.page/sdk
 ```
 
-For direct browser use, see [Browser Build](#browser-build).
+📖 Full documentation and interactive examples: [motion.page](https://motion.page)
+
+> **⚠️ Browser-only:** This SDK requires a browser environment (`document`, `window`). In SSR frameworks (Next.js, Nuxt, Astro), wrap SDK calls in `useEffect`, `onMounted`, or client-side scripts.
+
+For direct browser use without a bundler, see [Browser Build](#browser-build).
 
 ---
 
@@ -43,12 +55,11 @@ For direct browser use, see [Browser Build](#browser-build).
 ### Basic Animation
 
 ```ts
-import { Motion } from '@motion/sdk';
+import { Motion } from '@motion.page/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();
@@ -60,7 +71,6 @@ Motion('hero-intro', '#hero', {
 // 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%' });
 ```
@@ -84,13 +94,11 @@ 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
@@ -98,7 +106,6 @@ Motion('intro-sequence', [
   {
     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
   },
@@ -112,6 +119,22 @@ Motion('intro-sequence', [
 Motion('hero-intro').restart();
 ```
 
+### Object Animation
+
+Plain JavaScript objects can be tweened — useful for canvas, audio, WebGL, or any non-DOM state:
+
+```ts
+// Animate plain JS objects (useful for canvas, audio, WebGL)
+const state = { volume: 0, brightness: 100 };
+Motion('audio-fade', state, {
+  to: { volume: 1, brightness: 50 },
+  duration: 2,
+  onUpdate: () => {
+    audioNode.gain.value = state.volume;
+  },
+}).play();
+```
+
 ---
 
 ## Core Concept
@@ -120,6 +143,90 @@ Every animation in the SDK is a **named timeline**. The name is the first argume
 
 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.
 
+If `Motion('name', target, config)` is called when `'name'` already has a timeline, the new entries are **appended** to the existing timeline rather than replacing it. To rebuild from scratch, call `.kill()` first:
+
+```ts
+Motion('hero').kill();
+Motion('hero', '#hero', { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();
+```
+
+---
+
+## Implicit Values
+
+The SDK automatically resolves a missing `from` or `to` by reading the element's **current computed CSS** at build time (i.e. when `Motion()` is first called). This means you rarely need to specify both ends of an animation.
+
+### Three cases
+
+| Config | SDK behaviour |
+|--------|--------------|
+| `from` only | Reads current CSS as the `to` target. Animate **from** custom values **into** the element's natural state. |
+| `to` only | Reads current CSS as the `from` starting point. Animate **from** the natural state **to** custom values. |
+| Both | Both endpoints are explicit. Only needed when **neither** endpoint matches the element's natural CSS. |
+
+### Common pattern — reveal animations only need `from`
+
+```ts
+// ❌ Redundant — opacity:1 and y:0 are the element's natural CSS defaults
+Motion('reveal', '.card', {
+  from: { opacity: 0, y: 40 },
+  to:   { opacity: 1, y: 0 },
+  duration: 0.6,
+}).onScroll({ scrub: true });
+
+// ✅ Correct — SDK reads opacity:1 and y:0 from computed CSS automatically
+Motion('reveal', '.card', {
+  from: { opacity: 0, y: 40 },
+  duration: 0.6,
+}).onScroll({ scrub: true });
+```
+
+### When `to` only is correct
+
+```ts
+// Animate FROM the element's current state TO a hover state
+Motion('btn-hover', '.btn', {
+  to: { scale: 1.05, backgroundColor: '#0099ff' },
+  duration: 0.3,
+}).onHover({ onLeave: 'reverse' });
+```
+
+### When you need both
+
+```ts
+// Neither endpoint is the element's natural state
+Motion('parallax', '.layer', {
+  from: { x: -20, y: -20 },
+  to:   { x: 20, y: 20 },
+}).onMouseMove({ type: 'axis' });
+
+// Animating between two non-default positions
+Motion('swipe', '.panel', {
+  from: { x: -100 },
+  to:   { x: 100 },
+}).onGesture({ types: ['touch'], events: { Left: 'play', Right: 'reverse' } });
+```
+
+### Natural CSS defaults (common values the SDK resolves automatically)
+
+| Property | Natural default |
+|----------|----------------|
+| `opacity` | `1` |
+| `x`, `y`, `z` | `0` |
+| `scale`, `scaleX`, `scaleY` | `1` |
+| `rotate`, `rotateX`, `rotateY` | `0` |
+| `skewX`, `skewY` | `0` |
+
+> **Note:** `height: 'auto'` is **not** a natural default for the animation engine — it must be specified explicitly in `to` when needed (e.g. accordion reveals).
+
+### Build-time vs. play-time
+
+The SDK reads computed CSS **at build time** (when `Motion()` is called), not at play time. If the element's styles change after the timeline is created, call `.kill()` and rebuild the timeline.
+
+### Edge case — transform cache
+
+Transform properties (`x`, `y`, `scale`, `rotate`, etc.) are read from the SDK's **internal transform cache** rather than `getComputedStyle`. This ensures composited transforms remain consistent across animations. Plain CSS properties (`opacity`, `color`, `width`, etc.) are read directly from `getComputedStyle`.
+
 ---
 
 ## API Reference
@@ -149,7 +256,7 @@ Calling `Motion()` with the same name on an already-existing timeline returns it
 
 | 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.set` | `(target: TargetInput, vars: AnimationVars): void` | Immediately apply CSS / transform properties with no animation. Goes through the full animation engine pipeline (including color parsing and transform compositing) but completes in zero time, so applied values persist on the DOM. |
 | `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. |
@@ -184,6 +291,13 @@ Motion.reset('.animated-card');
 
 GSAP-compatible utility functions accessible via `Motion.utils`. These are drop-in replacements for `gsap.utils.*` helpers.
 
+`MotionUtils` is also exported directly from the package and can be imported independently:
+
+```ts
+import { MotionUtils } from '@motion.page/sdk';
+// Same object as Motion.utils
+```
+
 | Method | Signature | Description |
 |--------|-----------|-------------|
 | `toArray` | `(target, scope?) → Element[]` | Convert CSS selector, NodeList, HTMLCollection, or Element to a flat array. Drop-in for `gsap.utils.toArray()`. |
@@ -297,9 +411,11 @@ tl.call(
 | `"-=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 |
+| `"<0.2"` | 0.2 s after the start of the previous entry |
+| `">-0.1"` | 0.1 s before the end of the previous entry |
 
 ```ts
-Motion('demo', '.box', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 1 })
+Motion('demo', '.box', { from: { opacity: 0 }, duration: 1 })
   .call(() => console.log('halfway'), [], 0.5)
   .call(() => console.log('done'), [], '>');
 ```
@@ -320,6 +436,22 @@ tl.clear(): this
 
 All trigger methods are chainable and attach behaviour to the timeline without requiring you to manage event listeners manually.
 
+#### Per-Element Triggers (`each: true`)
+
+When targeting multiple elements, `each: true` creates independent per-element timeline instances. Without it, all matched elements share one timeline and play/reverse together.
+
+```ts
+// WITHOUT each — hovering any card plays ALL cards
+Motion('card-hover', '.card', { to: { y: -8 }, duration: 0.3 })
+  .onHover({ onLeave: 'reverse' });
+
+// WITH each — each card animates independently
+Motion('card-hover', '.card', { to: { y: -8 }, duration: 0.3 })
+  .onHover({ each: true, onLeave: 'reverse' });
+```
+
+`each` is supported by `.onHover()`, `.onClick()`, `.onScroll()`, `.onMouseMove()`, and `.onGesture()`.
+
 #### `.onHover(config?)`
 
 Play on `mouseenter`, react on `mouseleave`.
@@ -358,7 +490,7 @@ interface ClickConfig {
 ```ts
 Motion('menu-toggle', '#menu', {
   from: { height: 0, opacity: 0 },
-  to:   { height: 'auto', opacity: 1 },
+  to:   { height: 'auto' },  // height: 'auto' must be explicit
   duration: 0.4,
   ease: 'power2.inOut',
 }).onClick({ target: '#menu-btn', toggle: 'reverse' });
@@ -375,12 +507,55 @@ interface ScrollConfig {
   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
+  markers?: boolean | MarkerConfig;       // Debug markers (pass object for styling)
   scroller?: string | Element;            // Custom scroll container
-  pin?: boolean | string;                 // Pin the element during scroll
+  pin?: boolean | string;                 // true = pin animation target; string = pin a different element
   pinSpacing?: boolean | 'margin' | 'padding';
   each?: boolean;
-  toggleActions?: string;                 // e.g. 'play none none reverse'
+  toggleActions?: string;                 // Format: 'onEnter onLeave onEnterBack onLeaveBack'
+}
+```
+
+**`start` / `end` defaults:**
+- Without `pin`: `start: 'top bottom'`, `end: 'bottom top'`
+- With `pin`: `start: 'top top'`, `end: 'bottom top'`
+
+**Relative `end` with `+=`:** When `end` starts with `+=`, the value is a distance measured from the `start` position:
+
+```ts
+.onScroll({ start: 'top center', end: '+=800' })    // 800px of scroll travel
+.onScroll({ start: 'top top', end: '+=100vh' })     // one viewport height of scroll
+```
+
+**`pin: string`** pins a different element (e.g. a parent wrapper) while the animated child scrolls:
+
+```ts
+// Pin the parent section while the child content animates
+Motion('content-reveal', '.content', {
+  from: { opacity: 0, y: 40 },
+  duration: 1,
+}).onScroll({ scrub: true, pin: '.section-wrapper', start: 'top top', end: '+=600' });
+```
+
+**`toggleActions`** controls what happens at each scroll boundary. Format: `"onEnter onLeave onEnterBack onLeaveBack"`. Default: `"play reverse play reverse"`. Valid actions: `play`, `pause`, `resume`, `reverse`, `restart`, `reset`, `complete`, `none`.
+
+```ts
+// Play once — never reverse (common for reveal animations)
+.onScroll({ toggleActions: 'play none none none' });
+
+// Re-animate every time it enters the viewport
+.onScroll({ toggleActions: 'restart none none reset' });
+```
+
+**`markers`** accepts `true` for default debug markers, or a `MarkerConfig` object for custom styling:
+
+```ts
+interface MarkerConfig {
+  startColor?: string;   // Default: 'green'
+  endColor?: string;     // Default: 'red'
+  fontSize?: string;     // e.g. '12px'
+  fontWeight?: string;
+  indent?: number;       // Horizontal offset in pixels
 }
 ```
 
@@ -408,8 +583,7 @@ Motion('h-scroll', '.panel', {
 
 ```ts
 Motion('parallax', '.hero-bg', {
-  from: { y: 0 },
-  to:   { y: -100 },
+  to: { y: -100 },
 }).onScroll({ scrub: 1, start: 'top top', end: 'bottom top' });
 ```
 
@@ -428,6 +602,15 @@ interface MouseMoveConfig {
 }
 ```
 
+**Defaults:**
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `type` | `'distance'` | |
+| `startProgress` | `0.5` | Progress value when mouse is at rest |
+| `leaveProgress` | `0.5` | Progress to animate to on mouse leave |
+| `smooth` | `0.1` | `0` = instant tracking, `1` = maximum lag |
+
 ```ts
 Motion('parallax-depth', '.layer', {
   from: { x: -20, y: -20 },
@@ -438,15 +621,54 @@ Motion('parallax-depth', '.layer', {
 
 #### `.onPageLoad()`
 
-Play the animation automatically when the page finishes loading.
+Play the animation automatically when the page finishes loading. If called after `DOMContentLoaded` has already fired (common in SPAs or scripts placed at the bottom of `<body>`), the animation plays immediately.
 
 ```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 },
+  { target: '.logo',  from: { opacity: 0 }, duration: 0.5 },
+  { target: '.nav',   from: { y: -20, opacity: 0 }, duration: 0.4 },
 ]).onPageLoad();
 ```
 
+#### `.onPageExit(config?)`
+
+Intercept link clicks, play the exit animation, then navigate to the destination URL after the timeline completes. Works on any website with no server-side dependencies.
+
+```ts
+interface PageExitConfig {
+  /** 'all' (default) | 'include' | 'exclude' */
+  mode?: 'all' | 'include' | 'exclude';
+  /** CSS selectors for links — required when mode is 'include' or 'exclude' */
+  selectors?: string;
+  /** Href patterns to skip automatically. Note: 'mailto' also skips tel: links. */
+  skipHref?: ('anchor' | 'javascript' | 'mailto')[];
+}
+```
+
+- `mode: 'all'` (default) — intercepts every `<a>` on the page
+- `mode: 'include'` — only links matching `selectors`
+- `mode: 'exclude'` — all links except those matching `selectors`
+- Automatically skips `target="_blank"` links and modifier-key clicks (Cmd/Ctrl/Shift/Alt)
+
+```ts
+// Fade-out on page exit — all links
+Motion('page-exit', 'body', {
+  to: { opacity: 0 },
+  duration: 0.4,
+  ease: 'power2.in',
+}).onPageExit();
+
+// Only internal nav links
+Motion('page-exit', 'body', {
+  to: { opacity: 0 },
+  duration: 0.4,
+}).onPageExit({
+  mode: 'include',
+  selectors: 'nav a',
+  skipHref: ['anchor', 'mailto'],
+});
+```
+
 #### `.onGesture(config)`
 
 Respond to pointer, touch, wheel, or scroll gestures with fine-grained event-to-action mapping.
@@ -484,10 +706,36 @@ interface GestureConfig {
 }
 ```
 
+**Config defaults:**
+
+| Option | Default | Unit | Notes |
+|--------|---------|------|-------|
+| `tolerance` | `1` | px | Min movement before direction events fire |
+| `dragMinimum` | `10` | px | Distance before `Drag` fires |
+| `wheelSpeed` | `1` | multiplier | Scales wheel delta |
+| `scrollSpeed` | `1` | multiplier | Scales scroll delta |
+| `stopDelay` | `150` | ms | Idle time after movement before `Stop` fires |
+| `smooth` | `0` | 0–1 | Smoothness for `progressUp`/`progressDown` actions |
+| `animationStep` | `0.1` | 0–1 | Progress step per event for `progressUp`/`progressDown` |
+
+**Event distinctions:**
+
+- `Up`/`Down`/`Left`/`Right` — fire **continuously** during movement
+- `UpComplete`/`DownComplete`/etc. — fire **once on release** if that direction was active
+- `PressInit` — fires immediately on press, before start position is recorded
+- `Press` — fires after start position is recorded
+- `Hover`/`HoverEnd` — require a `target` element (not the window)
+- `playNext`/`playPrevious` actions — only work when `each: true` is set
+
+`animationStep` can be a single number or a per-event map:
+
+```ts
+animationStep: { Up: 0.2, Down: 0.1 }  // different step size per direction
+```
+
 ```ts
 Motion('swipe-gallery', '.gallery', {
-  from: { x: 0 },
-  to:   { x: -100 },
+  to: { x: -100 },
 }).onGesture({
   types: ['pointer', 'touch'],
   events: {
@@ -518,6 +766,18 @@ interface CursorConfig {
 }
 ```
 
+**`CursorStateVars`** is the shape used for `default`, `hover`, and `click`. The `targets` field controls which elements trigger that state:
+
+```ts
+interface CursorStateVars {
+  targets?: string[];    // CSS selectors that trigger this state (e.g. ['a', 'button', '.btn'])
+  duration?: number;     // Transition duration in seconds (default: 0.15)
+  ease?: string;         // Easing (default: 'power3.inOut')
+  enabled?: boolean;     // Whether state is active (default: true)
+  [key: string]: any;    // Any CSS property: width, height, backgroundColor, scale, etc.
+}
+```
+
 ```ts
 Motion('custom-cursor', 'body', {
   to: { opacity: 1 },
@@ -527,11 +787,52 @@ Motion('custom-cursor', 'body', {
   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 },
+  hover: {
+    targets: ['a', 'button', '[data-cursor-hover]'],
+    width: 40, height: 40,
+    backgroundColor: 'transparent',
+    borderColor: '#fff',
+  },
+  click: { scale: 0.8 },
+});
+```
+
+**`type: 'text'`** — reads text from `mp-cursor-text` or `mp-cursor-tooltip` HTML attributes and displays it inside the cursor element. The `text` config object sets CSS properties on the text node:
+
+```ts
+Motion('cursor', 'body', { to: { opacity: 1 }, duration: 0 }).onCursor({
+  target: '#cursor',
+  type: 'text',
+  hideNative: true,
+  default: { width: 12, height: 12, borderRadius: '50%', backgroundColor: '#fff' },
+  hover:   { width: 64, height: 64 },
+  text: { fontSize: '12px', color: '#000', fontWeight: 'bold' },
+});
+```
+
+```html
+<a href="/about" mp-cursor-text="About Us">About</a>
+<button mp-cursor-tooltip="Click me">Button</button>
+```
+
+**`type: 'media'`** — reads an image or video URL from the `mp-cursor-media` attribute and renders it inside the cursor. Supports http/https and relative URLs. The `media` config object sets CSS on the media element:
+
+```ts
+Motion('cursor', 'body', { to: { opacity: 1 }, duration: 0 }).onCursor({
+  target: '#cursor',
+  type: 'media',
+  hideNative: true,
+  default: { width: 48, height: 48, borderRadius: '50%' },
+  hover:   { width: 120, height: 80 },
+  media: { borderRadius: '8px', objectFit: 'cover' },
 });
 ```
 
+```html
+<div class="project-card" mp-cursor-media="/images/preview.jpg">…</div>
+<div class="video-card" mp-cursor-media="https://cdn.example.com/preview.mp4">…</div>
+```
+
 ---
 
 ### Lifecycle Callbacks
@@ -543,7 +844,6 @@ Attach callbacks via the `AnimationConfig` object or directly on the `Timeline`
 ```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),
@@ -557,7 +857,7 @@ Motion('slide-in', '.card', {
 #### Via `Timeline` Methods
 
 ```ts
-Motion('slide-in', '.card', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 0.6 })
+Motion('slide-in', '.card', { from: { opacity: 0 }, duration: 0.6 })
   .onStart(() => console.log('started'))
   .onUpdate((progress, time) => console.log(progress, time))
   .onComplete(() => console.log('done'));
@@ -585,8 +885,10 @@ interface AnimationConfig {
   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
+  repeat?:   number | RepeatConfig; // Repeat count shorthand or full config (see below)
   split?:    SplitType;             // Text splitting for per-char/word/line animation
+  mask?:     boolean;               // Wrap split elements in overflow:hidden for reveal effects
+  fit?:      FitConfig;             // FLIP-style morph toward another element
   axis?:     'x' | 'y';            // Axis binding for onMouseMove animations
 
   // Lifecycle
@@ -638,13 +940,68 @@ drawSVG                                    // string | { start?: number; end?: n
 
 // Motion path
 path: {
-  target:   string | Element;             // SVG <path> selector or element
+  target:   string | Element;             // SVG <path> selector, element, or raw path data (starts with M/m)
   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
 }
+
+// CSS custom properties
+'--my-var'                                 // any CSS custom property name (string)
+```
+
+### drawSVG
+
+Animate the visible portion of an SVG stroke. The element must have a `stroke` and a set `stroke-dasharray` (or the SDK will compute it automatically).
+
+| Format | Meaning |
+|--------|---------|
+| `"0% 100%"` | Full stroke visible |
+| `"0% 0%"` | Stroke fully hidden (start position for a draw-in) |
+| `"20% 80%"` | Middle portion only |
+| `"50%"` | Shorthand for `"0% 50%"` |
+| `"100px 500px"` | Pixel range along the stroke |
+| `{ start: 20, end: 80 }` | Object form — values are **percentages 0–100**, not 0–1 |
+
+```ts
+// Animate stroke from hidden to fully drawn
+Motion('draw-path', 'path#line', {
+  from: { drawSVG: '0% 0%' },
+  to:   { drawSVG: '0% 100%' },
+  duration: 1.2,
+  ease: 'power2.inOut',
+}).onPageLoad();
+
+// Object format — percentages, not 0–1
+Motion('draw-partial', '#circle', {
+  to: { drawSVG: { start: 20, end: 80 } },
+  duration: 0.8,
+}).play();
+```
+
+### path
+
+`path.target` accepts a CSS selector, an `Element`, or raw SVG path data (a string starting with `M` or `m`):
+
+```ts
+// Inline path data — no DOM element required
+Motion('fly', '.icon', {
+  to: { path: { target: 'M 0 100 C 50 0 150 200 200 100', rotate: true } },
+  duration: 2,
+}).play();
+```
+
+### CSS Custom Properties
+
+CSS custom properties can be animated by passing the property name as a string key:
+
+```ts
+Motion('theme', ':root', {
+  to: { '--primary-hue': 240, '--accent-opacity': 0.8 },
+  duration: 0.5,
+}).onClick({ target: '#theme-btn' });
 ```
 
 ### StaggerVars
@@ -662,12 +1019,23 @@ interface StaggerVars {
 
 ### RepeatConfig
 
+The `repeat` field accepts either a plain number or a `RepeatConfig` object:
+
 ```ts
+// Shorthand — number of additional repetitions
+repeat: 3    // repeat 3 more times after the first play
+repeat: -1   // repeat infinitely
+
+// Full config
 interface RepeatConfig {
   times: number;      // Number of additional repetitions (-1 = infinite)
   delay?: number;     // Seconds between repetitions
   yoyo?: boolean;     // Alternate direction each cycle
 }
+
+// Examples
+repeat: { times: -1, yoyo: true, delay: 0.2 }  // infinite yoyo with pause between cycles
+repeat: { times: 2, yoyo: true, delay: 0.5 }   // 2 extra cycles, yoyo, 0.5s pause
 ```
 
 ### SplitType
@@ -682,18 +1050,67 @@ type SplitType =
   | 'chars,words,lines';
 ```
 
-Text is split into wrapper `<span>` elements before animating. `Motion.reset()` reverts the DOM.
+Text is split into wrapper `<span>` elements before animating. `Motion.reset()` reverts the DOM. Inline elements (like `<span class="accent">`) are preserved during splitting.
+
+Split elements receive data attributes for CSS targeting:
+
+| Attribute | Set on | Index attribute |
+|-----------|--------|-----------------|
+| `[data-split-char]` | each character span | `data-char-index` |
+| `[data-split-word]` | each word span | `data-word-index` |
+| `[data-split-line]` | each line span | `data-line-index` |
+| `[data-split-mask]` | overflow wrapper (when `mask: true`) | — |
 
 ```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();
 ```
 
+### mask
+
+When `mask: true` is used together with `split`, each split element (char, word, or line) is wrapped in a parent with `overflow: hidden`. This clips animated content to its natural bounds, creating a 'reveal' effect — for example, animating `y: '100%'` makes text slide up from behind an invisible edge.
+
+```ts
+Motion('reveal', 'h1', {
+  split: 'lines',
+  mask: true,
+  from: { y: '100%' },
+  stagger: 0.1,
+}).onPageLoad();
+```
+
+### FitConfig
+
+FLIP-style morph animation. When `fit` is set, `from` and `to` are ignored — the SDK measures both elements' bounding rects at play time and animates the visual delta between them.
+
+```ts
+interface FitConfig {
+  /** CSS selector for the target element to morph toward */
+  target: string;
+  /** Convert to absolute positioning during animation. Default: false */
+  absolute?: boolean;
+  /** Include scale changes. Default: true */
+  scale?: boolean;
+  /** Animate actual width/height instead of scaleX/scaleY. Default: false */
+  resize?: boolean;
+}
+```
+
+- **`scale: true`** (default) — animates using `scaleX`/`scaleY`. Fast, GPU-accelerated, but can distort text, borders, and box-shadows.
+- **`resize: true`** — animates actual `width`/`height` properties instead. No visual distortion, but triggers layout reflow. Mutually exclusive with `scale`.
+
+```ts
+Motion('reorder', '.container', {
+  fit: { target: '.item', resize: true },
+  duration: 0.5,
+  ease: 'power2.inOut',
+}).play();
+```
+
 ---
 
 ## Easing
@@ -703,23 +1120,22 @@ Easing names are **case-insensitive** strings. Pass them to `AnimationConfig.eas
 | 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` |
+| `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();
@@ -731,6 +1147,8 @@ Motion('spring-in', '.box', {
 
 All types are re-exported from the package entry point.
 
+Most users won't need to import types directly — TypeScript infers everything from the `Motion()` function signature, so you get full autocomplete and type checking out of the box. These exports are provided for advanced use cases like building wrapper libraries or typing standalone config objects.
+
 ```ts
 import type {
   // Core
@@ -747,6 +1165,7 @@ import type {
   RepeatConfig,
   SplitType,
   PathConfig,
+  FitConfig,
 
   // Triggers
   HoverConfig,
@@ -754,6 +1173,7 @@ import type {
   ScrollConfig,
   MouseMoveConfig,
   MarkerConfig,
+  PageExitConfig,
 
   // Gesture
   GestureConfig,
@@ -765,38 +1185,38 @@ import type {
   CursorConfig,
   CursorStateVars,
   CursorSqueezeConfig,
-} from '@motion/sdk';
+} from '@motion.page/sdk';
 
 // Namespace import
-import { Types } from '@motion/sdk';
+import { Types } from '@motion.page/sdk';
 ```
 
 ---
 
 ## Browser Build
 
-A pre-built IIFE bundle is generated at `dist/motion-sdk.browser.js` for direct `<script>` tag usage:
+### Browser Build (IIFE)
+
+An IIFE build script is included but not part of the default build output. To generate a browser bundle:
+
+```bash
+bun run packages/sdk/scripts/build-iife.ts
+```
+
+This creates a self-contained script that exposes `window.Motion` and `window.MotionTimeline`:
 
 ```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,
+  Motion('fade', '.hero', {
+    from: { opacity: 0, y: 30 },
+    duration: 0.8,
   }).onPageLoad();
 </script>
 ```
 
-To regenerate the browser bundle:
-
-```bash
-bun run packages/sdk/scripts/build-iife.ts
-```
-
 ---
 
 ## Browser Support
@@ -814,4 +1234,12 @@ Modern evergreen browsers:
 
 ## License
 
-Proprietary — see [LICENSE](../../LICENSE) for details.
+**FSL-1.1-Apache-2.0** — [Functional Source License, Version 1.1, Apache 2.0 Future License](./LICENSE)
+
+**TL;DR:** Free for everyone. Use it in your websites, apps, SaaS products, client projects — commercial or not. No restrictions.
+
+**The one exception:** You cannot use this SDK to build a product that competes with Motion.page (e.g., a no-code animation builder, visual animation editor, or similar tool). If you're building something like that, [contact us](mailto:hello@motion.page) for an enterprise license.
+
+After 2 years from each release, the code converts to the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license with no restrictions at all.
+
+See [LICENSE](./LICENSE) for the full legal text.