@wix/interact 2.1.3 → 2.2.0

package/rules/pointermove.md

@@ -1,1074 +1,148 @@
 # PointerMove Trigger Rules for @wix/interact
 
-These rules help generate pointer-driven interactions using the `@wix/interact` library. PointerMove triggers create real-time animations that respond to mouse movement over elements, perfect for 3D effects, cursor followers, and interactive cards.
+These rules help generate pointer-driven interactions using `@wix/interact`. PointerMove triggers create real-time animations that respond to mouse movement over elements or the entire viewport.
 
-## Core Concepts
+## Table of Contents
 
-### Effect Types for PointerMove
+- [Trigger Source Elements with `hitArea: 'self'`](#trigger-source-elements-with-hitarea-self)
+- [PointerMoveParams](#pointermoveparams)
+- [Progress Object Structure](#progress-object-structure)
+- [Centering with `centeredToTarget`](#centering-with-centeredtotarget)
+- [Device Conditions](#device-conditions)
+- [Rule 1: namedEffect](#rule-1-namedeffect)
+- [Rule 2: keyframeEffect with Single Axis](#rule-2-keyframeeffect-with-single-axis)
+- [Rule 3: Two keyframeEffects with Two Axes and `composite`](#rule-3-two-keyframeeffects-with-two-axes-and-composite)
+- [Rule 4: customEffect](#rule-4-customeffect)
 
-The `pointerMove` trigger provides 2D progress (x and y coordinates). You can use:
+## Trigger Source Elements with `hitArea: 'self'`
 
-1. **`namedEffect`** (Preferred): Pre-built mouse presets from `@wix/motion-presets` that handle 2D progress internally
-2. **`customEffect`** (Advanced): Custom function receiving the 2D progress object for full control
-3. **`keyframeEffect`** (Single-axis): The pointer position on a single axis is mapped to linear 0-1 progress for keyframe animations. Use `axis: 'x'` or `axis: 'y'` (defaults to `'y'`)
+When using `hitArea: 'self'`, the source element is the hit area for pointer tracking:
 
-### Hit Area Configuration (`hitArea`)
+- The source element **MUST NOT** have `pointer-events: none` — it needs to receive pointer events.
+- **CRITICAL**: MUST AVOID using the same element as both source and target with effects that change size or position (e.g. `transform: translate(…)`, `scale(…)`). The transform shifts the hit area, causing jittery re-entry cycles. Instead, use `selector` to target a child element for the animation.
 
-The `hitArea` parameter determines where mouse movement is tracked:
-
-| Value    | Behavior                                              | Best For                                 |
-| -------- | ----------------------------------------------------- | ---------------------------------------- |
-| `'self'` | Tracks mouse within the source element's bounds only  | Local hover effects, card interactions   |
-| `'root'` | Tracks mouse anywhere in the viewport (document root) | Global cursor followers, ambient effects |
-
-### Progress Object Structure (for `customEffect`)
-
-When using `customEffect` with `pointerMove`, the progress parameter is an object:
-
-```typescript
-type Progress = {
-  x: number; // 0-1: horizontal position (0 = left edge, 1 = right edge)
-  y: number; // 0-1: vertical position (0 = top edge, 1 = bottom edge)
-  v?: {
-    // Velocity (optional)
-    x: number; // Horizontal velocity
-    y: number; // Vertical velocity
-  };
-  active?: boolean; // Whether mouse is currently in the hit area
-};
-```
-
-### Centering with `centeredToTarget`
-
-Controls how the progress range is calculated:
-
-| Value   | Behavior                                           | Use When                                 |
-| ------- | -------------------------------------------------- | ---------------------------------------- |
-| `true`  | Centers the coordinate range at the target element | Source and target are different elements |
-| `false` | Uses source element bounds for calculations        | Cursor followers, global effects         |
-
-## Rule 1: Single Element Pointer Effects with 3D Named Effects
-
-**Use Case**: Interactive 3D transformations on individual elements that respond to mouse position (e.g., card tilting, 3D product showcases, interactive buttons)
-
-**When to Apply**:
-
-- For interactive card hover effects
-- When creating 3D product showcases
-- For engaging button interactions
-- When building interactive UI elements that respond to mouse movement
-
-**Pattern**:
-
-```typescript
-{
-    key: '[SOURCE_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: '[HIT_AREA]'
-    },
-    effects: [
-        {
-            key: '[TARGET_KEY]',
-            namedEffect: {
-                type: '[3D_EFFECT_TYPE]',
-                [EFFECT_PROPERTIES]
-            },
-            centeredToTarget: [CENTERED_TO_TARGET],
-            effectId: '[UNIQUE_EFFECT_ID]'
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[SOURCE_KEY]`: Unique identifier for source element that tracks mouse movement
-- `[TARGET_KEY]`: Unique identifier for target element to animate (can be same as source or different)
-- `[HIT_AREA]`: 'self' (mouse within source element) or 'root' (mouse anywhere in viewport)
-- `[3D_EFFECT_TYPE]`: 'Tilt3DMouse', 'Track3DMouse', 'SwivelMouse'
-- `[EFFECT_PROPERTIES]`: Named effect specific properties (angle, perspective, direction, etc.)
-- `[CENTERED_TO_TARGET]`: true (center range at target) or false (use source element bounds)
-- `[UNIQUE_EFFECT_ID]`: Optional unique identifier
-
-**Example - Interactive Product Card**:
-
-```typescript
-{
-    key: 'product-card',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'product-card',
-            namedEffect: {
-                type: 'Tilt3DMouse',
-                angle: 15,
-                perspective: 1000
-            }
-        }
-    ]
-}
-```
-
----
-
-## Rule 2: Single Element Pointer Effects with Movement Named Effects
-
-**Use Case**: Cursor-following and position-tracking effects on individual elements (e.g., floating elements, cursor followers, responsive decorations)
-
-**When to Apply**:
-
-- For cursor-following elements
-- When creating floating responsive decorations
-- For interactive element positioning
-- When building mouse-aware UI components
-
-**Pattern**:
-
-```typescript
-{
-    key: '[SOURCE_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: '[HIT_AREA]'
-    },
-    effects: [
-        {
-            key: '[TARGET_KEY]',
-            namedEffect: {
-                type: '[MOVEMENT_EFFECT_TYPE]',
-                distance: { value: [DISTANCE_VALUE], unit: '[DISTANCE_UNIT]' },
-                axis: '[AXIS_CONSTRAINT]'
-            },
-            centeredToTarget: [CENTERED_TO_TARGET],
-            effectId: '[UNIQUE_EFFECT_ID]'
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[MOVEMENT_EFFECT_TYPE]`: 'TrackMouse', 'AiryMouse', 'BounceMouse'
-- `[DISTANCE_VALUE]`: Numeric value for movement distance
-- `[DISTANCE_UNIT]`: 'px', 'percentage', 'vw', 'vh'
-- `[AXIS_CONSTRAINT]`: 'both', 'horizontal', 'vertical'
-- Other variables same as Rule 1
-
-**Example - Cursor Follower Element**:
-
-```typescript
-{
-    key: 'cursor-follower',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'root'
-    },
-    effects: [
-        {
-            namedEffect: {
-                type: 'TrackMouse',
-                distance: { value: 50, unit: 'percentage' },
-                axis: 'both'
-            },
-            centeredToTarget: false
-        }
-    ]
-}
-```
-
-**Example - Floating Decoration**:
-
-```typescript
-{
-    key: 'hero-section',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'floating-element',
-            namedEffect: {
-                type: 'AiryMouse',
-                distance: { value: 30, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: true,
-            effectId: 'hero-float'
-        }
-    ]
-}
-```
-
----
-
-## Rule 3: Single Element Pointer Effects with Scale Named Effects
-
-**Use Case**: Dynamic scaling and deformation effects on individual elements based on mouse position (e.g., interactive scaling, organic transformations, blob effects)
-
-**When to Apply**:
-
-- For interactive scaling buttons
-- When creating organic blob-like interactions
-- For dynamic size responsive elements
-- When building creative morphing interfaces
-
-**Pattern**:
-
-```typescript
-{
-    key: '[SOURCE_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: '[HIT_AREA]'
-    },
-    effects: [
-        {
-            key: '[TARGET_KEY]',
-            namedEffect: {
-                type: '[SCALE_EFFECT_TYPE]',
-                [SCALE_PROPERTIES]
-            },
-            centeredToTarget: [CENTERED_TO_TARGET],
-            effectId: '[UNIQUE_EFFECT_ID]'
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[SCALE_EFFECT_TYPE]`: 'ScaleMouse', 'BlobMouse', 'SkewMouse'
-- `[SCALE_PROPERTIES]`: Effect-specific properties (scale, distance, axis)
-- Other variables same as Rule 1
-
-**Example - Interactive Scale Button**:
-
-```typescript
-{
-    key: 'scale-button',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'scale-button',
-            namedEffect: {
-                type: 'ScaleMouse',
-                scale: 1.1,
-                distance: { value: 100, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: true
-        }
-    ]
-}
-```
-
-**Example - Organic Blob Effect**:
-
-```typescript
-{
-    key: 'blob-container',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'blob-shape',
-            namedEffect: {
-                type: 'BlobMouse',
-                intensity: 0.8,
-                smoothness: 0.6
-            },
-            effectId: 'blob-morph'
-        }
-    ]
-}
-```
-
----
-
-## Rule 4: Single Element Pointer Effects with Visual Named Effects
-
-**Use Case**: Visual effect transformations on individual elements based on mouse position (e.g., motion blur, rotation effects, visual filters)
-
-**When to Apply**:
-
-- For creative visual interfaces
-- When adding motion blur to interactions
-- For rotation-based mouse effects
-- When creating dynamic visual feedback
-
-**Pattern**:
-
-```typescript
-{
-    key: '[SOURCE_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: '[HIT_AREA]'
-    },
-    effects: [
-        {
-            key: '[TARGET_KEY]',
-            namedEffect: {
-                type: '[VISUAL_EFFECT_TYPE]',
-                [VISUAL_PROPERTIES]
-            },
-            centeredToTarget: [CENTERED_TO_TARGET],
-            effectId: '[UNIQUE_EFFECT_ID]'
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[VISUAL_EFFECT_TYPE]`: 'BlurMouse', 'SpinMouse'
-- `[VISUAL_PROPERTIES]`: Effect-specific properties (blur amount, rotation speed)
-- Other variables same as Rule 1
-
-**Example - Motion Blur Card**:
-
-```typescript
-{
-    key: 'motion-card',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'motion-card',
-            namedEffect: {
-                type: 'BlurMouse',
-                blurAmount: 5,
-                motionIntensity: 0.7
-            },
-            centeredToTarget: true
-        }
-    ]
-}
-```
-
-**Example - Spinning Element**:
-
-```typescript
-{
-    key: 'spin-trigger',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'spinning-icon',
-            namedEffect: {
-                type: 'SpinMouse',
-                rotationSpeed: 0.5,
-                direction: 'clockwise'
-            },
-            centeredToTarget: false,
-            effectId: 'icon-spin'
-        }
-    ]
-}
-```
-
----
-
-## Rule 5: Multi-Element Pointer Parallax Effects with Named Effects
-
-**Use Case**: Coordinated pointer-driven animations across multiple elements creating layered parallax effects (e.g., multi-layer backgrounds, depth effects, coordinated element responses)
-
-**When to Apply**:
-
-- For multi-layer background effects
-- When creating depth and parallax interactions
-- For coordinated UI element responses
-- When building immersive pointer-driven experiences
-
-**Pattern**:
-
-```typescript
-{
-    key: '[CONTAINER_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: '[HIT_AREA]'
-    },
-    effects: [
-        {
-            key: '[BACKGROUND_LAYER_KEY]',
-            namedEffect: {
-                type: '[BACKGROUND_EFFECT_TYPE]',
-                distance: { value: [BACKGROUND_DISTANCE], unit: '[DISTANCE_UNIT]' }
-            },
-            centeredToTarget: [CENTERED_TO_TARGET]
-        },
-        {
-            key: '[MIDGROUND_LAYER_KEY]',
-            namedEffect: {
-                type: '[MIDGROUND_EFFECT_TYPE]',
-                distance: { value: [MIDGROUND_DISTANCE], unit: '[DISTANCE_UNIT]' }
-            },
-            centeredToTarget: [CENTERED_TO_TARGET]
-        },
-        {
-            key: '[FOREGROUND_LAYER_KEY]',
-            namedEffect: {
-                type: '[FOREGROUND_EFFECT_TYPE]',
-                distance: { value: [FOREGROUND_DISTANCE], unit: '[DISTANCE_UNIT]' }
-            },
-            centeredToTarget: [CENTERED_TO_TARGET]
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[CONTAINER_KEY]`: Unique identifier for container element tracking mouse
-- `[*_LAYER_KEY]`: Unique identifier for different layer elements
-- `[*_EFFECT_TYPE]`: Named effects for each layer (typically movement effects)
-- `[*_DISTANCE]`: Movement distance for each layer (creating depth)
-- Other variables same as previous rules
-
-**Example - Parallax Card Layers**:
-
-```typescript
-{
-    key: 'parallax-card',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'bg-layer',
-            namedEffect: {
-                type: 'AiryMouse',
-                distance: { value: 15, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'mid-layer',
-            namedEffect: {
-                type: 'TrackMouse',
-                distance: { value: 25, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'fg-layer',
-            namedEffect: {
-                type: 'BounceMouse',
-                distance: { value: 35, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: true
-        }
-    ]
-}
-```
-
-**Example - Multi-Layer Hero Section**:
-
-```typescript
-{
-    key: 'hero-container',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'hero-bg',
-            namedEffect: {
-                type: 'AiryMouse',
-                distance: { value: 20, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'hero-content',
-            namedEffect: {
-                type: 'TrackMouse',
-                distance: { value: 40, unit: 'px' },
-                axis: 'horizontal'
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'hero-decorations',
-            namedEffect: {
-                type: 'ScaleMouse',
-                scale: 1.05,
-                distance: { value: 60, unit: 'px' }
-            },
-            centeredToTarget: true
-        }
-    ]
-}
-```
-
----
-
-## Rule 6: Coordinated Group Pointer Effects with Named Effects
-
-**Use Case**: Synchronized pointer-driven animations across related elements with different responses (e.g., card grids, navigation menus, interactive galleries)
-
-**When to Apply**:
-
-- For interactive card grids
-- When building responsive navigation systems
-- For gallery hover effects
-- When creating coordinated interface responses
-
-**Pattern**:
-
-```typescript
-{
-    key: '[CONTAINER_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: '[HIT_AREA]'
-    },
-    effects: [
-        {
-            key: '[PRIMARY_ELEMENTS_KEY]',
-            namedEffect: {
-                type: '[PRIMARY_EFFECT_TYPE]',
-                [PRIMARY_EFFECT_PROPERTIES]
-            },
-            centeredToTarget: [PRIMARY_CENTERED]
-        },
-        {
-            key: '[SECONDARY_ELEMENTS_KEY]',
-            namedEffect: {
-                type: '[SECONDARY_EFFECT_TYPE]',
-                [SECONDARY_EFFECT_PROPERTIES]
-            },
-            centeredToTarget: [SECONDARY_CENTERED]
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[PRIMARY_ELEMENTS_KEY]`: Unique identifier for primary responsive elements
-- `[SECONDARY_ELEMENTS_KEY]`: Unique identifier for secondary responsive elements
-- `[PRIMARY_EFFECT_TYPE]`: Named effect for primary elements
-- `[SECONDARY_EFFECT_TYPE]`: Named effect for secondary elements
-- `[*_EFFECT_PROPERTIES]`: Properties specific to each effect type
-- `[*_CENTERED]`: Centering configuration for each element group
-- Other variables same as previous rules
-
-**Example - Interactive Card Grid**:
-
-```typescript
-{
-    key: 'card-grid',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'grid-card',
-            namedEffect: {
-                type: 'Tilt3DMouse',
-                angle: 12,
-                perspective: 1000
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'card-shadow',
-            namedEffect: {
-                type: 'AiryMouse',
-                distance: { value: 20, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: true
-        }
-    ]
-}
-```
-
-**Example - Navigation Menu Response**:
-
-```typescript
-{
-    key: 'nav-container',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'nav-item',
-            namedEffect: {
-                type: 'ScaleMouse',
-                scale: 1.05,
-                distance: { value: 80, unit: 'px' }
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'nav-indicator',
-            namedEffect: {
-                type: 'TrackMouse',
-                distance: { value: 15, unit: 'px' },
-                axis: 'horizontal'
-            },
-            centeredToTarget: false
-        }
-    ]
-}
-```
-
----
-
-## Rule 7: Global Cursor Follower Effects with Named Effects
-
-**Use Case**: Page-wide cursor following elements that respond to mouse movement anywhere (e.g., custom cursors, global decorative followers, interactive overlays)
-
-**When to Apply**:
-
-- For custom cursor implementations
-- When creating global interactive overlays
-- For page-wide decorative followers
-- When building immersive cursor experiences
-
-**Pattern**:
-
-```typescript
-{
-    key: '[FOLLOWER_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'root'
-    },
-    effects: [
-        {
-            namedEffect: {
-                type: '[FOLLOWER_EFFECT_TYPE]',
-                distance: { value: [FOLLOWER_DISTANCE], unit: '[DISTANCE_UNIT]' },
-                [FOLLOWER_PROPERTIES]
-            },
-            centeredToTarget: false,
-            effectId: '[FOLLOWER_EFFECT_ID]'
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[FOLLOWER_KEY]`: Unique identifier for cursor follower element
-- `[FOLLOWER_EFFECT_TYPE]`: 'TrackMouse', 'AiryMouse', 'BounceMouse'
-- `[FOLLOWER_DISTANCE]`: Distance/lag for follower (0 for perfect following)
-- `[FOLLOWER_PROPERTIES]`: Additional effect properties
-- `[FOLLOWER_EFFECT_ID]`: Unique identifier for the follower effect
-- Other variables same as previous rules
-
-**Example - Custom Cursor Follower**:
-
-```typescript
-{
-    key: 'custom-cursor',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'root'
-    },
-    effects: [
-        {
-            namedEffect: {
-                type: 'TrackMouse',
-                distance: { value: 0, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: false,
-            effectId: 'global-cursor'
-        }
-    ]
-}
-```
-
-**Example - Floating Decoration Follower**:
-
-```typescript
-{
-    key: 'floating-decoration',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'root'
-    },
-    effects: [
-        {
-            namedEffect: {
-                type: 'AiryMouse',
-                distance: { value: 50, unit: 'px' },
-                axis: 'both'
-            },
-            centeredToTarget: false,
-            effectId: 'decoration-follower'
-        }
-    ]
-}
-```
-
----
-
-## Rule 8: Custom Pointer Effects with customEffect
-
-**Use Case**: When you need full control over pointer-driven animations that cannot be achieved with named effects, such as custom physics, complex multi-property animations, or unique visual transformations.
-
-**When to Apply**:
-
-- For custom physics-based animations
-- When creating unique visual effects not covered by named effects
-- When controlling WebGL/WebGPU effects or other JavaScript controlled effects
-- For complex DOM manipulations based on mouse position
-- When implementing grid-based or particle effects
-- For animations requiring access to velocity data
-
-**IMPORTANT**: Only use `customEffect` when `namedEffect` cannot achieve the desired result. Named effects are optimized and GPU-friendly.
-
-**Pattern - Basic customEffect**:
-
-```typescript
-{
-    key: '[SOURCE_KEY]',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: '[HIT_AREA]'
-    },
-    effects: [
-        {
-            key: '[TARGET_KEY]',
-            customEffect: (element, progress) => {
-                // progress.x: 0-1 horizontal position
-                // progress.y: 0-1 vertical position
-                // progress.v: { x, y } velocity (optional)
-                // progress.active: boolean (optional)
-
-                [CUSTOM_ANIMATION_LOGIC]
-            },
-            centeredToTarget: [CENTERED_TO_TARGET]
-        }
-    ]
-}
-```
-
-**Variables**:
+---
 
-- `[SOURCE_KEY]`: Unique identifier for source element tracking mouse movement
-- `[TARGET_KEY]`: Unique identifier for target element to animate
-- `[HIT_AREA]`: 'self' or 'root'
-- `[CUSTOM_ANIMATION_LOGIC]`: Your custom animation code using the progress object
-- `[CENTERED_TO_TARGET]`: true or false
+## PointerMoveParams
 
-**Example - Custom Rotation Based on Mouse Position**:
+`params` object for `pointerMove` interactions:
 
 ```typescript
-{
-    key: 'rotation-container',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            customEffect: (element, progress) => {
-                // Convert progress to angle (0-360 degrees)
-                const angle = Math.atan2(
-                    progress.y - 0.5,
-                    progress.x - 0.5
-                ) * (180 / Math.PI);
-
-                element.style.transform = `rotate(${angle}deg)`;
-            },
-            centeredToTarget: true
-        }
-    ]
-}
+type PointerMoveParams = {
+  hitArea?: 'root' | 'self';
+  axis?: 'x' | 'y';
+};
 ```
 
-**Example - Magnetic Effect with Distance Calculation**:
+### Properties
 
-```typescript
-{
-    key: 'magnetic-button',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            customEffect: (element, progress) => {
-                // Calculate distance from center (0.5, 0.5)
-                const dx = (progress.x - 0.5) * 2; // -1 to 1
-                const dy = (progress.y - 0.5) * 2; // -1 to 1
+- `hitArea` — determines where mouse movement is tracked:
+  - `'self'` — tracks pointer within the source element's bounds only. Use for local pointer-tracking effects on a specific element.
+  - `'root'` — tracks pointer anywhere in the viewport. Use for global cursor followers, ambient effects.
+- `axis` — restricts pointer tracking to a single axis. Used with `keyframeEffect` to map one axis to 0–1 progress; ignored by `namedEffect` and `customEffect` which receive the full 2D progress:
+  - `'x'` — maps horizontal pointer position to 0–1 progress for keyframe interpolation.
+  - `'y'` — maps vertical pointer position to 0–1 progress for keyframe interpolation. **Default** when `keyframeEffect` is used.
+  - For `namedEffect` or `customEffect` both axes are available via the 2D progress object, and will be ignored.
 
-                // Apply magnetic pull effect
-                const maxMove = 20; // pixels
-                const moveX = dx * maxMove;
-                const moveY = dy * maxMove;
+---
 
-                element.style.transform = `translate(${moveX}px, ${moveY}px)`;
-            },
-            centeredToTarget: true
-        }
-    ]
-}
-```
+## Progress Object Structure
 
-**Example - Velocity-Based Motion Blur**:
+When using `customEffect` with `pointerMove`, the progress parameter is an object:
 
 ```typescript
-{
-    key: 'velocity-element',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'root'
-    },
-    effects: [
-        {
-            customEffect: (element, progress) => {
-                // Use velocity for motion blur intensity
-                const velocity = progress.v || { x: 0, y: 0 };
-                const speed = Math.sqrt(velocity.x ** 2 + velocity.y ** 2);
-
-                // Apply blur based on speed
-                const blurAmount = Math.min(speed * 0.5, 10);
-                element.style.filter = `blur(${blurAmount}px)`;
-
-                // Move element towards mouse
-                const offsetX = (progress.x - 0.5) * 100;
-                const offsetY = (progress.y - 0.5) * 100;
-                element.style.transform = `translate(${offsetX}px, ${offsetY}px)`;
-            },
-            centeredToTarget: false
-        }
-    ]
-}
+type Progress = {
+  x: number; // 0-1: horizontal position (0 = left edge, 1 = right edge)
+  y: number; // 0-1: vertical position (0 = top edge, 1 = bottom edge)
+  v?: {
+    x: number; // Horizontal velocity: negative = moving left, positive = moving right. Magnitude reflects speed.
+    y: number; // Vertical velocity: negative = moving up, positive = moving down. Magnitude reflects speed.
+  };
+  active?: boolean; // Whether mouse is currently in the hit area
+};
 ```
 
-**Example - Grid Cell Rotation Effect**:
-
-```typescript
-// First, cache grid cell positions for performance
-const cellCache = new Map();
-// Cache viewport size
-const windowWidth = window.innerWidth;
-const windowHeight = window.innerHeight;
-// ... populate cache with cell center positions
-// ... update `windowWidth/height` on window `resize` event
+---
 
-{
-    key: 'interactive-grid',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'root'
-    },
-    effects: [
-        {
-            customEffect: (element, progress) => {
-                // Convert progress to viewport coordinates
-                const mouseX = progress.x * windowWidth;
-                const mouseY = progress.y * windowHeight;
+## Centering with `centeredToTarget`
 
-                // Iterate through cached grid cells
-                for (const [cell, cache] of cellCache) {
-                    const deltaX = mouseX - cache.x;
-                    const deltaY = mouseY - cache.y;
+Controls which element's bounds define the 0–1 progress range.
 
-                    // Calculate angle pointing towards mouse
-                    const angle = Math.atan2(deltaY, deltaX) * (180 / Math.PI) + 90;
+- **`false` (default)**: Progress is calculated against the **source element's** (or viewport's) bounds. The `50%` progress of the timeline is at the center of the source element.
+- **`true`**: `50%` progress of the timeline is calculated against the **target element's center**. The edges of the timeline are still calculated against the edges of the source element/viewport depending on `hitAea`.
 
-                    // Calculate distance-based intensity
-                    const dist = Math.sqrt(deltaX ** 2 + deltaY ** 2);
-                    const intensity = Math.max(0, 1 - dist / 500);
+---
 
-                    cell.style.transform = `rotate(${angle}deg) scale(${1 + intensity * 0.2})`;
-                }
-            },
-            centeredToTarget: false
-        }
-    ]
-}
-```
+## Device Conditions
 
-**Example - Active State Handling**:
+`pointerMove` works best on hover-capable devices. Use a `conditions` entry with a `(hover: hover)` media query to prevent the interaction from registering on touch-only devices. On touch-only devices, consider a fallback to `viewEnter` or `viewProgress` based interactions:
 
 ```typescript
 {
-    key: 'active-aware-element',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
+    conditions: {
+        '[CONDITION_NAME]': { type: 'media', predicate: '(hover: hover)' }
     },
-    effects: [
+    interactions: [
         {
-            customEffect: (element, progress) => {
-                if (!progress.active) {
-                    // Mouse left the hit area - reset or animate out
-                    element.style.transform = 'scale(1)';
-                    element.style.opacity = '0.7';
-                    return;
-                }
-
-                // Mouse is active in hit area
-                const scale = 1 + (1 - Math.abs(progress.x - 0.5) * 2) * 0.1;
-                element.style.transform = `scale(${scale})`;
-                element.style.opacity = '1';
-            },
-            centeredToTarget: true
+            key: '[SOURCE_KEY]',
+            trigger: 'pointerMove',
+            conditions: ['[CONDITION_NAME]'],
+            params: { hitArea: '[HIT_AREA]' },
+            effects: [ /* ... */ ]
         }
     ]
 }
 ```
 
-### customEffect with Transition Smoothing
-
-For smoother animations, you can use `transitionDuration` and `transitionEasing`:
-
-```typescript
-{
-    key: 'smooth-custom',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            customEffect: (element, progress) => {
-                const x = (progress.x - 0.5) * 50;
-                const y = (progress.y - 0.5) * 50;
-                element.style.transform = `translate(${x}px, ${y}px)`;
-            },
-            transitionDuration: 100,
-            transitionEasing: 'easeOut',
-            centeredToTarget: true
-        }
-    ]
-}
-```
+For devices with dynamic viewport sizes (e.g. mobile browsers where the address bar collapses), consider using viewport-relative units carefully and prefer `lvh`/`svh` over `dvh` unless dynamic viewport behavior is specifically desired.
 
 ---
 
-## Rule 9: Multi-Element Custom Parallax with customEffect
-
-**Use Case**: Complex parallax effects with custom physics or non-standard transformations across multiple layers.
+## Rule 1: namedEffect
 
-**When to Apply**:
+Use pre-built mouse presets from `@wix/motion-presets` that handle 2D mouse tracking internally. Mouse presets are preferred over `keyframeEffect` for 2D effects.
 
-- For parallax with custom easing or physics
-- When layers need different calculation methods
-- For effects combining multiple CSS properties
-
-**Pattern**:
+**Multiple effects:** The `effects` array can contain multiple effects — all share the same pointer tracking and fire together. Use this to animate different targets from the same pointer movement.
 
 ```typescript
 {
-    key: '[CONTAINER_KEY]',
+    key: '[SOURCE_KEY]',
     trigger: 'pointerMove',
     params: {
         hitArea: '[HIT_AREA]'
     },
     effects: [
         {
-            key: '[LAYER_1_KEY]',
-            customEffect: (element, progress) => {
-                [LAYER_1_CUSTOM_LOGIC]
+            key: '[TARGET_KEY]',
+            namedEffect: {
+                type: '[NAMED_EFFECT_TYPE]',
+                [EFFECT_PROPERTIES]
             },
-            centeredToTarget: true
+            centeredToTarget: [CENTERED_TO_TARGET],
+            transitionDuration: [TRANSITION_DURATION_MS],
+            transitionEasing: '[TRANSITION_EASING]'
         },
-        {
-            key: '[LAYER_2_KEY]',
-            customEffect: (element, progress) => {
-                [LAYER_2_CUSTOM_LOGIC]
-            },
-            centeredToTarget: true
-        }
+        // additional effects targeting other elements can be added here
     ]
 }
 ```
 
-**Example - Depth-Based Custom Parallax**:
+### Variables
 
-```typescript
-{
-    key: 'parallax-scene',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'bg-stars',
-            customEffect: (element, progress) => {
-                // Background: subtle movement, inverted direction
-                const x = (0.5 - progress.x) * 10;
-                const y = (0.5 - progress.y) * 10;
-                element.style.transform = `translate(${x}px, ${y}px)`;
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'mid-clouds',
-            customEffect: (element, progress) => {
-                // Midground: moderate movement with rotation
-                const x = (progress.x - 0.5) * 30;
-                const y = (progress.y - 0.5) * 20;
-                const rotation = (progress.x - 0.5) * 5;
-                element.style.transform = `translate(${x}px, ${y}px) rotate(${rotation}deg)`;
-            },
-            centeredToTarget: true
-        },
-        {
-            key: 'fg-elements',
-            customEffect: (element, progress) => {
-                // Foreground: strong movement with scale
-                const x = (progress.x - 0.5) * 60;
-                const y = (progress.y - 0.5) * 40;
-                const scale = 1 + Math.abs(progress.x - 0.5) * 0.1;
-                element.style.transform = `translate(${x}px, ${y}px) scale(${scale})`;
-            },
-            centeredToTarget: true
-        }
-    ]
-}
-```
+- `[SOURCE_KEY]` — identifier matching the element's key (`data-interact-key` for web, `interactKey` for React). The element that tracks pointer movement.
+- `[TARGET_KEY]` — identifier matching the element's key on the element to animate (can be same as source or different).
+- `[HIT_AREA]` — `'self'` (track pointer within source element) or `'root'` (track pointer anywhere in viewport).
+- `[NAMED_EFFECT_TYPE]` — a registered effect name, or a preset from `@wix/motion-presets` `mouse` library.
+- `[EFFECT_PROPERTIES]` — preset-specific options. Refer to motion-presets rules for each preset's available options and their value types. Do NOT guess preset option names or types; omit unknown options and rely on defaults.
+- `[CENTERED_TO_TARGET]` — `true` or `false`. See **Centering with `centeredToTarget`** above.
+- `[TRANSITION_DURATION_MS]` — optional number. Milliseconds for smoothing (interpolating) between progress updates. The animation does not jump to the new progress value instantly; instead it transitions over this duration. Use to add inertia/lag to the effect, making it feel more physical (e.g. `200`–`600`).
+- `[TRANSITION_EASING]` — optional string. CSS easing or named easing from `@wix/motion`. Adds a natural deceleration feel when used with `transitionDuration`.
 
 ---
 
-## Rule 10: KeyframeEffect with Axis Mapping
-
-**Use Case**: When you want to use standard keyframe animations driven by pointer movement along a single axis (e.g., horizontal sliders, vertical progress indicators, single-axis parallax effects)
-
-**When to Apply**:
-
-- For slider-like interactions driven by horizontal mouse position
-- For vertical scroll-like effects driven by vertical mouse position
-- When you have existing keyframe animations you want to control with pointer movement
-- For simple linear interpolation effects along one axis
+## Rule 2: keyframeEffect with Single Axis
 
-**Pattern**:
+Use `keyframeEffect` when the pointer position along a single axis should drive a keyframe animation. The pointer's position on the chosen axis is mapped to linear 0–1 progress.
 
 ```typescript
 {
@@ -1076,457 +150,130 @@ For smoother animations, you can use `transitionDuration` and `transitionEasing`
     trigger: 'pointerMove',
     params: {
         hitArea: '[HIT_AREA]',
-        axis: '[AXIS]'  // 'x' or 'y'
+        axis: '[AXIS]'
     },
     effects: [
         {
             key: '[TARGET_KEY]',
             keyframeEffect: {
-                name: '[ANIMATION_NAME]',
-                keyframes: [
-                    { [PROPERTY]: '[START_VALUE]' },
-                    { [PROPERTY]: '[END_VALUE]' }
-                ]
-            },
-            fill: '[FILL_MODE]',
-            centeredToTarget: [CENTERED_TO_TARGET]
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[SOURCE_KEY]`: Unique identifier for source element tracking mouse movement
-- `[TARGET_KEY]`: Unique identifier for target element to animate
-- `[HIT_AREA]`: 'self' or 'root'
-- `[AXIS]`: 'x' (maps x position) or 'y' (maps y position) - **defaults to 'y'** (in `params`)
-- `[ANIMATION_NAME]`: Name for the keyframe animation
-- `[PROPERTY]`: CSS property to animate (transform, opacity, etc.)
-- `[START_VALUE]`: Value at progress 0 (left/top edge)
-- `[END_VALUE]`: Value at progress 1 (right/bottom edge)
-- `[FILL_MODE]`: 'none', 'forwards', 'backwards', 'both'
-- `[CENTERED_TO_TARGET]`: true or false
-
-**Example - Horizontal Slider with Multiple Targets**:
-
-This example shows a pointer-driven slider where the X position controls both a sliding element and an indicator's opacity/scale.
-
-```typescript
-{
-    interactions: [
-        {
-            key: 'pointer-container',
-            trigger: 'pointerMove',
-            params: { hitArea: 'self', axis: 'x' },
-            effects: [
-                {
-                    key: 'pointer-slider',
-                    effectId: 'slide-effect',
-                },
-                {
-                    key: 'pointer-indicator',
-                    effectId: 'indicator-effect',
-                },
-            ],
-        },
-    ],
-    effects: {
-        'slide-effect': {
-            keyframeEffect: {
-                name: 'slide-x',
-                keyframes: [
-                    { transform: 'translateX(0px)' },
-                    { transform: 'translateX(220px)' },
-                ],
-            },
-            fill: 'both',
-        },
-        'indicator-effect': {
-            keyframeEffect: {
-                name: 'indicator-fade-scale',
-                keyframes: [
-                    { opacity: '0.3', transform: 'scale(0.8)' },
-                    { opacity: '1', transform: 'scale(1)' },
-                ],
+                name: '[EFFECT_NAME]',
+                keyframes: [KEYFRAMES]
             },
             fill: 'both',
+            centeredToTarget: [CENTERED_TO_TARGET],
+            transitionDuration: [TRANSITION_DURATION_MS],
+            transitionEasing: '[TRANSITION_EASING]',
+            effectId: '[UNIQUE_EFFECT_ID]'
         },
-    },
+        // additional effects targeting other elements can be added here
+    ]
 }
 ```
 
-**Important Notes**:
+### Variables
 
-- `axis` defaults to `'y'` when using `keyframeEffect` with `pointerMove`
-- For 2D effects that need both axes, you can use composite animations (Rule 11), `namedEffect`, or `customEffect`
+- `[SOURCE_KEY]` / `[TARGET_KEY]` — same as Rule 1.
+- `[HIT_AREA]` — `'self'` or `'root'`.
+- `[AXIS]` — `'x'` (horizontal) or `'y'` (vertical). Defaults to `'y'` when omitted.
+- `[EFFECT_NAME]` — unique string name for the keyframe effect.
+- `[KEYFRAMES]` — array of CSS keyframe objects (e.g. `[{ transform: 'rotate(-10deg)' }, { transform: 'rotate(0)' }, { transform: 'rotate(10deg)' }]`). Distributed evenly across 0–1 progress: first keyframe = progress 0 (left/top edge), last = progress 1 (right/bottom edge). Any number of keyframes is allowed.
+- `[CENTERED_TO_TARGET]` — optional. `true` or `false`. See **Centering with `centeredToTarget`** above. Defaults to `false`.
+- `[TRANSITION_DURATION_MS]` — optional. Milliseconds for smoothing between progress updates. See Rule 1 for details.
+- `[TRANSITION_EASING]` — optional. CSS easing string or named easing from `@wix/motion`. See Rule 1 for supported values.
+- `[UNIQUE_EFFECT_ID]` — optional string identifier.
 
 ---
 
-## Rule 11: Multi-Axis KeyframeEffect (X + Y)
-
-**Use Case**: Independent X/Y axis control using two `keyframeEffect` animations on the same target.
+## Rule 3: Two keyframeEffects with Two Axes and `composite`
 
-**Pattern**:
-Define two interactions on the same source/target pair—one for `axis: 'x'`, one for `axis: 'y'`. When animating the same CSS property (e.g. `transform`), use the `composite` option to combine the effects.
-
-**Example - 2D Scale Control**:
-
-X axis controls `scaleX`, Y axis controls `scaleY`.
+Use two separate interactions on the same source/target pair — one for `axis: 'x'`, one for `axis: 'y'` — for independent 2D control with keyframes. When both effects animate the same CSS property (e.g. `transform` or `filter`), use `composite` to combine them.
 
 ```typescript
 {
     interactions: [
         {
-            key: 'composite-add-container',
+            key: '[SOURCE_KEY]',
             trigger: 'pointerMove',
-            params: { hitArea: 'self', axis: 'x' },
-            effects: [
-                {
-                    key: 'composite-add-ball',
-                    effectId: 'scale-x-effect',
-                },
-            ],
+            params: { hitArea: '[HIT_AREA]', axis: 'x' },
+            effects: [{ key: '[TARGET_KEY]', effectId: '[X_EFFECT_ID]' }]
         },
         {
-            key: 'composite-add-container',
+            key: '[SOURCE_KEY]',
             trigger: 'pointerMove',
-            params: { hitArea: 'self', axis: 'y' },
-            effects: [
-                {
-                    key: 'composite-add-ball',
-                    effectId: 'scale-y-effect',
-                },
-            ],
-        },
+            params: { hitArea: '[HIT_AREA]', axis: 'y' },
+            effects: [{ key: '[TARGET_KEY]', effectId: '[Y_EFFECT_ID]' }]
+        }
     ],
     effects: {
-        'scale-x-effect': {
+        '[X_EFFECT_ID]': {
             keyframeEffect: {
-                name: 'scale-x',
-                keyframes: [
-                    { transform: 'scaleX(0.5)' },
-                    { transform: 'scaleX(1.5)' },
-                ],
+                name: '[X_EFFECT_NAME]',
+                keyframes: [X_KEYFRAMES]
             },
-            fill: 'both',
-            composite: 'add',
+            fill: '[FILL_MODE]', // usually 'both'
+            composite: '[COMPOSITE_OPERATION]',
+            transitionDuration: [TRANSITION_DURATION_MS],
+            transitionEasing: '[TRANSITION_EASING]'
         },
-        'scale-y-effect': {
+        '[Y_EFFECT_ID]': {
             keyframeEffect: {
-                name: 'scale-y',
-                keyframes: [
-                    { transform: 'scaleY(0.5)' },
-                    { transform: 'scaleY(1.5)' },
-                ],
+                name: '[Y_EFFECT_NAME]',
+                keyframes: [Y_KEYFRAMES]
             },
-            fill: 'both',
-            composite: 'add',
-        },
-    },
-}
-```
-
----
-
-## Advanced Patterns and Combinations
-
-### Responsive Pointer Effects
-
-`pointerMove` only fires on pointer-capable devices, but touch users still visit the page. Use the `conditions` config map to define device/motion guards — condition IDs are arbitrary strings you define, matched against the media query predicates you provide.
-
-```typescript
-{
-    conditions: {
-        // Only run pointer effects on devices that support hover (non-touch)
-        'supports-hover': { type: 'media', predicate: '(hover: hover)' },
-        // Suppress animations for users who prefer reduced motion
-        'prefers-motion': { type: 'media', predicate: '(prefers-reduced-motion: no-preference)' },
-    },
-    interactions: [
-        {
-            key: 'responsive-element',
-            trigger: 'pointerMove',
-            conditions: ['supports-hover', 'prefers-motion'],
-            params: { hitArea: 'self' },
-            effects: [
-                {
-                    key: 'responsive-element',
-                    namedEffect: { type: 'Tilt3DMouse', angle: 20, perspective: 800 },
-                    centeredToTarget: true
-                }
-            ]
+            fill: '[FILL_MODE]', // usually 'both'
+            composite: '[COMPOSITE_OPERATION]',
+            transitionDuration: [TRANSITION_DURATION_MS],
+            transitionEasing: '[TRANSITION_EASING]'
         }
-    ]
+    }
 }
 ```
 
-### Contextual Hit Areas
+### Variables
 
-Different hit areas for different interaction contexts:
+- `[SOURCE_KEY]` / `[TARGET_KEY]` — same as Rule 1.
+- `[HIT_AREA]` — `'self'` or `'root'`.
+- `[X_EFFECT_ID]` / `[Y_EFFECT_ID]` — unique string identifiers for the X-axis and Y-axis effects. Required — they map to keys in the top-level `effects` map.
+- `[X_EFFECT_NAME]` / `[Y_EFFECT_NAME]` — unique string names for each keyframe effect.
+- `[X_KEYFRAMES]` / `[Y_KEYFRAMES]` — arrays of WAAPI keyframe objects for the X-axis and Y-axis effects respectively. Each effect can vary in propertise and keyframes.
+- `[COMPOSITE_OPERATION]` — `'add'` or `'accumulate'`. Required when both effects animate `transform` and/or both animate `filter`, so their values combine rather than override. `'add'`: composited transform functions are appended. `'accumulate'`: matching function arguments are summed.
+- `[FILL_MODE]` — typically `'both'` to ensure the effect keeps applying after exiting the effect's active range.
+- `[TRANSITION_DURATION_MS]` — optional. Milliseconds for smoothing between progress updates. See Rule 1 for details.
+- `[TRANSITION_EASING]` — optional. CSS easing function for the smoothing transition. See Rule 1 for supported values.
 
-```typescript
-// Local interaction - mouse must be over element
-{
-    key: 'local-card',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'self'
-    },
-    effects: [
-        {
-            key: 'local-card',
-            namedEffect: {
-                type: 'Tilt3DMouse',
-                angle: 15
-            },
-            centeredToTarget: true
-        }
-    ]
-},
-// Global interaction - responds to mouse anywhere
-{
-    key: 'global-background',
-    trigger: 'pointerMove',
-    params: {
-        hitArea: 'root'
-    },
-    effects: [
-        {
-            key: 'ambient-element',
-            namedEffect: {
-                type: 'AiryMouse',
-                distance: { value: 30, unit: 'px' }
-            },
-            centeredToTarget: false
-        }
-    ]
-}
-```
+---
 
-### Axis-Constrained Effects
+## Rule 4: customEffect
 
-Controlling movement direction for specific design needs:
+Use `customEffect` when you need full imperative control over pointer-driven animations — custom physics, complex multi-property animations, velocity-reactive effects, or controlling WebGL/WebGPU and other JavaScript-driven effects. The callback receives the 2D progress object (see **Progress Object Structure**).
 
 ```typescript
 {
-    key: 'constrained-container',
+    key: '[SOURCE_KEY]',
     trigger: 'pointerMove',
     params: {
-        hitArea: 'self'
+        hitArea: '[HIT_AREA]'
     },
     effects: [
         {
-            key: 'horizontal-slider',
-            namedEffect: {
-                type: 'TrackMouse',
-                distance: { value: 100, unit: 'px' },
-                axis: 'horizontal'
+            key: '[TARGET_KEY]',
+            customEffect: (element: Element, progress: Progress) => {
+                [CUSTOM_ANIMATION_LOGIC]
             },
-            centeredToTarget: true
+            centeredToTarget: [CENTERED_TO_TARGET],
+            transitionDuration: [TRANSITION_DURATION_MS],
+            transitionEasing: '[TRANSITION_EASING]'
         },
-        {
-            key: 'vertical-indicator',
-            namedEffect: {
-                type: 'ScaleMouse',
-                scale: 1.2,
-                distance: { value: 150, unit: 'px' },
-                axis: 'vertical'
-            },
-            centeredToTarget: true
-        }
+        // additional effects targeting other elements can be added here
     ]
 }
 ```
 
----
-
-## Best Practices for PointerMove Interactions
-
-### Effect Type Selection Guidelines
-
-**When to use `namedEffect` (Preferred)**:
-
-1. For standard mouse-tracking effects (tilt, track, scale, blur)
-2. When GPU-optimized performance is critical
-3. For effects that match preset behavior (3D tilt, elastic following)
-4. When you don't need custom physics or calculations
-
-**When to use `customEffect`**:
-
-1. For custom physics-based animations (springs, gravity)
-2. When you need access to velocity data (`progress.v`)
-3. For complex DOM manipulations (updating multiple elements)
-4. When creating effects not covered by named presets
-5. For grid/particle systems with many elements
-6. For controlling WebGL/WebGPU effects
-
-**When to use `keyframeEffect`**:
-
-1. When you want single-axis control using the `axis` parameter ('x' or 'y')
-2. For slider-like interactions driven by pointer position along one axis
-3. For 2D control, use two `keyframeEffect` interactions with `composite` (see Rule 11)
-
-### Performance Guidelines
-
-1. **Limit simultaneous pointer effects** - too many can cause performance issues
-2. **Test on various devices** - pointer sensitivity varies across hardware
-3. **Cache DOM queries outside `customEffect` callbacks** - avoid repeated `querySelector` calls inside the callback
-4. **Use `requestAnimationFrame` sparingly** - the library already handles frame timing
-5. **Prefer `namedEffect` over `customEffect`** - named effects are optimized for GPU acceleration
-
-### Hit Area Guidelines
-
-1. **Use `hitArea: 'self'`** for local element interactions (cards, buttons, hover effects)
-2. **Use `hitArea: 'root'`** for global cursor followers and ambient effects
-3. **Consider container boundaries** when choosing hit areas
-4. **Test hit area responsiveness** across different screen sizes
-5. **`'self'`** is more performant than `'root'` - use when possible
-
-### Centering Guidelines
-
-1. **Set `centeredToTarget: true`** when target differs from source (e.g., animating child element from parent)
-2. **Use `centeredToTarget: false`** for cursor followers and global effects
-3. **Test centering behavior** with different element sizes
-4. **Consider responsive design** when setting centering
-5. **Centering affects how progress.x/y map to element position**
-
-### Common Use Cases by Pattern
-
-**Single Element 3D Effects (Rule 1)** - `namedEffect`:
-
-- Interactive product cards
-- 3D showcase elements
-- Immersive button interactions
-- Portfolio item presentations
-
-**Movement Followers (Rule 2)** - `namedEffect`:
-
-- Cursor follower elements
-- Floating decorative elements
-- Responsive UI indicators
-- Interactive overlays
-
-**Scale & Deformation (Rule 3)** - `namedEffect`:
-
-- Organic interface elements
-- Interactive morphing shapes
-- Creative scaling buttons
-- Blob-like interactions
-
-**Visual Effects (Rule 4)** - `namedEffect`:
-
-- Creative interface elements
-- Motion blur interactions
-- Spinning decorative elements
-- Dynamic visual feedback
-
-**Multi-Element Parallax (Rule 5)** - `namedEffect`:
-
-- Layered background effects
-- Depth-based interactions
-- Immersive hero sections
-- Complex scene responses
-
-**Group Coordination (Rule 6)** - `namedEffect`:
-
-- Interactive card grids
-- Navigation menu systems
-- Gallery hover effects
-- Coordinated UI responses
-
-**Global Followers (Rule 7)** - `namedEffect`:
-
-- Custom cursor implementations
-- Page-wide decorative elements
-- Global interactive overlays
-- Immersive cursor experiences
-
-**Custom Pointer Effects (Rule 8)** - `customEffect`:
-
-- Grid-based rotation systems
-- Magnetic pull/push effects
-- Physics-based animations
-- Velocity-reactive effects
-- Complex DOM manipulations
-- Particle systems
-
-**Multi-Element Custom Parallax (Rule 9)** - `customEffect`:
-
-- Non-linear parallax physics
-- Layers with different calculation methods
-- Combined transform effects per layer
-- Custom easing per element
-
-**Single-Axis Keyframe Control (Rule 10)** - `keyframeEffect`:
-
-- Horizontal slider interactions
-- Vertical progress indicators
-- Single-axis reveal effects
-- Linear interpolation along one axis
-
-**Composite Keyframe (Rule 11)** - Two `keyframeEffect` + `composite`:
-
-- 2D element positioning with pointer
-- Combined X/Y transform animations
-- Independent axis control with keyframes
-- Declarative 2D animations without customEffect
-
-### Troubleshooting Common Issues
-
-**Poor pointer responsiveness**:
-
-- Verify `hitArea` configuration
-- Test `centeredToTarget` settings
-- Ensure target elements are properly positioned
-
-**Performance issues**:
-
-- Reduce number of simultaneous effects
-- Use simpler named effects
-- Check for CSS conflicts
-- Test on lower-end devices
-- In customEffect: cache DOM queries outside the callback
-- Avoid creating objects inside customEffect callbacks
-
-**customEffect not updating smoothly**:
-
-- Add `transitionDuration` and `transitionEasing` for smoother transitions
-- Avoid expensive calculations inside the callback
-- Consider debouncing complex logic
-
-**customEffect progress values unexpected**:
-
-- Remember x/y are 0-1 normalized (not pixel values)
-- Check `centeredToTarget` setting affects coordinate mapping
-- Verify `hitArea` matches expected tracking area
-- Use `progress.active` to handle edge cases
-
-**Unexpected behavior on touch devices**:
-
-- Implement appropriate conditions for touch vs. mouse
-- Provide touch-friendly alternatives
-- Test pointer events on mobile devices
-- Consider disabling complex effects on touch
-
-**Effects not triggering**:
-
-- Verify source element exists and is visible
-- Check `data-interact-key` matches CSS selector
-- Ensure proper hit area configuration
-- Test mouse event propagation
-
----
-
-## Quick Reference: Effect Type Selection
+### Variables
 
-| Requirement                 | Use This                                   | Why                                                    |
-| --------------------------- | ------------------------------------------ | ------------------------------------------------------ |
-| Standard 3D tilt            | `namedEffect: { type: 'Tilt3DMouse' }`     | GPU-optimized, battle-tested                           |
-| Cursor following            | `namedEffect: { type: 'TrackMouse' }`      | Built-in physics                                       |
-| Horizontal progress control | `keyframeEffect` + `params: { axis: 'x' }` | Maps x position to keyframes                           |
-| Vertical progress control   | `keyframeEffect` + `params: { axis: 'y' }` | Maps y position to keyframes                           |
-| Multi-axis keyframe (X + Y) | Two interactions with `keyframeEffect`     | Use `composite: 'add'` or `'accumulate'` for same prop |
-| Custom physics              | `customEffect`                             | Full control over calculations                         |
-| Velocity-based effects      | `customEffect`                             | Access to `progress.v`                                 |
-| Grid/particle systems       | `customEffect`                             | Can manipulate many elements                           |
+- `[SOURCE_KEY]` / `[TARGET_KEY]` — same as Rule 1.
+- `[HIT_AREA]` — `'self'` or `'root'`.
+- `[CUSTOM_ANIMATION_LOGIC]` — JavaScript using `progress.x`, `progress.y`, `progress.v`, and `progress.active` to apply the effect. See **Progress Object Structure** above.
+- `[CENTERED_TO_TARGET]` — optional. `true` or `false`. See **Centering with `centeredToTarget`** above. Defaults to `false`.
+- `[TRANSITION_DURATION_MS]` — optional. Milliseconds for smoothing between progress updates. See Rule 1 for details.
+- `[TRANSITION_EASING]` — optional. CSS easing function for the smoothing transition. See Rule 1 for supported values.