wix · ydaniv · May 20, 2026
diff --git a/packages/motion/README.md b/packages/motion/README.md
@@ -1,182 +1,188 @@
-# Wix Motion
+# @wix/motion
 
-A comprehensive animation library featuring 82+ carefully crafted presets, designed for modern web applications, built on native browser technology.
+Low-level, web-native animation engine — WAAPI, CSS, scroll-driven, and pointer-tracking animations with a single dependency.
 
-## ✨ Features
+[![npm version](https://img.shields.io/npm/v/@wix/motion.svg)](https://www.npmjs.com/package/@wix/motion)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@wix/motion)](https://bundlephobia.com/package/@wix/motion)
+[![license](https://img.shields.io/npm/l/@wix/motion.svg)](./LICENSE)
 
-- **Web Platform First** - Built on native browser technology for smooth 60fps animations
-- **82+ Animation Presets** - Professionally designed animations ready to use
-- **5 Animation Categories** - Entrance, Ongoing, Scroll, Mouse, and Background Scroll effects
-- **TypeScript Support** - Complete type definitions with IntelliSense support
-- **Dual Rendering** - Both Web Animations API and CSS-based rendering
-- **Scroll Integration** - Advanced scroll-driven animations with ViewTimeline API support
-- **Mouse Parallax** - Interactive pointer-based animations
-- **Performance Optimized** - Uses fastdom to minimize layout thrashing
+## Why Motion?
 
-## 🚀 Quick Start
+- **Native-first** — Built directly on the Web Animations API and CSS Animations.
+- **ViewTimeline** — First-class scroll-driven animations via the ViewTimeline API, with a scrub fallback when the API is unavailable.
+- **Pointer-driven** — `pointer-move` animations map cursor `(x, y)` progress to effects, with optional transition smoothing.
+- **Custom effects** — Plug in programmatic render callbacks — no preset registration required.
+- **Dual rendering** — Choose CSS for declarative effects or WAAPI for fine-grained control, using the same options shape.
+- **Performance** — `fastdom` batches DOM reads/writes; no `requestAnimationFrame` loop unless a custom callback opts in.
+- **Pluggable presets** — `registerEffects()` accepts any effect module. Use [`@wix/motion-presets`](../motion-presets) or roll your own.
 
-### Installation
+Motion is the engine layer. [`@wix/interact`](../interact) is the declarative configuration layer built on top of it.
+
+## Install
 
 ```bash
 npm install @wix/motion
 ```
 
-### Basic Usage
+## Quick Start
+
+### Time-based animation (WAAPI)
 
 ```typescript
 import { getWebAnimation } from '@wix/motion';
 
-// Create a fade-in entrance animation
-const animation = getWebAnimation(document.getElementById('myElement'), {
-  namedEffect: { type: 'FadeIn' },
-  duration: 1000,
-  easing: 'easeOut',
+const animation = getWebAnimation(document.getElementById('hero'), {
+  keyframeEffect: {
+    name: 'fade-up',
+    keyframes: [
+      { opacity: 0, transform: 'translateY(20px)' },
+      { opacity: 1, transform: 'translateY(0)' },
+    ],
+  },
+  duration: 600,
+  easing: 'ease-out',
 });
 
-// Play the animation
-await animation.play();
+animation.play();
 ```
 
-### Scroll-Driven Animation
+### Scroll-driven (ViewTimeline)
 
 ```typescript
-import { getScrubScene } from '@wix/motion';
+import { getWebAnimation } from '@wix/motion';
+
+const scrollRoot = document.getElementById('viewport')!;
 
-// Create a scroll-driven parallax effect
-const scene = getScrubScene(
-  document.getElementById('scrollElement'),
+const animation = getWebAnimation(
+  document.getElementById('parallax'),
   {
-    namedEffect: {
-      type: 'ParallaxScroll',
-      speed: 0.5,
+    keyframeEffect: {
+      name: 'parallax',
+      keyframes: [{ transform: 'translateY(80px)' }, { transform: 'translateY(-80px)' }],
     },
+    startOffset: { name: 'cover', offset: { value: 0, unit: 'percentage' } },
+    endOffset: { name: 'cover', offset: { value: 100, unit: 'percentage' } },
   },
-  { trigger: 'view-progress', element: document.getElementById('viewport') },
+  { trigger: 'view-progress', element: scrollRoot },
 );
 ```
 
-## 📚 Animation Categories
-
-### 🎭 Entrance Animations (24 presets)
-
-Perfect for element reveals and page transitions:
-
-- **FadeIn** - Simple opacity transition
-- **ArcIn** - Curved motion with 3D rotation
-- **BounceIn** - Spring-based entrance with bounce effect
-- **SlideIn** - Directional slides from off-screen
-- **FlipIn** - 3D flip transitions
-- [See all entrance animations →](docs/categories/entrance-animations.md)
-
-### 🔄 Ongoing Animations (16 presets)
-
-Continuous looping animations for attention and delight:
-
-- **Pulse** - Rhythmic scaling effect
-- **Breathe** - Organic scaling animation
-- **Spin** - Smooth rotation loops
-- **Wiggle** - Playful shake motions
-- **Float** - Gentle floating movement
-- [See all ongoing animations →](docs/categories/ongoing-animations.md)
-
-### 📜 Scroll Animations (19 presets)
-
-Scroll-synchronized effects that respond to viewport position:
+### Scroll-driven (polyfill / custom scrubbing)
 
-- **ParallaxScroll** - Classic parallax movement
-- **FadeScroll** - Opacity changes on scroll
-- **GrowScroll** - Scale transformations
-- **RevealScroll** - Clip-path reveals
-- **TiltScroll** - 3D perspective tilting
-- [See all scroll animations →](docs/categories/scroll-animations.md)
+```typescript
+import { getScrubScene } from '@wix/motion';
 
-### 🖱️ Mouse Animations (12 presets)
+const scrollRoot = document.getElementById('viewport')!;
 
-Interactive pointer-driven effects:
+const scenes = getScrubScene(
+  document.getElementById('parallax'),
+  {
+    keyframeEffect: {
+      name: 'parallax',
+      keyframes: [{ transform: 'translateY(80px)' }, { transform: 'translateY(-80px)' }],
+    },
+    startOffset: { name: 'cover', offset: { value: 0, unit: 'percentage' } },
+    endOffset: { name: 'cover', offset: { value: 100, unit: 'percentage' } },
+  },
+  { trigger: 'view-progress', element: scrollRoot },
+);
+// Drive each scene's `effect(scene, progress)` from your own scroll/IO listener
+// when ViewTimeline is unavailable.
+```
 
-- **TrackMouse** - Element follows cursor
-- **Tilt3DMouse** - 3D tilt based on pointer position
-- **ScaleMouse** - Dynamic scaling on hover
-- **BlurMouse** - Motion blur effects
-- [See all mouse animations →](docs/categories/mouse-animations.md)
+Quickstart examples use `keyframeEffect` (inline keyframes) so they run without registering presets.
 
-### 🖼️ Background Scroll Animations (12 presets)
+## Animation Modes
 
-Specialized effects for background media elements:
+| Mode           | Driver                        | API                                            |
+| -------------- | ----------------------------- | ---------------------------------------------- |
+| Time-based     | Duration + easing             | `getWebAnimation()` / `getCSSAnimation()`      |
+| Scroll-driven  | ViewTimeline / external scrub | `getScrubScene()` with `view-progress` trigger |
+| Pointer-driven | Mouse / touch position        | `getScrubScene()` with `pointer-move` trigger  |
 
-- **BgParallax** - Background parallax scrolling
-- **BgZoom** - Dynamic background scaling
-- **BgFade** - Background opacity transitions
-- **BgRotate** - Background rotation effects
-- [See all background animations →](docs/categories/background-scroll-animations.md)
+## Core API
 
-## 🛠️ Core APIs
+| Function             | Purpose                                                     |
+| -------------------- | ----------------------------------------------------------- |
+| `getWebAnimation()`  | Create WAAPI-backed animations (time- or scroll-linked)     |
+| `getCSSAnimation()`  | Generate CSS animation descriptors for stylesheet injection |
+| `getScrubScene()`    | Build scroll-polyfill or pointer-driven scrub scenes        |
+| `prepareAnimation()` | Pre-measure / mutate DOM via `fastdom` before animating     |
+| `getAnimation()`     | Auto-select CSS (if present) or WAAPI path                  |
+| `getSequence()`      | Coordinate staggered groups with easing-based offsets       |
+| `registerEffects()`  | Register named effect modules into the global registry      |
 
-### Animation Creation
+See [`docs/api/`](./docs/api/) for full signatures and options.
 
-- `getWebAnimation()` - Create Web Animations API instances
-- `getScrubScene()` - Generate scroll/pointer-driven scenes
-- `prepareAnimation()` - Pre-calculate measurements for performance
+## Custom Effects
 
-### CSS Integration
+Three ways to define what an animation does:
 
-- CSS custom properties for dynamic values
-- CSS Animation API for stylesheet-based animations
-- Automatic vendor prefixing and fallbacks
+1. **Inline keyframes** — pass `keyframeEffect: { name, keyframes }` directly. Zero registration.
+2. **Custom callback** — pass `customEffect: (element, progress) => void` for full programmatic control per frame.
+3. **Named presets** — pass `namedEffect: { type: '…', …params }` referencing effects you've registered via `registerEffects()` (use [`@wix/motion-presets`](../motion-presets) or your own modules).
 
-### TypeScript Support
+## Sequences and Staggering
 
-Complete type definitions for all animation options:
+`getSequence()` coordinates multiple `AnimationGroup`s with staggered offsets. The stagger interval can be eased so groups bunch toward the start or end of the sequence.
 
 ```typescript
-interface TimeAnimationOptions {
-  namedEffect: EntranceAnimation | OngoingAnimation;
-  duration?: number;
-  easing?: string;
-  // ... more options
-}
-```
-
-## 📖 Documentation
+import { getSequence } from '@wix/motion';
+
+const sequence = getSequence(
+  { offset: 150, offsetEasing: 'quadIn' },
+  Array.from(document.querySelectorAll('.card')).map((el) => ({
+    target: el,
+    options: {
+      duration: 600,
+      easing: 'ease-out',
+      keyframeEffect: {
+        name: 'fade-up',
+        keyframes: [
+          { opacity: 0, transform: 'translateY(20px)' },
+          { opacity: 1, transform: 'translateY(0)' },
+        ],
+      },
+    },
+  })),
+);
 
-- **[Getting Started](docs/getting-started.md)** - Setup and first animation
-- **[Core Concepts](docs/core-concepts.md)** - Understanding the animation system
-- **[API Reference](docs/api/)** - Complete function documentation
-- **[Category Guides](docs/categories/)** - Detailed category overviews
-- **[Preset Reference](docs/presets/)** - Individual animation documentation
-- **[Advanced Usage](docs/guides/)** - Performance tips and patterns
+sequence.play();
+```
 
-## 🎮 Interactive Playground
+See [`docs/api/get-sequence.md`](./docs/api/get-sequence.md) for the full stagger model.
 
-Explore animations interactively in our Storybook playground:
+## ViewTimeline and Polyfills
 
-```bash
-yarn start  # Opens interactive documentation
-```
+Motion is built around progressive enhancement:
 
-## 🔧 Framework Integration
+- **Native path** — when `window.ViewTimeline` is available, `getWebAnimation()` with a `view-progress` trigger returns a WAAPI animation linked to the scroll timeline.
+- **Polyfill path** — `getScrubScene()` with `view-progress` returns `ScrubScrollScene[]` objects exposing `start`, `end`, `viewSource`, and `effect(scene, progress)`. Drive these from your own IntersectionObserver/scroll listener (or use the scroll driver in `@wix/interact`).
+- **Pointer smoothing** — `ScrubPointerScene` accepts `transitionDuration` and `transitionEasing` so pointer-tracking effects don't snap to the cursor.
 
-Works seamlessly with popular frameworks:
+## Performance Notes
 
-- React/Vue/Angular components
-- GSAP and Framer Motion compatibility
-- CSS-in-JS libraries
-- Server-side rendering support
+- `prepareAnimation()` runs `fastdom` measure/mutate phases before the animation starts, avoiding layout thrash.
+- The CSS rendering path (`getCSSAnimation`) offloads work to the compositor thread.
+- No `requestAnimationFrame` loop runs unless a `customEffect` callback is used.
 
-## 🌐 Browser Support
+## Browser Support
 
-- **Modern browsers** with Web Animations API
-- **Progressive enhancement** with CSS fallbacks
-- **ViewTimeline API** for advanced scroll effects (with polyfill)
+Modern evergreen browsers with Web Animations API support (Chrome, Edge, Firefox, Safari). The ViewTimeline API is used where available; pair `getScrubScene()` with an external driver for older browsers.
 
-## 🤝 Contributing
+## Related Packages
 
-This package is part of the Wix wow-libs monorepo. See [contributing guidelines](../../CONTRIBUTING.md) for development setup and contribution process.
+- [`@wix/interact`](../interact) — declarative, config-driven interaction layer built on Motion.
+- [`@wix/motion-presets`](../motion-presets) — ready-made effect catalog (entrance, ongoing, scroll, mouse, background-scroll).
 
-## 📄 License
+## Documentation
 
-UNLICENSED - Internal Wix package
+- [Getting Started](./docs/getting-started.md)
+- [Core Concepts](./docs/core-concepts.md)
+- [API Reference](./docs/api/)
+- [Category Guides](./docs/categories/)
+- [Advanced Patterns](./docs/guides/)
 
----
+## License
 
-**Built with ❤️ by the Wix wow!Team**
+MIT