@wix/interact 2.1.4 → 2.2.0

package/rules/full-lean.md

@@ -1,149 +1,179 @@
-### Basic usage (quick start)
+# @wix/interact — Rules
+
+Declarative configuration-driven interaction library. Binds animations to triggers via JSON config.
+
+## Table of Contents
+
+- [Common Pitfalls](#common-pitfalls)
+- [Quick Start](#quick-start)
+- [Element Binding](#element-binding)
+- [Config Structure](#config-structure)
+- [Interactions](#interactions)
+- [Triggers](#triggers)
+  - [hover / click](#hover--click)
+  - [viewEnter](#viewenter)
+  - [viewProgress](#viewprogress)
+  - [pointerMove](#pointermove)
+  - [animationEnd](#animationend)
+- [Effects](#effects)
+  - [Time-based Effect](#time-based-effect)
+  - [Scroll / Pointer-driven Effect](#scroll--pointer-driven-effect)
+  - [State Effect](#stateeffect-css-style-toggle)
+  - [Animation Payloads](#animation-payloads)
+- [Sequences](#sequences)
+- [Conditions](#conditions)
+- [FOUC Prevention](#fouc-prevention)
+- [Element Resolution](#element-resolution)
+- [Static API](#static-api)
+
+---
+
+## Common Pitfalls
+
+Each item here is CRITICAL — ignoring any of them will break animations.
+
+- **CRITICAL — `overflow: hidden` breaks `viewProgress`**: Replace with `overflow: clip` on all ancestors between source and scroll container. In Tailwind, replace `overflow-hidden` with `overflow-clip`.
+- **CRITICAL**: When using `viewEnter` trigger and source (trigger) and target (effect) elements are the **same element**, use ONLY `type: 'once'`. For all other types (`'repeat'`, `'alternate'`, `'state'`) MUST use **separate** source and target elements — animating the observed element itself can cause it to leave/re-enter the viewport, leading to rapid re-triggers or the animation never firing.
+- **CRITICAL - Hit-area shift**: When a hover effect changes the size or position of the hovered element (e.g., `transform: scale(…)`), MUST use a separate source and target elements. Otherwise the hit-area shifts, causing rapid enter/leave.
+  events and flickering. Use `selector` to target a child element, or set the effect's `key` to a different element.
+- **CRITICAL**: For `pointerMove` trigger MUST AVOID using the same element as both source and target with `hitArea: 'self'` and 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.
+- **CRITICAL — Do NOT guess preset options**: If you don't know the expected type/structure for a `namedEffect` param, omit it — rely on defaults rather than guessing.
+- **Reduced motion**: Use conditions to provide gentler alternatives (shorter durations, fewer transforms, no perpetual motion) for users who prefer reduced motion. You can also set `Interact.forceReducedMotion = matchMedia('(prefers-reduced-motion: reduce)').matches` to force a global reduced-motion behavior programmatically.
+- **Perspective**: Prefer `transform: perspective(...)` inside keyframes. Use the CSS `perspective` property only when multiple children share the same `perspective-origin`.
+
+---
+
+## Quick Start
+
+```bash
+npm install @wix/interact @wix/motion-presets
+```
 
-- Import the runtime and create it with a config defining the interactions.
-- Call `Interact.create(config)` once to initialize.
-- Create the full configuration up‑front and pass it in a single `create` call to avoid unintended overrides; subsequent calls replace the previous config.
+Create the full config up-front and pass it in a single `create` call. Subsequent calls create new `Interact` instances. When creating multiple instances, each manages its own set of interactions independently — use separate instances for isolated component scopes or lazy-loaded sections.
 
-**For web (Custom Elements):**
+**Web (Custom Elements):**
 
 ```ts
 import { Interact } from '@wix/interact/web';
-import type { InteractConfig } from '@wix/interact';
-
-const config: InteractConfig = {
-  // config-props
-};
-
-Interact.create(config);
+const instance = Interact.create(config);
 ```
 
-**For React:**
+The `config` object is an `InteractConfig` containing `interactions` (required), and optionally shared `effects`, `sequences`, and `conditions`.
+
+**React:**
 
 ```ts
 import { Interact } from '@wix/interact/react';
-import type { InteractConfig } from '@wix/interact';
+const instance = Interact.create(config);
+```
 
-const config: InteractConfig = {
-  // config-props
-};
+**Vanilla JS:**
 
-Interact.create(config);
+```ts
+import { Interact } from '@wix/interact';
+const instance = Interact.create(config);
+instance.add(element, 'hero'); // bind after element exists in DOM
+instance.remove('hero'); // unregister
 ```
 
-### Using `namedEffect` presets (`registerEffects`)
+**CDN (no build tools):**
+
+```html
+<script type="module">
+  import { Interact } from 'https://esm.sh/@wix/interact';
+  Interact.create(config);
+</script>
+```
 
-Before using `namedEffect`, you must register the presets with the `Interact` instance. Without this, `namedEffect` types will not resolve.
+**Registering presets** — MUST be called before calling `Interact.create()` with usage of `namedEffect`:
 
 ```ts
-import { Interact } from '@wix/interact/web'; // or /react
 import * as presets from '@wix/motion-presets';
-
 Interact.registerEffects(presets);
-Interact.create(config);
 ```
 
-Or register only what you need:
+Or selectively:
 
 ```ts
 import { FadeIn, ParallaxScroll } from '@wix/motion-presets';
 Interact.registerEffects({ FadeIn, ParallaxScroll });
 ```
 
-- Without Node/build tools: add a `<script type="module">` and import from the CDN.
+---
 
-```html
-<script type="module">
-  import { Interact } from 'https://esm.sh/@wix/interact';
+## Element Binding
 
-  const config = {
-    // config-props
-  };
+**CRITICAL:** Do NOT add observers/event listeners manually. The runtime binds triggers and effects via element keys.
 
-  Interact.create(config);
-</script>
+### Web: `<interact-element>`
+
+- MUST set `data-interact-key` to a unique value.
+- MUST contain at least one child element (the library targets `.firstElementChild`).
+- If an effect targets a different element, that element also needs its own `<interact-element>`.
+
+```html
+<interact-element data-interact-key="hero">
+  <section class="hero">...</section>
+</interact-element>
 ```
 
-### Preventing FOUC for entrance animations
+### React: `<Interaction>` component
 
-- Use `generate(config)` to create critical CSS that hides elements until their `viewEnter` entrance animation plays.
-- Add `data-interact-initial="true"` to the `<interact-element>` that should have its first child hidden initially.
-- Only use `data-interact-initial="true"` for `<interact-element>` with `viewEnter` trigger and `type: 'once'`, where the source and target elements are the same.
-- Do NOT use for `hover` or `click` interactions.
+- MUST set `tagName` to the replaced element's HTML tag.
+- MUST set `interactKey` to a unique string.
 
-**Usage:**
+```tsx
+import { Interaction } from '@wix/interact/react';
 
-```javascript
-import { generate } from '@wix/interact/web';
+<Interaction tagName="section" interactKey="hero" className="hero">
+  ...
+</Interaction>;
+```
 
-const config = {
-  /*...*/
-};
+---
 
-// Generate CSS at build time or on server
-const css = generate(config);
+## Config Structure
 
-// Include in your HTML template
-const html = `
-<!DOCTYPE html>
-<html>
-<head>
-    <style>${css}</style>
-</head>
-<body>
-    <interact-element data-interact-key="hero" data-interact-initial="true">
-        <section class="hero">
-            <h1>Welcome to Our Site</h1>
-            <p>This content fades in smoothly without flash</p>
-        </section>
-    </interact-element>
-    <script type="module" src="./main.js"></script>
-</body>
-</html>
-`;
+```ts
+type InteractConfig = {
+  interactions: Interaction[]; // REQUIRED
+  effects?: Record<string, Effect>; // reusable effects referenced by effectId
+  sequences?: Record<string, SequenceConfig>; // reusable sequences by sequenceId
+  conditions?: Record<string, Condition>; // named conditions; keys are condition ids
+};
 ```
 
-### General guidelines (avoiding common pitfalls)
+All cross-references (by id) MUST point to existing entries. Element keys MUST be stable for the config's lifetime.
 
-- Missing required fields or invalid references SHOULD be treated as no-ops for the offending interaction/effect while leaving the rest of the config functional.
-- Params with incorrect types or shapes (especially for `namedEffect` preset options) can produce console errors. If you do not know the expected type/structure for a param, omit it and rely on defaults rather than guessing.
-- Using `overflow: hidden` or `overflow: auto` can break viewProgress animations. Prefer `overflow: clip` for clipping semantics while preserving normal ViewTimeline.
-- When animating with perspective, prefer `transform: perspective(...)` inside keyframes/presets. Reserve the static CSS `perspective` property for the specific case where multiple children of the same container must share the same viewpoint (`perspective-origin`).
-- Stacking contexts and `viewProgress` (ViewTimeline): Creating a new stacking context on the target or any of its ancestors can prevent or freeze ViewTimeline sampling in some engines and setups. Avoid stacking‑context‑creating styles on the observed subtree (target and ancestors), including `transform`, `filter`, `perspective`, `opacity < 1`, `mix-blend-mode`, `isolation: isolate`, aggressive `will-change`, and `contain: paint/layout/size`. If needed for visuals, wrap the content and apply these styles to an inner child so the element that owns the timeline remains “flat”. Also avoid turning the scroll container into a stacking context; if you need clipping, prefer `overflow: clip` and avoid `transform` on the container. Typical symptoms are `viewProgress` not running, jumping 0→1, or never reaching anchors—remove or relocate the offending styles.
+---
 
-### InteractConfig – Rules for authoring interactions (AI-agent oriented)
+## Interactions
 
-This configuration declares what user/system triggers occur on which source element(s), and which visual effects should be applied to which target element(s). It is composed of three top-level sections: `effects`, `conditions`, and `interactions`.
+Each interaction maps a source element + trigger to one or more effects.
 
-### Global rules
+**Multiple effects per interaction:** A single interaction can contain multiple effects in its `effects` array. All effects in the same interaction share the same trigger — they all fire together when the trigger activates. Use this to apply different animations to different targets from the same trigger event, rather than creating separate interactions with duplicate trigger configs.
 
-- **Required/Optional**: You MUST provide an `interactions` array. You SHOULD provide an `effects` registry when you want to reference reusable effects by id. `conditions` and `sequences` are OPTIONAL.
-- **Cross-references**: All cross-references (by id) MUST point to existing entries (e.g., an `EffectRef.effectId` MUST exist in `effects`).
-- **Element keys**: All element keys (`key` fields) refer to the element path string (e.g., the value used in `data-interact-key`) and MUST be stable for the lifetime of the configuration.
-- **List context**: Where both a list container and list item selector are provided, they MUST describe the same list context across an interaction and its effects. Mismatched list contexts will be ignored by the system.
-- **Conditions**: Conditions act as guards. If any condition on an interaction or effect evaluates to false, the corresponding trigger/effect WILL NOT be applied.
-- **Element binding**: Do NOT add observers/listeners manually. For web, wrap the DOM subtree with `<interact-element>` and set `data-interact-key` to the element key. For React, use the `<Interaction>` component with `interactKey` prop. Use the same key in your config (`Interaction.key`/`Effect.key`). The runtime binds triggers/effects via this attribute.
+```ts
+{
+  key: string;                   // REQUIRED — matches data-interact-key / interactKey - the root element
+  trigger: TriggerType;          // REQUIRED
+  params?: TriggerParams;        // trigger-specific options
+  effects?: (Effect | EffectRef)[]; // possible to add multiple effects for same trigger
+  sequences?: (SequenceConfig | SequenceConfigRef)[]; // possible to add multiple sequences for same trigger
+  conditions?: string[];         // ids referencing the top-level conditions map; all must pass
+  selector?: string;             // optional - CSS selector to refine source element selection within the root element
+  listContainer?: string;        // optional — CSS selector for list container
+  listItemSelector?: string;     // optional — CSS selector to filter which children of listContainer are observed as sources
+}
+```
 
-### Structure
+At least one of `effects` or `sequences` MUST be provided.
 
-- **effects: Record<string, Effect>**
-  - **Purpose**: A registry of reusable, named effect definitions that can be referenced from interactions via `EffectRef`.
-  - **Key (string)**: The effect id. MUST be unique across the registry.
-  - **Value (Effect)**: A full effect definition. See Effect rules below.
+For most use cases, `key` alone is sufficient for both source and target resolution. The `selector`, `listContainer`, and `listItemSelector` fields are only needed for advanced patterns (lists, delegated triggers, child targeting). See [Element Resolution](#element-resolution) for details.
 
-- **sequences?: Record<string, SequenceConfig>**
-  - **Purpose**: A registry of reusable sequence definitions that can be referenced from interactions via `SequenceConfigRef`.
-  - **Key (string)**: The sequence id. MUST be unique across the registry.
-  - **Value (SequenceConfig)**: A full sequence definition. See Sequences section below.
+---
 
-- **conditions?: Record<string, Condition>**
-  - **Purpose**: Named predicates that gate interactions/effects by runtime context.
-  - **Key (string)**: The condition id. MUST be unique across the registry.
-  - **Value (Condition)**:
-    - **type**: `'media' | 'container' | 'selector'`
-      - `'media'`: The predicate MUST be a valid CSS media query expression without the outer `@media` keyword (e.g., `'(min-width: 768px)'`).
-      - `'container'`: The predicate SHOULD be a valid CSS container query condition string relative to the relevant container context.
-      - `'selector'`: The predicate is a CSS selector pattern. If it contains `&`, the `&` is replaced with the base element selector; otherwise the predicate is appended to the base selector. Used for conditional styling (e.g., `:nth-of-type(odd)`, `.active`).
-    - **predicate?**: OPTIONAL textual predicate for the given type. If omitted, the condition is treated as always-true (i.e., a no-op guard).
+## Triggers
 
 - **interactions: Interaction[]**
   - **Purpose**: Declarative mapping from a source element and trigger to one or more target effects.
@@ -157,38 +187,16 @@ This configuration declares what user/system triggers occur on which source elem
     - **trigger: TriggerType**
       - REQUIRED. One of:
         - `'hover' | 'click' | 'activate' | 'interest'`: Pointer interactions (`activate` = click with keyboard Space/Enter; `interest` = hover with focus).
-        - `'viewEnter' | 'pageVisible' | 'viewProgress'`: Viewport visibility/progress triggers.
+        - `'viewEnter' | 'viewProgress'`: Viewport visibility/progress triggers.
         - `'animationEnd'`: Fires when a specific effect completes on the source element.
         - `'pointerMove'`: Continuous pointer motion over an area.
     - **params?: TriggerParams**
       - OPTIONAL. Parameter object that MUST match the trigger:
-        - hover/click/activate/interest: `StateParams | PointerTriggerParams` (activate uses same params as click; interest uses same params as hover).
-          - `StateParams.method`: `'add' | 'remove' | 'toggle' | 'clear'`
-          - `PointerTriggerParams.type?`: `'once' | 'repeat' | 'alternate' | 'state'`
-          - Usage:
-            - When the effect is a `TransitionEffect`, use `StateParams.method` to control the state toggle invoked on interaction:
-              - `'toggle'` (default): Hover — adds on enter and removes on leave. Click — toggles on each click.
-              - `'add'`: Apply the state on the event; hover leave will NOT auto‑remove.
-              - `'remove'`: Remove the state on the event.
-              - `'clear'`: Clear/reset the effect’s state for the element (or list item when list context is used).
-              - With lists (`listContainer`/`listItemSelector`), the state is set on the matching item only.
-            - When the effect is a time animation (`namedEffect`/`keyframeEffect`), use `PointerTriggerParams.type`:
-              - `'alternate'` (default): Hover — play on enter, reverse on leave. Click — alternate play/reverse on successive clicks.
-              - `'repeat'`: Restart from progress 0 on each event; on hover leave the animation is canceled.
-              - `'once'`: Play once and remove the listener (hover attaches only the enter listener; no leave).
-              - `'state'`: Hover — play on enter if idle/paused, pause on leave if running. Click — toggle play/pause on successive clicks until finished.
-        - viewEnter/pageVisible/viewProgress: `ViewEnterParams`
-          - `type?`: `'once' | 'repeat' | 'alternate' | 'state'`
+        - hover/click/activate/interest: No params needed. Behavior is configured on the effect itself.
+        - viewEnter: `ViewEnterParams`
           - `threshold?`: number in [0,1] describing intersection threshold
           - `inset?`: string CSS-style inset for rootMargin/observer geometry
-          - Usage:
-            - `'once'`: Play on first visibility and unobserve the element.
-            - `'repeat'`: Play each time the element re‑enters visibility according to `threshold`/`inset`.
-            - `'alternate'`: Triggers on re‑entries; if you need alternating direction, set it on the effect (e.g., `alternate: true`) rather than relying on the trigger.
-            - `'state'`: Play on entry, pause on exit (for looping/continuous animations).
-            - `threshold`: Passed to `IntersectionObserver.threshold` — typical values are 0.1–0.6 for entrances.
-            - `inset`: Applied as vertical `rootMargin` (`top/bottom`), e.g., `'-100px'` to trigger earlier/later; left/right remain 0.
-            - Note: For `viewProgress`, `threshold` and `inset` are ignored; progress is driven by ViewTimeline/scroll scenes. Control the range via `ScrubEffect.rangeStart/rangeEnd` and `namedEffect.range`.
+        - viewProgress: No trigger params. Progress is driven by ViewTimeline/scroll scenes. Control the range via `ScrubEffect.rangeStart/rangeEnd` and `namedEffect.range`.
         - animationEnd: `AnimationEndParams`
           - `effectId`: string of the effect to wait for completion
           - Usage: Fire when the specified effect (by `effectId`) on the source element finishes, useful for chaining sequences.
@@ -213,292 +221,460 @@ This configuration declares what user/system triggers occur on which source elem
               };
               ```
 
-    - **conditions?: string[]**
-      - OPTIONAL. Array of condition ids that MUST all pass for this trigger to be active.
-    - **selector?: string**
-      - OPTIONAL. Additional CSS selector to refine element selection:
-        - Without `listContainer`: Uses `querySelectorAll` to match all elements within the root element as separate items.
-        - With `listContainer`: Uses `querySelectorAll` within the container to find matching elements as list items. For dynamically added list items, uses `querySelector` within each item to find a single matching element.
-    - **effects?: Array<Effect | EffectRef>**
-      - The effects to apply when the trigger fires. Ordering is significant: the first array entry is applied first. The system may reverse internal storage to preserve this application order.
-      - At least one of `effects` or `sequences` MUST be provided.
-    - **sequences?: Array<SequenceConfig | SequenceConfigRef>**
-      - OPTIONAL. Sequences to play when the trigger fires. Each sequence coordinates multiple effects with staggered timing. See Sequences section below.
+### hover / click
+
+For `TimeEffect` (keyframe/named/custom effects), set `triggerType` on the effect. For `StateEffect` (transitions), set `stateAction` on the effect. Do NOT mix `triggerType` and `stateAction` on the same effect.
+
+**`triggerType`** — on `TimeEffect`:
+
+| Type                    | hover behavior                          | click behavior                   |
+| :---------------------- | :-------------------------------------- | :------------------------------- |
+| `'alternate'` (default) | Play on enter, reverse on leave         | Alternate play/reverse per click |
+| `'repeat'`              | Play on enter, stop and rewind on leave | Restart per click                |
+| `'once'`                | Play once on first enter only           | Play once on first click only    |
+| `'state'`               | Play on enter, pause on leave           | Toggle play/pause per click      |
+
+**`stateAction`** — on `StateEffect`:
+
+| Action               | hover behavior                                  | click behavior               |
+| :------------------- | :---------------------------------------------- | :--------------------------- |
+| `'toggle'` (default) | Add style state on enter, remove on leave       | Toggle style state per click |
+| `'add'`              | Add style state on enter; leave does NOT remove | Add style state on click     |
+| `'remove'`           | Remove style state on enter                     | Remove style state on click  |
+| `'clear'`            | Clear/reset all style states on enter           | Clear/reset all style states |
+
+### viewEnter
+
+```ts
+params: {
+  threshold?: number;  // 0–1, IntersectionObserver threshold
+  inset?: string;      // like view-timeline-inset, e.g. '-100px' or '-50px 0px'
+}
+// Playback behavior is set on each effect:
+effect.triggerType: 'once' | 'repeat' | 'alternate' | 'state';  // default: 'once'
+```
+
+**CRITICAL:** When source and target are the **same element**, MUST use `triggerType: 'once'`. For `'repeat'` / `'alternate'` / `'state'`, ALWAYS use **separate** source and target elements — animating the observed element can cause it to leave/re-enter the viewport, causing rapid re-triggers.
+
+### viewProgress
+
+Scroll-driven animations using native `ViewTimeline`, with polyfill where not supported. Progress is driven by scroll position. Control the range via `rangeStart`/`rangeEnd` on the effect (see [Scroll / Pointer-driven Effect](#scroll--pointer-driven-effect)).
+
+`viewProgress` has no trigger params. Range configuration (`rangeStart`/`rangeEnd`) is on the effect, not on the trigger.
+
+**CRITICAL:** Replace ALL `overflow: hidden` with `overflow: clip` on every element between the trigger source and the scroll container. `overflow: hidden` creates a new scroll context that breaks ViewTimeline. In Tailwind replace `overflow-hidden` with `overflow-clip`.
+
+### pointerMove
+
+```ts
+params: {
+  hitArea?: 'self' | 'root';  // 'self' = source element bounds, 'root' = viewport
+  axis?: 'x' | 'y';           // restricts tracking to a single axis (for keyframeEffect)
+}
+```
+
+**Rules:**
+
+- Source element MUST NOT have `pointer-events: none`.
+- MUST NOT use the same element as both source and target with size or position effects — use `selector` to target a child or set a different `key`.
+- Use a `(hover: hover)` media condition to disable on touch-only devices. On touch-only devices prefer `viewEnter` or `viewProgress` fallbacks.
+- For 2D effects, use `namedEffect` mouse presets or `customEffect`. `keyframeEffect` only supports a single axis.
+- For independent 2-axis control with keyframes, use two separate interactions (one `axis: 'x'`, one `axis: 'y'`) with `composite: 'add'` or `'accumulate'` on the second effect.
+
+**`centeredToTarget`** — set `true` to remap the `0–1` progress range so that `0.5` progress corresponds to the center of the target element. Use when source and target are different elements, or when `hitArea: 'root'` is used, so that the pointer resting over the target center produces 50% progress regardless of position in viewport.
+
+**Progress object** (for `customEffect`):
+
+```ts
+{ x: number; y: number; v?: { x: number; y: number }; active?: boolean }
+// x, y: 0–1 normalized position within hit area
+// v: velocity vector (unbounded, typically -1 to 1 range at moderate speed; 0 = stationary)
+// active: whether pointer is within the active hit area
+```
+
+### animationEnd
+
+```ts
+params: {
+  effectId: string;
+} // the effect to wait for
+```
+
+Fires when the specified effect completes on the source element. Useful for chaining sequences.
+
+---
+
+## Effects
+
+Each effect applies a visual change to a target element. An effect is either inline or referenced by `effectId` from the top-level `effects` registry (`EffectRef`). An `EffectRef` inherits all properties from the registry entry, and can override any of them (e.g. `key`, `duration`, `easing`, `fill`, etc.) — not just the target. See [Element Resolution](#element-resolution) for how the target is determined.
+
+### Common fields
+
+```ts
+{
+  key?: string;              // target element key; omit to target the source
+  effectId?: string;         // reference to effects registry (EffectRef)
+  conditions?: string[];     // ids referencing the top-level conditions map; all must pass
+  selector?: string;         // optional — CSS selector to refine target element
+  listContainer?: string;    // optional — CSS selector for list container
+  listItemSelector?: string; // optional — filter which children of listContainer are selected
+  composite?: 'replace' | 'add' | 'accumulate';
+  fill?: 'none' | 'forwards' | 'backwards' | 'both';
+}
+```
+
+**`fill` guidance:**
+
+- `'both'` — use for scroll-driven (`viewProgress`), pointer-driven (`pointerMove`), and toggling effects (`hover`/`click` with `alternate`, `repeat`, or `state` type).
+- `'backwards'` — use for entrance animations with `type: 'once'` when the element's own CSS already matches the final keyframe (applies the initial keyframe during any `delay`).
+
+**`composite`** — same as CSS's `animation-composition`. Controls how this effect combines with others on the same property (transforms & filters):
+
+- `'replace'` (default): fully replaces prior values.
+- `'add'`: concatenates transform/filter functions after any existing ones (e.g. existing `translateX(10px)` + added `translateY(20px)` → both apply).
+- `'accumulate'`: merges arguments of matching functions (e.g. `translateX(10px)` + `translateX(20px)` → `translateX(30px)`); non-matching functions concatenate like `'add'`.
+
+**`easing` guidance:** from `@wix/motion` (in addition to standard CSS easings):
+
+`'linear'`, `'ease'`, `'ease-in'`, `'ease-out'`, `'ease-in-out'`, `'sineIn'`, `'sineOut'`, `'sineInOut'`, `'quadIn'`, `'quadOut'`, `'quadInOut'`, `'cubicIn'`, `'cubicOut'`, `'cubicInOut'`, `'quartIn'`, `'quartOut'`, `'quartInOut'`, `'quintIn'`, `'quintOut'`, `'quintInOut'`, `'expoIn'`, `'expoOut'`, `'expoInOut'`, `'circIn'`, `'circOut'`, `'circInOut'`, `'backIn'`, `'backOut'`, `'backInOut'`, or any `'cubic-bezier(...)'` / `'linear(...)'` string.
+
+### Time-based Effect
+
+Used with `hover`, `click`, `viewEnter`, `animationEnd` triggers.
+
+```ts
+{
+  duration: number;            // REQUIRED (ms)
+  easing?: string;             // CSS easing or named easing (see below)
+  delay?: number;              // ms
+  iterations?: number;         // >=1 or Infinity; 0 is treated as Infinity
+  alternate?: boolean;
+  reversed?: boolean;
+  fill?: 'none' | 'forwards' | 'backwards' | 'both';
+  composite?: 'replace' | 'add' | 'accumulate';
+  // + exactly one animation payload (see below)
+}
+```
+
+### Scroll / Pointer-driven Effect
+
+Used with `viewProgress` and `pointerMove` triggers.
+
+```ts
+{
+  rangeStart?: RangeOffset;    // REQUIRED for viewProgress
+  rangeEnd?: RangeOffset;      // REQUIRED for viewProgress
+  easing?: string;             // CSS easing or named easing (see above)
+  iterations?: number;         // NOT Infinity
+  alternate?: boolean;
+  reversed?: boolean;
+  fill?: 'none' | 'forwards' | 'backwards' | 'both';
+  composite?: 'replace' | 'add' | 'accumulate';
+  centeredToTarget?: boolean;
+  transitionDuration?: number; // ms, smoothing on progress jumps (primarily for pointerMove)
+  transitionDelay?: number;    // ms (primarily for pointerMove)
+  transitionEasing?: 'linear' | 'hardBackOut' | 'easeOut' | 'elastic' | 'bounce';
+  // + exactly one animation payload (see below)
+}
+```
+
+**RangeOffset** — works like CSS's `animation-range`:
 
-### Sequences (coordinated multi-effect stagger)
+```ts
+{
+  name?: 'entry' | 'exit' | 'contain' | 'cover' | 'entry-crossing' | 'exit-crossing';
+  offset?: { value: number; unit: 'percentage' | 'px' | 'vh' | 'vw' }
+}
+```
 
-Sequences let you group multiple effects into a single coordinated timeline with staggered delays. Instead of manually setting `delay` on each effect, you define `offset` (ms between items) and `offsetEasing` (how that offset is distributed).
+| Range name       | Meaning                                                        |
+| :--------------- | :------------------------------------------------------------- |
+| `entry`          | Element entering viewport                                      |
+| `exit`           | Element exiting viewport                                       |
+| `contain`        | After `entry` range and before `exit` range                    |
+| `cover`          | Full range from `entry` through `contain` and `exit`           |
+| `entry-crossing` | From element's leading edge entering to trailing edge entering |
+| `exit-crossing`  | From element's leading edge exiting to trailing edge exiting   |
 
-**Prefer sequences over manual delay stagger** for any multi-element entrance or orchestration pattern.
+**Sticky container pattern** — for scroll-driven animations inside a stuck `position: sticky` container:
 
-- **SequenceConfig** type:
-  - `effects: (Effect | EffectRef)[]` — REQUIRED. The effects in this sequence, applied in array order.
-  - `delay?: number` — Base delay (ms) before the entire sequence starts. Default `0`.
-  - `offset?: number` — Stagger offset (ms) between consecutive effects. Default `0`.
-  - `offsetEasing?: string | ((p: number) => number)` — Easing function for stagger distribution. Named easings: `'linear'`, `'quadIn'`, `'quadOut'`, `'sineOut'`, `'cubicIn'`, `'cubicOut'`, `'cubicInOut'`. Also accepts `'cubic-bezier(...)'` strings or a JS function `(p: number) => number`. Default `'linear'`.
-  - `sequenceId?: string` — Id for caching and referencing. Auto-generated if omitted.
-  - `conditions?: string[]` — Condition ids that MUST all pass for this sequence to be active.
+- Tall wrapper: height defines scroll distance (e.g. `300vh` for ~2 viewport-heights of scroll travel).
+- Sticky child (`key`) with `position: sticky; top: 0; height: 100vh`: stays fixed while the wrapper scrolls. This is the ViewTimeline source.
+- Use `rangeStart/rangeEnd` with `name: 'contain'` to animate only during the stuck phase.
 
-- **SequenceConfigRef** type (referencing a reusable sequence):
-  - `sequenceId: string` — REQUIRED. MUST match a key in `InteractConfig.sequences`.
-  - `delay?`, `offset?`, `offsetEasing?`, `conditions?` — OPTIONAL overrides merged on top of the referenced sequence.
+### StateEffect (CSS style toggle)
 
-- Effects within a sequence follow the same rules as standalone effects. Each effect can:
-  - Target a different element via `key` (cross-element sequences).
-  - Use `listContainer` to target list children (each child becomes a separate effect in the sequence).
-  - Reference the effects registry via `effectId`.
+Used with `hover` / `click` triggers. Set `stateAction` on the effect to control state behavior.
 
-- A sequence is treated as a single animation unit by the trigger handler—it plays, reverses, and alternates as one.
+**StateEffect** (CSS transition-style state toggles):
 
-**Example — viewEnter staggered list using `listContainer`**:
+- `key?`: string (target override; see TARGET CASCADE)
+- `effectId?`: string (when used as a reference identity)
+- One of:
+  - `transition?`: `{ duration?: number; delay?: number; easing?: string; styleProperties: { name: string; value: string }[] }`
+    - Applies a single transition options block to all listed style properties.
+  - `transitionProperties?`: `Array<{ name: string; value: string; duration?: number; delay?: number; easing?: string }>`
+    - Allows per-property transition options. If both `transition` and `transitionProperties` are provided, the system SHOULD apply both with per-property entries taking precedence for overlapping properties.
 
-```typescript
+```ts
+// Shared timing for all properties:
+{
+  transition: {
+    duration?: number; delay?: number; easing?: string;
+    styleProperties: [{ name: string; value: string }]
+  }
+}
+
+// Per-property timing:
+{
+  transitionProperties: [
+    { name: string; value: string; duration?: number; delay?: number; easing?: string }
+  ]
+}
+```
+
+CSS property names use **camelCase** (e.g. `'backgroundColor'`, `'borderRadius'`).
+
+### Animation Payloads
+
+Exactly one MUST be provided per time-based or scroll/pointer-driven effect:
+
+1. **`namedEffect`** (preferred) — pre-built presets from `@wix/motion-presets`. GPU-friendly and tuned.
+
+   ```ts
+   namedEffect: {
+     type: '[PRESET_NAME]',
+     // ...optional [PRESET_OPTIONS] as additional properties
+   }
+   ```
+
+   - `[PRESET_NAME]` — one of the registered preset names (see table below).
+   - `[PRESET_OPTIONS]` — optional preset-specific properties spread as additional keys on the object. **CRITICAL:** Do NOT guess option names/types. Omit unknown options and rely on defaults.
+
+   Available presets:
+
+   | Category | Presets                                                                                                                                                                                                                                                                                      |
+   | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | Entrance | `FadeIn`, `GlideIn`, `SlideIn`, `FloatIn`, `RevealIn`, `ExpandIn`, `BlurIn`, `FlipIn`, `ArcIn`, `ShuttersIn`, `CurveIn`, `DropIn`, `FoldIn`, `ShapeIn`, `TiltIn`, `WinkIn`, `SpinIn`, `TurnIn`, `BounceIn`                                                                                   |
+   | Ongoing  | `Pulse`, `Spin`, `Breathe`, `Bounce`, `Wiggle`, `Flash`, `Flip`, `Fold`, `Jello`, `Poke`, `Rubber`, `Swing`, `Cross`                                                                                                                                                                         |
+   | Scroll   | `FadeScroll`, `RevealScroll`, `ParallaxScroll`, `MoveScroll`, `SlideScroll`, `GrowScroll`, `ShrinkScroll`, `TiltScroll`, `PanScroll`, `BlurScroll`, `FlipScroll`, `SpinScroll`, `ArcScroll`, `ShapeScroll`, `ShuttersScroll`, `SkewPanScroll`, `Spin3dScroll`, `StretchScroll`, `TurnScroll` |
+   | Mouse    | `TrackMouse`, `Tilt3DMouse`, `Track3DMouse`, `SwivelMouse`, `AiryMouse`, `ScaleMouse`, `BlurMouse`, `SkewMouse`, `BlobMouse`                                                                                                                                                                 |
+   - **CRITICAL** — Scroll presets (`*Scroll`) used with `viewProgress` MUST include `range` in options: `'in'` (ends at idle state), `'out'` (starts from idle state), or `'continuous'` (passes through idle). Prefer `'continuous'`.
+   - Mouse presets are preferred over `keyframeEffect` for `pointerMove` 2D effects.
+
+2. **`keyframeEffect`** — custom keyframe animations.
+
+   ```ts
+   keyframeEffect: { name: '[EFFECT_NAME]', keyframes: [KEYFRAMES] }
+   ```
+
+   - `[EFFECT_NAME]` — unique string identifier for this effect.
+   - `[KEYFRAMES]` — array of keyframe objects using standard WAAPI format (e.g. `[{ opacity: '0' }, { opacity: '1' }]`). Property names in camelCase.
+
+3. **`customEffect`** — imperative update callback. Use only when CSS-based effects cannot express the desired behavior (e.g., animating SVG attributes, canvas, text content).
+
+   ```ts
+   customEffect: [CUSTOM_EFFECT_CALLBACK];
+   ```
+
+   - `[CUSTOM_EFFECT_CALLBACK]` — function with signature `(element: Element, progress: number | ProgressObject) => void`. Called on each animation frame.
+
+---
+
+## Sequences
+
+Coordinate multiple effects with staggered timing. Prefer sequences over manual delay stagger.
+
+### Sequence As type
+
+```ts
+{
+  effects: (Effect | EffectRef)[];      // REQUIRED
+  delay?: number;                       // ms before sequence starts
+  offset?: number;                      // ms between each child's animation start
+  offsetEasing?: string;                // easing curve for staggering offsets
+  sequenceId?: string;                  // for caching/referencing
+  conditions?: string[];                // ids referencing the top-level conditions map
+}
+```
+
+### Template
+
+```ts
 {
   interactions: [
     {
-      key: 'card-grid',
-      trigger: 'viewEnter',
-      params: { type: 'once', threshold: 0.3 },
+      key: '[SOURCE_KEY]',
+      trigger: '[TRIGGER]',
+      params: [TRIGGER_PARAMS],
       sequences: [
         {
-          offset: 100,
-          offsetEasing: 'quadIn',
+          offset: [OFFSET_MS],           // optional
+          offsetEasing: '[OFFSET_EASING]', // optional
+          delay: [DELAY_MS],             // optional
           effects: [
+            // if used `listContainer` each item in the list is a target of a child effect
             {
-              effectId: 'card-entrance',
-              listContainer: '.card-grid',
+              effectId: '[EFFECT_ID]',
+              listContainer: '[LIST_CONTAINER_SELECTOR]',
             },
+            // if multiple effects are given each generated effect is added to the sequence
           ],
         },
       ],
     },
   ],
   effects: {
-    'card-entrance': {
-      // ...
+    '[EFFECT_ID]': {
+      // effect definition (namedEffect, keyframeEffect, or customEffect)
     },
   },
 }
 ```
 
-### Working with elements
+### Variables
 
-#### Web: `<interact-element>` custom element
+- `[SOURCE_KEY]` — identifier matching the element's key (`data-interact-key` for /vanilla, `interactKey` for React).
+- `[TRIGGER]` — any trigger for time-based animation effects (e.g., `'viewEnter'`, `'activate'`, `'interest'`).
+- `[TRIGGER_PARAMS]` — trigger-specific parameters (e.g., `{ type: 'once', threshold: 0.3 }`).
+- `[OFFSET_MS]` — ms between each child's animation start.
+- `[OFFSET_EASING]` — CSS easing string or named easing from `@wix/motion`.
+- `[DELAY_MS]` — optional. Base delay (ms) before the entire sequence starts.
+- `[EFFECT_ID]` — string key referencing an entry in the top-level `effects` map.
+- `[LIST_CONTAINER_SELECTOR]` — optional. CSS selector for the container whose children will be staggered.
 
-- Wrap the interactive DOM subtree with the custom element and set `data-interact-key` to a stable key. Reference that same key from your config via `Interaction.key` (and optionally `Effect.key`). No observers/listeners or manual DOM querying are needed—the runtime binds triggers and effects via this attribute.
-- If an effect targets an element that is not the interaction's source, you MUST also wrap that target element's subtree with its own `<interact-element>` and set `data-interact-key` to the target's key (the value used in `Effect.key` or the referenced registry Effect's `key`). This is required so the runtime can locate and apply effects to non-source targets.
-- MUST have a `data-interact-key` attribute with a value that is unique within the scope.
-- MUST contain at least one child element.
+Reusable sequences can be defined in `InteractConfig.sequences` and referenced by `sequenceId`.
 
-```html
-<interact-element data-interact-key="my-button">
-  <button id="my-button">Click me</button>
-</interact-element>
+---
+
+## Conditions
+
+Named conditions that gate interactions, effects, or sequences.
+
+| Type       | Predicate                                                                 |
+| :--------- | :------------------------------------------------------------------------ |
+| `media`    | CSS media query condition without `@media` (e.g., `'(min-width: 768px)'`) |
+| `selector` | CSS selector; `&` is replaced with the base element selector              |
+
+Attach via `conditions: ['[CONDITION_ID]']` on interactions, effects, or sequences. On an interaction, conditions gate the entire trigger; on an effect, only that specific effect is skipped. All listed conditions must pass.
+
+### Examples
+
+```ts
+conditions: {
+  'desktop': { type: 'media', predicate: '(min-width: 768px)' },
+  'hover-device': { type: 'media', predicate: '(hover: hover)' },
+  'reduced-motion': { type: 'media', predicate: '(prefers-reduced-motion: reduce)' },
+  'odd-items': { type: 'selector', predicate: ':nth-of-type(odd)' },
+}
 ```
 
+---
+
+## FOUC Prevention
+
+**Problem:** Elements with entrance animations (e.g. `viewEnter` + `type: 'once'` with `FadeIn`) start in their final visible state. Before the animation framework initializes and applies the starting keyframe (e.g. `opacity: 0`), the element is briefly visible at full opacity — causing a flash of unstyled/un-animated content (FOUC).
+
+**Solution:** Two things are required — both MUST be present:
+
+1. **Generate critical CSS** using `generate(config)` — produces CSS rules that hide entrance-animated elements from the moment the page renders.
+2. **Mark elements with `initial`** — tells the runtime which elements have critical CSS applied so it can coordinate with the generated styles.
+
+### Step 1: Generate CSS
+
+Call `generate(config)` server-side or at build time and inject the result into the `<head>` (preferred), or insert to beginning of `<body>`, so it loads before the page content is painted:
+
 ```ts
-import type { InteractConfig } from '@wix/interact';
+import { generate } from '@wix/interact/web';
+const css = generate(config);
+```
 
-const config: InteractConfig = {
-  interactions: [
-    {
-      key: 'my-button', // matches data-interact-key
-      trigger: 'hover',
-      effects: [
-        {
-          // key omitted -> targets the source element ('my-button')
-          // effect props go here (e.g., transition | keyframeEffect | namedEffect | customEffect)
-        },
-      ],
-    },
-  ],
-};
+**Append to `<head>` or beginning of `<body>`:**
+
+```html
+<style>
+  ${css}
+</style>
 ```
 
-For a different target element:
+### Step 2: Mark elements
+
+**Web (Custom Elements):**
 
 ```html
-<interact-element data-interact-key="my-button">
-  <button id="my-button">Click me</button>
+<interact-element data-interact-key="hero" data-interact-initial="true">
+  <section class="hero">...</section>
 </interact-element>
+```
 
-<interact-element data-interact-key="my-badge">
-  <span id="my-badge">Badge</span>
-</interact-element>
+**React:**
+
+```tsx
+<Interaction tagName="section" interactKey="hero" initial={true} className="hero">
+  ...
+</Interaction>
 ```
 
-```ts
-const config: InteractConfig = {
-  interactions: [
-    {
-      key: 'my-button',
-      trigger: 'click',
-      effects: [
-        {
-          key: 'my-badge', // target is different than source
-          // effect props (e.g., transition | keyframeEffect | namedEffect)
-        },
-      ],
-    },
-  ],
-};
+**Vanilla:**
+
+```html
+<section data-interact-key="hero" data-interact-initial="true" class="hero">...</section>
 ```
 
-#### React: `<Interaction>` component
+### Rules
 
-- MUST replace the element itself with the `<Interaction/>` component.
-- MUST set the `tagName` prop with the tag of the replaced element.
-- MUST set the `interactKey` prop to a unique string within the scope.
+- `generate()` should be called server-side or at build time. Can also be called on client-side if page content is initially hidden (e.g. behind a loader/splash screen).
+- **Both** `generate(config)` CSS **and** `initial` on the element are required. Using only one has no effect.
+- `initial` is only valid for `viewEnter` + `type: 'once'` where source and target are the same element.
+- For `repeat`/`alternate`/`state`, do NOT use `initial`. Instead, manually apply the initial keyframe as inline styles on the target element and use `fill: 'both'`.
 
-```tsx
-import { Interaction } from '@wix/interact/react';
+---
 
-function MyComponent() {
-  return (
-    <Interaction tagName="button" interactKey="my-button" className="btn">
-      Click me
-    </Interaction>
-  );
-}
-```
+## Element Resolution
 
-For a different target element:
+For simple use cases, `key` on the interaction matches the element, and the same element is both trigger source and animation target. The fields below are only needed for advanced patterns (lists, delegated triggers, child targeting).
 
-```tsx
-import { Interaction } from '@wix/interact/react';
+### Source element resolution (Interaction level)
 
-function MyComponent() {
-  return (
-    <>
-      <Interaction tagName="button" interactKey="my-button" className="btn">
-        Click me
-      </Interaction>
-
-      <Interaction tagName="span" interactKey="my-badge" className="badge">
-        Badge
-      </Interaction>
-    </>
-  );
-}
-```
+The source element is what the trigger attaches to. Resolved in priority order:
+
+1. **`listContainer` + `listItemSelector`** — trigger attaches to each element matching `listItemSelector` within the `listContainer`. Use `listItemSelector` only when you need to **filter** which children participate (e.g. select only `.active` items). If all immediate children should participate, omit `listItemSelector`.
+2. **`listContainer` only** — trigger attaches to each immediate child of the container. This is the common case for lists.
+3. **`listContainer` + `selector`** — trigger attaches to the element found via `querySelector` within each immediate child of the container.
+4. **`selector` only** — trigger attaches to all elements matching `querySelectorAll` within the root `<interact-element>`.
+5. **Fallback** — first child of `<interact-element>` (web) or the root element (react/vanilla).
+
+### Target element resolution (Effect level)
+
+The target element is what the effect animates. Resolved in priority order:
+
+1. **`Effect.key`** — the `<interact-element>` with matching `data-interact-key`.
+2. **Registry Effect's `key`** — if the effect is an `EffectRef`, the `key` from the referenced registry entry is used.
+3. **Fallback to `Interaction.key`** — the same `key` is used for the source will be used for the target.
+4. After resolving the root target, `selector`, `listContainer`, and `listItemSelector` on the effect further refine which child elements within that target are animated (same priority order as source resolution).
+
+---
+
+## Static API
+
+| Method / Property                   | Description                                                                                                   |
+| :---------------------------------- | :------------------------------------------------------------------------------------------------------------ |
+| `Interact.create(config)`           | Initialize with a config. Returns the instance. Store the instance to manage its lifecycle.                   |
+| `Interact.registerEffects(presets)` | Register named effect presets. MUST be called before `create`.                                                |
+| `Interact.destroy()`                | Tear down all instances. Call on unmount or route change to prevent memory leaks.                             |
+| `Interact.forceReducedMotion`       | `boolean` (default: `false`) — force reduced-motion behavior regardless of OS setting.                        |
+| `Interact.allowA11yTriggers`        | `boolean` (default: `false`) — enable accessibility trigger variants (`interest`, `activate`).                |
+| `Interact.setup(options)`           | Configure global options for scroll, pointer, and viewEnter systems. Call before `create`. See options below. |
+
+**`Interact.setup(options)`** — optional configuration object:
+
+| Option                 | Type                           | Description                                                           |
+| :--------------------- | :----------------------------- | :-------------------------------------------------------------------- |
+| `scrollOptionsGetter`  | `() => Partial<scrollConfig>`  | Function returning defaults for scroll-driven animation configuration |
+| `pointerOptionsGetter` | `() => Partial<PointerConfig>` | Function returning defaults for pointer-move animation configuration  |
+| `viewEnter`            | `Partial<ViewEnterParams>`     | Defaults for all viewEnter triggers (`threshold`,`inset`)             |
+| `allowA11yTriggers`    | `boolean`                      | Enable accessibility trigger variants (use `interest` and `activate`) |
+
+Use `setup()` when you need to override default observer thresholds or provide global configuration that applies to all interactions of a given trigger type.
 
-The config remains the same for both integrations—only the HTML/JSX setup differs.
-
-### Effect rules (applies to both registry-defined Effect and inline Effect within interactions)
-
-- Common fields (`EffectBase`):
-  - **key?: string**
-    - OPTIONAL. Target element path. If omitted, resolution follows TARGET CASCADE:
-      1. `Effect.key` (if provided)
-      2. If Effect is an `EffectRef`: lookup registry by `effectId` and use that registry Effect’s `key`
-      3. Fallback to the `Interaction.key` (i.e., source acts as target)
-  - **listContainer?: string, listItemSelector?: string**
-    - OPTIONAL. If provided, MUST match the interaction's list context when both exist.
-  - **conditions?: string[]**
-    - OPTIONAL. All conditions MUST pass for the effect to run (in addition to interaction conditions).
-  - **selector?: string**
-    - OPTIONAL. Additional CSS selector to refine target element selection:
-      - Without `listContainer`: Uses `querySelectorAll` to match all elements within the target root as separate items.
-      - With `listContainer`: Uses `querySelectorAll` within the container to find matching elements as list items. For dynamically added list items, uses `querySelector` within each item to find a single matching element.
-  - **effectId?: string**
-    - For `EffectRef` this field is REQUIRED and MUST reference an entry in `effects`.
-
-- Composition and fill usage
-  - **composite** (similar to CSS `animation-composition` / WAAPI `composite`):
-    - Controls how this effect combines with other effects targeting the same element/property.
-    - `'replace'` (default): this effect fully replaces prior values for overlapping properties.
-    - `'add'`: this effect adds to the underlying value where the property supports additive composition (e.g., transforms, filters, opacity).
-    - `'accumulate'`: values build up across iterations/repeats where supported.
-    - Note: If a property is not additive, the runtime will treat `'add'`/`'accumulate'` like `'replace'`.
-  - **fill** (like CSS `animation-fill-mode`):
-    - `'none'`: styles are only applied while the effect is actively running/in-range.
-    - `'forwards'`: the effect’s end state is retained after completion (or last sampled value for scrub).
-    - `'backwards'`: the start state applies before the effect begins (or before `rangeStart` for scrub/during `delay` for time effects).
-    - `'both'`: combines `'backwards'` and `'forwards'`.
-    - For scroll-driven animations (`viewProgress`), prefer `fill: 'both'` to preserve start/end states around the active range and avoid flicker on rapid scroll.
-
-- Types of `Effect` (exactly one MUST be provided via discriminated fields):
-  1. **TimeEffect** (discrete animation over time)
-     - `duration`: number (REQUIRED)
-     - `easing?`: string (CSS/WAAPI easing)
-     - `iterations?`: number (>=1 or Infinity)
-     - `alternate?`: boolean (direction alternation)
-     - `fill?`: `'none' | 'forwards' | 'backwards' | 'both'`
-     - `composite?`: `'replace' | 'add' | 'accumulate'`
-     - `reversed?`: boolean
-     - `delay?`: number (ms)
-     - One of:
-       - `keyframeEffect`: `{ name: string; keyframes: Keyframe[] }`
-       - `namedEffect`: `NamedEffect` (from `@wix/motion-presets`)
-       - `customEffect`: `(element: Element, progress: any) => void`
-
-  2. **ScrubEffect** (animation driven by scroll/progress)
-     - `easing?`: string
-     - `iterations?`: number (NOT Infinity)
-     - `alternate?`: boolean
-     - `fill?`: `'none' | 'forwards' | 'backwards' | 'both'`
-     - `composite?`: `'replace' | 'add' | 'accumulate'`
-     - `reversed?`: boolean
-     - `rangeStart`: `RangeOffset`
-     - `rangeEnd`: `RangeOffset`
-     - `centeredToTarget?`: boolean // If `true` centers the coordinate range at the target element, otherwise uses source element
-     - `transitionDuration?`: number (ms for smoothing on progress jumps)
-     - `transitionDelay?`: number
-     - `transitionEasing?`: `ScrubTransitionEasing`
-     - One of `keyframeEffect | namedEffect | customEffect` (see above)
-     - For mouse-effects driven by the `pointerMove` trigger, avoid `keyframeEffect` unless using `params: { axis: 'x' | 'y' }` to map a single pointer axis to linear 0–1 progress. For 2D effects, use `namedEffect` mouse presets or `customEffect` instead.
-     - For scroll `namedEffect` presets (e.g., `*Scroll`) used with a `viewProgress` trigger, include `range: 'in' | 'out' | 'continuous'` in the `namedEffect` options; prefer `'continuous'` for simplicity.
-     - RangeOffset (used by `rangeStart`/`rangeEnd`):
-       - Type: `{ name: 'entry' | 'exit' | 'contain' | 'cover' | 'entry-crossing' | 'exit-crossing'; offset: LengthPercentage }`
-       - name?: Optional logical anchor derived from ViewTimeline concepts.
-         - 'entry': Leading edge of the target crosses into the view/container.
-         - 'exit': Trailing edge of the target crosses out of the view/container.
-         - 'contain': Interval where the target is fully within the view/container.
-         - 'cover': Interval where the view/container is fully covered by the target.
-         - 'entry-crossing': The moment the target's center crosses the entry boundary.
-         - 'exit-crossing': The moment the target's center crosses the exit boundary.
-         - If omitted, the runtime chooses a context-appropriate anchor; specify explicitly for deterministic behavior.
-       - offset: A `LengthPercentage` that shifts the anchor boundary.
-         - Explicit format: `{ value: number; unit: 'percentage' | 'px' | 'em' | 'rem' | 'vh' | 'vw' | 'vmin' | 'vmax' }`
-         - Percentages are interpreted along the relevant scroll axis relative to the observation area (e.g., viewport or container size).
-         - Positive values move the anchor "forward" along the scroll direction; negative values move it "backward".
-       - Examples:
-         - Start when the element is 20% inside the viewport: `rangeStart: { name: 'entry', offset: { value: 20, unit: 'percentage' } }`
-         - End when the element is leaving: `rangeEnd: { name: 'exit', offset: { value: 0, unit: 'percentage' } }`
-
-  3. **TransitionEffect** (CSS transition-style state toggles)
-     - `key?`: string (target override; see TARGET CASCADE)
-     - `effectId?`: string (when used as a reference identity)
-     - One of:
-       - `transition?`: `{ duration?: number; delay?: number; easing?: string; styleProperties: { name: string; value: string }[] }`
-         - Applies a single transition options block to all listed style properties.
-       - `transitionProperties?`: `Array<{ name: string; value: string; duration?: number; delay?: number; easing?: string }>`
-         - Allows per-property transition options. If both `transition` and `transitionProperties` are provided, the system SHOULD apply both with per-property entries taking precedence for overlapping properties.
-
-### Authoring rules for animation payloads (`namedEffect`, `keyframeEffect`, `customEffect`):
-
-- **namedEffect (Preferred)**: Use first for best performance. These are pre-built presets from `@wix/motion-presets` that are GPU-friendly and tuned.
-  - Structure: `namedEffect: { type: '<PresetName>', /* optional preset options like direction (bottom|top|left|right), etc. do not use those without having proper documentation of which options exist and of what types. */ }`
-  - Short list of common preset names:
-    - Entrance: `FadeIn`, `BounceIn`, `SlideIn`, `FlipIn`, `ArcIn`
-    - Ongoing: `Pulse`, `Spin`, `Wiggle`, `Bounce`
-    - Scroll: `ParallaxScroll`, `FadeScroll`, `RevealScroll`, `TiltScroll` — for `viewProgress`, `namedEffect` options MUST include `range: 'in' | 'out' | 'continuous'`; prefer `'continuous'`
-    - Mouse: `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse` — for `pointerMove`; prefer over `keyframeEffect` for 2D pointer effects
-- **keyframeEffect (Default for custom animations)**: Prefer this when you need a custom-made animation.
-  - Structure: `keyframeEffect: { name: string; keyframes: Keyframe[] }` (keyframes use standard CSS/WAAPI properties).
-  - When used with `pointerMove`, requires `params: { axis: 'x' | 'y' }` to select which pointer coordinate maps to linear progress. Without `axis`, pointer progress is two-dimensional and cannot drive keyframe animations. For 2D pointer effects, use `namedEffect` or `customEffect`.
-- **customEffect (Last resort)**: Use only when you must perform DOM manipulation or produce randomized/non-deterministic visuals that cannot be expressed as keyframes or presets.
-  - Structure: `customEffect: (element: Element, progress: any) => void`
-
-### Target resolution and list context
-
-- When applying an effect, the system resolves the final target as:
-  `Effect.key -> registry Effect.key (for EffectRef) -> Interaction.key`.
-- If a `listContainer` is present on the interaction, the selector resolution may be widened to include list items (optionally filtered by `listItemSelector`), and then further refined by any provided `selector`.
-
-### Reduced motion
-
-- The runtime MAY force reduced motion globally. Authors SHOULD keep effects resilient to reduced motion by avoiding reliance on specific durations or continuous motion.
-- Use `conditions` to provide responsive and accessible behavior:
-  - Define media conditions such as `'(prefers-reduced-motion: reduce)'` and breakpoint queries, and attach them to interactions/effects to disable, simplify, or swap animations when appropriate.
-  - Provide alternative reduced‑motion variants (e.g., shorter durations, fewer transforms, no perpetual motion/parallax/3D), and select them via `conditions` or effect references so that users who prefer reduced motion get a gentler experience.
+Each `Interact.create()` call returns an instance. Store instances and call `instance.destroy()` when no longer needed (e.g. on component unmount) to prevent stale listeners and memory leaks.