@motion.page/sdk 0.1.0 → 0.1.1

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)
+![License](https://img.shields.io/badge/license-Proprietary-red)
 
 ---
 
@@ -30,11 +32,16 @@ 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).
+For direct browser use without a bundler, see [Browser Build](#browser-build).
 
 ---
 
@@ -43,7 +50,7 @@ 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', {
@@ -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,13 @@ 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 }, to: { opacity: 1 }, duration: 0.8 }).onPageLoad();
+```
+
 ---
 
 ## API Reference
@@ -149,7 +179,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 +214,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,6 +334,8 @@ 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 })
@@ -320,6 +359,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`.
@@ -375,12 +430,56 @@ 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 },
+  to:   { opacity: 1, y: 0 },
+  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`, `reverse`, `restart`, `reset`, `complete`, `kill`, `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
 }
 ```
 
@@ -428,6 +527,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,7 +546,7 @@ 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', [
@@ -447,6 +555,45 @@ Motion('page-intro', [
 ]).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,6 +631,33 @@ 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 },
@@ -518,6 +692,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 +713,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
@@ -585,8 +812,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 +867,68 @@ drawSVG                                    // string | { start?: number; end?: n
 
 // Motion path
 path: {
-  target:   string | Element;             // SVG <path> selector or element
+  target:   string | Element | string;    // 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 +946,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,7 +977,16 @@ 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', {
@@ -694,6 +998,48 @@ Motion('text-reveal', '.headline', {
 }).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%' },
+  to:   { y: 0 },
+  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
@@ -731,6 +1077,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 +1095,7 @@ import type {
   RepeatConfig,
   SplitType,
   PathConfig,
+  FitConfig,
 
   // Triggers
   HoverConfig,
@@ -754,30 +1103,33 @@ import type {
   ScrollConfig,
   MouseMoveConfig,
   MarkerConfig,
+  PageExitConfig,
 
   // Gesture
   GestureConfig,
   GestureEvent,
   GestureAction,
   GestureInputType,
+  TimelineAction,
 
   // Cursor
   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:
+A pre-built IIFE bundle (`motion-sdk.browser.js`) is included in the package's `dist/` folder and can be used directly via a `<script>` tag — no bundler required. You can also load it from a CDN that mirrors npm packages (e.g. jsDelivr or unpkg).
 
 ```html
+<!-- From your own server / CDN -->
 <script src="motion-sdk.browser.js"></script>
 <script>
   // Globals are exposed on window:
@@ -791,12 +1143,6 @@ A pre-built IIFE bundle is generated at `dist/motion-sdk.browser.js` for direct
 </script>
 ```
 
-To regenerate the browser bundle:
-
-```bash
-bun run packages/sdk/scripts/build-iife.ts
-```
-
 ---
 
 ## Browser Support