From 673e66856a0d5e1c7a727415f7f178cfd10f97fb Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Sun, 25 Jan 2026 18:45:17 +0200
Subject: [PATCH 01/29] Add spec and plan for Sequence and clean up old plans

---
 ...ce_feature_implementation_84c01c97.plan.md | 206 ++++++++
 packages/interact/dev/DOCS_PLAN.md            | 463 ------------------
 packages/interact/dev/LIST_PLAN.md            | 212 --------
 packages/interact/dev/RULES_PLAN.md           | 288 -----------
 packages/interact/dev/VIEW_ENTER_SPEC.md      |  28 --
 packages/interact/dev/sequences-spec.md       | 166 +++++++
 6 files changed, 372 insertions(+), 991 deletions(-)
 create mode 100644 .cursor/plans/sequence_feature_implementation_84c01c97.plan.md
 delete mode 100644 packages/interact/dev/DOCS_PLAN.md
 delete mode 100644 packages/interact/dev/LIST_PLAN.md
 delete mode 100644 packages/interact/dev/RULES_PLAN.md
 delete mode 100644 packages/interact/dev/VIEW_ENTER_SPEC.md
 create mode 100644 packages/interact/dev/sequences-spec.md

diff --git a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
new file mode 100644
index 00000000..de7c5cff
--- /dev/null
+++ b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
@@ -0,0 +1,206 @@
+---
+name: Sequence Feature Implementation
+overview: Implement a new Sequence feature in @wix/motion that manages a list of AnimationGroup instances with staggered delays, and integrate it into @eix/interact for declarative configuration.
+todos:
+  - id: motion-sequence-class
+    content: Create Sequence class in @wix/motion that extends AnimationGroup and manages AnimationGroup instances
+    status: pending
+  - id: motion-types
+    content: Add SequenceOptions type to @wix/motion/types.ts and export from index.ts
+    status: pending
+  - id: interact-types
+    content: Update InteractConfig, Interaction, and InteractCache types to include sequences
+    status: pending
+  - id: interact-parse-config
+    content: Update parseConfig in Interact.ts to process sequence declarations and sequence effects
+    status: pending
+  - id: interact-add-sequence
+    content: Update add.ts to create Sequence instances and apply calculated delay offsets
+    status: pending
+  - id: handler-integration
+    content: Update trigger handlers to work with Sequence instances for coordinated playback
+    status: pending
+isProject: false
+---
+
+# Sequence Feature Implementation
+
+This plan implements the Sequence feature as specified in [sequences-spec.md](packages/interact/dev/sequences-spec.md). The feature enables managing multiple Effects as a coordinated timeline with staggered delays.
+
+## Architecture Overview
+
+```mermaid
+classDiagram
+    class AnimationGroup {
+        +animations: Animation[]
+        +options: AnimationGroupOptions
+        +ready: Promise
+        +play()
+        +pause()
+        +reverse()
+        +cancel()
+        +onFinish()
+    }
+    
+    class Sequence {
+        +animationGroups: AnimationGroup[]
+        +delay: number
+        +offset: number
+        +offsetEasing: function
+        +play()
+        +pause()
+        +reverse()
+        +cancel()
+        +onFinish()
+        -calculateOffsets()
+    }
+    
+    Sequence --|> AnimationGroup : extends
+    Sequence "1" --> "*" AnimationGroup : manages
+```
+
+## Part 1: @wix/motion Package Changes
+
+### 1.1 Create Sequence Class
+
+Create new file `packages/motion/src/Sequence.ts`:
+
+- Extend `AnimationGroup` to inherit the playback control API
+- Store `animationGroups: AnimationGroup[]` instead of `animations: Animation[]`
+- Add properties: `delay`, `offset`, `offsetEasing`
+- Implement `calculateOffsets()` method using the formula from spec:
+```typescript
+const last = indices.at(-1);
+indices.map(n => easing(n / last) * last * offset | 0);
+```
+
+- Override playback methods (`play`, `pause`, `reverse`, `cancel`) to delegate to child `AnimationGroup` instances
+- Apply calculated delay offsets to each effect's animation timing
+
+### 1.2 Add Sequence Types
+
+Update `packages/motion/src/types.ts`:
+
+```typescript
+export type SequenceOptions = {
+  delay?: number;           // default 0
+  offset?: number;          // default 100
+  offsetEasing?: string | ((p: number) => number);
+};
+```
+
+### 1.3 Export Sequence
+
+Update `packages/motion/src/index.ts` to export:
+
+- `Sequence` class
+- `SequenceOptions` type
+
+## Part 2: @eix/interact Package Changes
+
+### 2.1 Update Types
+
+Update `packages/interact/src/types.ts`:
+
+```typescript
+// New Sequence type
+export type Sequence = {
+  sequenceId?: string;    // for referencing reusable sequences
+  delay?: number;         // default 0
+  offset?: number;        // default 100
+  offsetEasing?: string | ((p: number) => number);
+  effects: (Effect | EffectRef)[];
+};
+
+// Update InteractConfig
+export type InteractConfig = {
+  effects: Record<string, Effect>;
+  sequences?: Record<string, Sequence>;  // NEW: reusable sequences
+  conditions?: Record<string, Condition>;
+  interactions: Interaction[];
+};
+
+// Update Interaction
+export type Interaction = InteractionTrigger & {
+  effects: ((Effect | EffectRef) & { interactionId?: string })[];
+  sequences?: Sequence[];  // NEW: inline sequences
+};
+```
+
+### 2.2 Update InteractCache
+
+Add sequences to the cache structure in `packages/interact/src/types.ts`:
+
+```typescript
+export type InteractCache = {
+  effects: { [effectId: string]: Effect };
+  sequences: { [sequenceId: string]: Sequence };  // NEW
+  conditions: { [conditionId: string]: Condition };
+  interactions: { /* existing structure */ };
+};
+```
+
+### 2.3 Update parseConfig Function
+
+Modify `packages/interact/src/core/Interact.ts`:
+
+1. Parse `config.sequences` into cache (similar to `config.effects`)
+2. Process `interaction.sequences` array:
+
+   - Resolve `sequenceId` references from `config.sequences`
+   - Process each effect within the sequence
+   - Generate unique IDs for sequence effects
+
+3. Track sequence membership for effects (needed for delay calculation)
+
+### 2.4 Update Effect Processing in add.ts
+
+Modify `packages/interact/src/core/add.ts`:
+
+1. When adding interactions, check if effects belong to a sequence
+2. Create `Sequence` instance from `@wix/motion` for grouped effects
+3. Apply calculated delay offsets based on effect index in sequence
+4. Handle sequence removal (when conditions change or elements removed)
+
+### 2.5 Handler Integration
+
+Update relevant trigger handlers (e.g., `viewEnter.ts`, `click.ts`) to:
+
+- Accept `Sequence` instances in addition to individual `AnimationGroup`
+- Properly manage sequence lifecycle (play, pause, cancel)
+
+## Part 3: Offset Calculation Implementation
+
+The offset calculation follows this algorithm:
+
+```typescript
+function calculateOffsets(
+  count: number,
+  offset: number,
+  easingFn: (t: number) => number
+): number[] {
+  if (count <= 1) return [0];
+  
+  const last = count - 1;
+  return Array.from({ length: count }, (_, i) => 
+    (easingFn(i / last) * last * offset) | 0
+  );
+}
+```
+
+The calculated offsets are added to each effect's existing `delay` property.
+
+## Key Implementation Notes
+
+1. **Initial Scope**: Only `keyframeEffect` and `namedEffect` types (not `customEffect`)
+2. **Skip `align` Property**: Per spec, do not implement the `align` property yet
+3. **Effect Removal**: When an effect is removed (e.g., condition no longer matches), recalculate delays for remaining effects
+4. **Sequence Removal**: Optimize to avoid recalculating when entire sequence is removed
+5. **No Element Target**: `Sequence` has no `key` property - targeting is per-effect
+
+## Testing Strategy
+
+1. Unit tests for `Sequence` class offset calculations
+2. Unit tests for easing function integration
+3. Integration tests for sequence parsing in Interact
+4. E2E tests for staggered animations with various easing functions
\ No newline at end of file
diff --git a/packages/interact/dev/DOCS_PLAN.md b/packages/interact/dev/DOCS_PLAN.md
deleted file mode 100644
index ae3b5eb2..00000000
--- a/packages/interact/dev/DOCS_PLAN.md
+++ /dev/null
@@ -1,463 +0,0 @@
-## Context Summary
-
-**Key Files, Functions, Types & Structures Involved:**
-
-1. **Main API Files:**
-   - `src/index.ts` - Public exports: `Interact` class, `add()`, `remove()` functions, and all types
-   - `src/interact.ts` - Core `Interact` class with static methods and instance management
-   - `src/types.ts` - Comprehensive type definitions (238 lines) including triggers, effects, configurations
-
-2. **Core Components:**
-   - `src/InteractElement.ts` - Custom element implementation with state management
-   - `src/utils.ts` - Utility functions for ID generation, CSS transition creation, media queries
-   - `src/handlers/` - Directory with 7 trigger handlers: `click`, `hover`, `viewEnter`, `viewProgress`, `pointerMove`, `animationEnd`, and `utilities`
-
-3. **Key Types & Interfaces:**
-   - `InteractConfig` - Main configuration object structure
-   - `Interaction` - Defines source, trigger, effects relationship
-   - `Effect` types - `TimeEffect`, `ScrubEffect`, `TransitionEffect`
-   - `TriggerType` - Union of supported triggers: 'hover', 'click', 'viewEnter', 'pageVisible', 'animationEnd', 'viewProgress', 'pointerMove'
-
-**Current Data Flow & Observed Patterns:**
-
-1. **Configuration-driven Architecture:** Users provide `InteractConfig` with effects, conditions, and interactions
-2. **Custom Element Integration:** Uses `<interact-element>` with `data-interact-key` attributes
-3. **Event Management:** Trigger handlers register/remove DOM event listeners
-4. **State Management:** Effects applied via CSS custom states or data attributes
-5. **Dependency on @wix/motion:** Integrates with Wix's motion library for animations
-6. **Dynamic List Management:** Built-in mutation observers for tracking list item additions/removals
-7. **Element Selection Priority:** Sophisticated selector system with `listContainer`, `selector`, and fallback to first child
-8. **Effect Cascading:** Condition-based effect layering similar to CSS cascade
-
-**Reference Implementations/Utilities Found:**
-
-- `packages/interact-playground/` - Comprehensive examples showing real usage patterns
-- Integration with `@wix/motion` for animation effects
-- Test suite (`__tests__/interact.spec.ts`) with 1194 lines of test cases showing API usage
-- Minimal existing documentation (current README is 9 lines with basic Yoshi links)
-
-**Potential Challenges, Risks & Considerations:**
-
-1. **Complex API Surface:** The package exports extensive types and configuration options
-2. **Browser Compatibility:** Uses modern APIs like `ElementInternals` with legacy fallbacks
-3. **Integration Complexity:** Requires understanding of custom elements, CSS states, and motion library
-4. **Configuration Structure:** Multi-level nested configuration can be overwhelming for new users
-5. **Missing Documentation:** Currently minimal documentation for a feature-rich package
-
----
-
-## Phase 2: Documentation Plan for @wix/interact Package
-
-Based on my comprehensive analysis, I'll create a detailed plan for writing comprehensive documentation for the `@interact` package.
-
-### **Stage 1: Foundation Documentation Structure**
-
-**What:** Create the core documentation framework and main README
-**Where:**
-
-- Update `packages/interact/README.md`
-- Create `packages/interact/docs/` directory structure
-  **Why:** Establish clear information architecture and entry points for different user types
-
-**Deliverables:**
-
-- Enhanced main README with quick start, installation, and overview
-- Documentation directory structure following monorepo patterns
-- Table of contents and navigation structure
-
-### **Stage 2: API Reference Documentation**
-
-**What:** Comprehensive API documentation for all public interfaces
-**Where:** `packages/interact/docs/api/` directory
-**Why:** Developers need detailed reference documentation for all classes, methods, and types
-
-**Deliverables:**
-
-- `Interact` class documentation (static methods, instance methods, properties)
-  - Document `Interact.forceReducedMotion` static property
-- Function documentation (`add()`, `remove()`)
-  - Add `addListItems(root, key, listContainer, elements)` documentation
-  - Add `removeListItems(elements)` documentation
-- Complete type definitions with examples
-- Configuration object schemas and validation rules
-- Custom element API (`<interact-element>`)
-  - Document `watchChildList(listContainer)` method
-- Element selection priority documentation
-  - `listContainer` + `selector` combinations
-  - Resolution order and fallback behavior
-
-### **Stage 3: Concept Guides**
-
-**What:** Educational content explaining core concepts and architecture
-**Where:** `packages/interact/docs/guides/` directory
-**Why:** Users need to understand the mental model and design philosophy
-
-**Deliverables:**
-
-- "Getting Started" tutorial with first interaction ✅ (complete)
-- "Understanding Triggers" - all 7 trigger types with examples (expand/complete)
-- "Effects and Animations" - integration with @wix/motion ✅ (complete)
-- "Configuration Structure" - nested config organization ✅ (complete)
-- "Custom Elements" - how interact-element works ✅ (complete)
-- "State Management" - CSS states vs data attributes (complete/expand)
-- "Conditions and Media Queries" - responsive interactions ✅ (complete)
-- **NEW: "Lists and Dynamic Content"** - Working with dynamic lists (HIGH PRIORITY)
-  - When to use `listContainer` vs multiple elements
-  - How mutation observers track list changes automatically
-  - Staggered animations for list items
-  - Performance considerations for large lists
-  - Examples: animated galleries, dynamic to-do lists, filtered product grids
-  - Add/remove item animations
-  - Infinite scroll integration patterns
-
-### **Stage 4: Usage Examples and Patterns**
-
-**What:** Practical examples and common patterns
-**Where:** `packages/interact/docs/examples/` directory
-**Why:** Developers learn best from working examples and common use cases
-
-**Deliverables:**
-
-- Prefer using examples of Effects using `keyframeEffect` over `namedEffect`
-- Basic examples for each trigger type (extracted from playground)
-- Advanced patterns (chaining animations, conditional effects)
-- Integration examples (with React, vanilla JS)
-- Performance optimization patterns
-- Common pitfalls and troubleshooting
-
-**NEW: Expanded Example Categories:**
-
-- **List Patterns** (HIGH PRIORITY):
-  - Staggered entrance animations for list items (10+ variations)
-  - Add/remove item animations with smooth transitions
-  - Sorting and filtering with animated transitions
-  - Infinite scroll integration patterns
-  - Grid-to-list layout transitions
-  - Drag-and-drop with visual feedback
-- **Selector Pattern Examples:**
-  - Complex component targeting strategies
-  - `listContainer` + `selector` combinations with real use cases
-  - Dynamic selector strategies for SPAs
-  - Nested component interactions
-  - Cross-element targeting patterns
-
-- **Effect Cascading Examples:**
-  - Responsive effect variations using effect-level conditions
-  - Mobile-first progressive enhancement patterns
-  - Graceful degradation with accessibility
-  - Theme-aware animations (light/dark mode)
-  - Performance-based effect selection
-
-- **Code Quality Standards:**
-  - All examples include TypeScript types
-  - Both vanilla JS and React versions
-  - Before/after HTML structure shown
-  - Common gotchas documented as comments
-  - Copy-paste ready with zero modifications needed
-
-### **Stage 5: Migration and Integration Guides**
-
-**What:** Guides for adopting and integrating the package
-**Where:** `packages/interact/docs/integration/` directory
-**Why:** Teams need guidance on how to adopt this into existing projects
-
-**Deliverables:**
-
-- Integration with different frameworks (React, vanilla JS, Vue, Angular, Svelte)
-- Migration from other animation libraries (GSAP, Framer Motion, CSS-only)
-  - Side-by-side comparison examples
-  - Feature mapping tables
-  - Migration checklists
-- Best practices for performance
-- Testing strategies for interactions
-- Debugging and development tools
-
-**NEW: Server-Side Rendering (SSR) Guide** (HIGH PRIORITY):
-
-- Hydration strategies and timing
-- When to initialize Interact (useEffect, componentDidMount, etc.)
-- Avoiding hydration mismatches
-- Next.js integration patterns
-  - App Router (React Server Components)
-  - Pages Router
-  - Client component boundaries
-- Remix integration
-- SvelteKit integration
-- Framework-specific list handling with SSR
-- Progressive enhancement patterns for SSR
-
-### **Stage 6: Advanced Topics**
-
-**What:** Deep-dive technical documentation
-**Where:** `packages/interact/docs/advanced/` directory
-**Why:** Power users and contributors need detailed technical information
-
-**Deliverables:**
-
-- Architecture overview and design decisions
-- Custom trigger development guide
-- Browser compatibility and polyfills
-- Performance optimization techniques
-- Contributing guidelines
-
-### **Implementation Priority Levels**
-
-Given that significant documentation already exists, prioritize work as follows:
-
-**🔴 High Priority (Complete First):**
-
-1. Lists and Dynamic Content guide (new, critical missing feature)
-2. List management API documentation (`addListItems`, `removeListItems`, `watchChildList`)
-3. SSR integration patterns (common pain point for modern frameworks)
-4. Element selection priority flowchart/decision tree
-5. List pattern examples (10+ variations)
-6. Complete "Understanding Triggers" guide (expand existing)
-7. Expand "State Management" guide with list-specific patterns
-
-**🟡 Medium Priority:** 8. Selector pattern examples (complex targeting strategies) 9. Effect cascading examples with conditions 10. Migration guides from GSAP/Framer Motion 11. Framework-specific integration examples (Vue, Angular) 12. Performance optimization patterns for lists 13. Troubleshooting sections for each major feature
-
-**🟢 Lower Priority:** 14. Advanced topics (custom trigger development) 15. Browser compatibility deep-dives 16. Contributing guidelines 17. Experimental features documentation
-
-### **Check-in Points:**
-
-1. **After High Priority Items:** Review with team and early adopters
-2. **After Stage 3:** Validate concept explanations with subject matter experts
-3. **After Stage 4:** Test examples with actual users/developers (must be copy-paste ready)
-4. **After Stage 5:** Validate SSR patterns with framework experts
-5. **After Stage 6:** Final review for completeness and accuracy
-
-### **Success Criteria:**
-
-**User Experience Metrics:**
-
-- ✅ New developers can get first interaction working in under 10 minutes
-- ✅ Developer can implement a staggered list animation in under 5 minutes
-- ✅ Zero ambiguity in element selection priority behavior (flowchart/decision tree)
-- ✅ All example code runs without modification (copy-paste ready)
-- ✅ SSR/hydration works first time for Next.js, Remix, SvelteKit
-
-**Documentation Coverage:**
-
-- ✅ All public APIs have comprehensive documentation with examples
-- ✅ All 7 trigger types fully documented with real-world examples
-- ✅ List management features completely documented (mutation observers, etc.)
-- ✅ Common use cases are covered with copy-paste examples
-- ✅ Advanced users can extend the system with custom triggers
-- ✅ Common framework integrations (React, Vue, Vanilla) all documented
-
-**Quality Standards:**
-
-- ✅ Performance best practices clearly stated for each pattern
-- ✅ Accessibility considerations documented for all interaction types
-- ✅ Browser compatibility clearly stated with workarounds
-- ✅ Troubleshooting section for each major feature
-- ✅ Migration paths from GSAP/Framer Motion documented
-- ✅ Documentation follows monorepo standards and patterns
-
-**Validation Tests:**
-
-- ✅ 5+ external developers test documentation and provide feedback
-- ✅ All code examples validated in TypeScript strict mode
-- ✅ Examples tested in React, Vue, and vanilla JS environments
-- ✅ SSR patterns validated in production-like environments
-
-### **Documentation Tools & Format:**
-
-- Markdown files for consistency with monorepo
-- TypeScript code examples with syntax highlighting
-- Interactive examples linking to playground
-- Auto-generated API docs from TypeScript comments
-- Clear cross-references between related concepts
-
----
-
-## **Identified Content Gaps & Specific Topics to Address**
-
-### **Critical Missing Documentation**
-
-1. **`listContainer` Feature** (🔴 High Priority)
-
-   ```typescript
-   // This pattern is used throughout the codebase but poorly documented
-   {
-     key: 'gallery',
-     listContainer: '.gallery-grid',     // Selects container
-     selector: '.gallery-item img',      // Selects within each child
-     trigger: 'hover',
-     effects: [/* ... */]
-   }
-   ```
-
-   **Required Coverage:**
-   - How `listContainer` works with mutation observers
-   - When to use vs multiple separate elements
-   - Performance implications of list vs individual elements
-   - Staggered animation patterns
-   - Memory management for large lists
-
-2. **Element Selection Priority** (🔴 High Priority)
-
-   **Resolution Order (needs clear flowchart):**
-
-   ```
-   1. listContainer specified?
-      → Yes: Match children using selector (or all immediate children)
-      → No: Continue to step 2
-
-   2. selector specified?
-      → Yes: querySelector within interact-element
-      → No: Use first child element (fallback)
-   ```
-
-   **Edge Cases to Document:**
-   - What happens when `listContainer` + `selector` matches nothing?
-   - Inheritance behavior from Interaction to Effect
-   - Selector specificity and combinators
-
-3. **Dynamic List Management** (🔴 High Priority)
-
-   **API Methods Missing Docs:**
-   - `watchChildList(listContainer: string): void`
-   - `addListItems(root, key, listContainer, elements)`
-   - `removeListItems(elements)`
-   - `_observers` WeakMap structure
-
-   **Behavior to Document:**
-   - Automatic mutation tracking setup
-   - When observers are created/destroyed
-   - Performance with rapid DOM changes
-   - Interaction with frameworks' virtual DOM
-
-4. **Effect Cascading with Conditions** (🟡 Medium Priority)
-
-   **Pattern to Document:**
-
-   ```typescript
-   // Effects cascade like CSS - last matching wins
-   effects: [
-     {
-       key: 'card',
-       effectId: 'slide-mobile',
-       conditions: ['mobile'], // Applies on mobile
-     },
-     {
-       key: 'card',
-       effectId: 'slide-tablet',
-       conditions: ['tablet'], // Overrides on tablet
-     },
-     {
-       key: 'card',
-       effectId: 'slide-desktop',
-       conditions: ['desktop'], // Overrides on desktop
-     },
-   ];
-   ```
-
-5. **SSR and Hydration** (🔴 High Priority)
-
-   **Framework Patterns Needed:**
-   - Next.js App Router (use client boundaries)
-   - Next.js Pages Router (useEffect timing)
-   - Remix (clientLoader vs useEffect)
-   - SvelteKit (onMount timing)
-   - Common hydration pitfalls
-
-6. **Performance Best Practices**
-
-   **Topics to Cover:**
-   - When to use `listContainer` (100+ items → use listContainer)
-   - Transform/opacity vs layout properties
-   - Event delegation considerations
-   - Memory implications of many interactions
-   - RequestAnimationFrame usage in handlers
-
-### **Documentation Quality Improvements Needed**
-
-1. **Add Troubleshooting Sections to Each Guide:**
-   - Common error messages and solutions
-   - Debug checklist with specific steps
-   - Browser DevTools integration tips
-   - Performance profiling guidance
-
-2. **Enhance All Code Examples:**
-
-   ```typescript
-   // ✅ GOOD: Complete, typed, copy-paste ready
-   import { Interact, type InteractConfig } from '@wix/interact';
-
-   const config: InteractConfig = {
-     interactions: [
-       {
-         key: 'my-button',
-         trigger: 'hover',
-         effects: [
-           /* ... */
-         ],
-       },
-     ],
-   };
-
-   // Initialize in useEffect for React
-   useEffect(() => {
-     const instance = Interact.create(config);
-     return () => {
-       // Cleanup if needed
-     };
-   }, []);
-   ```
-
-   **Every example should include:**
-   - TypeScript types
-   - Framework context (vanilla/React/Vue)
-   - Before/after HTML structure
-   - Common gotchas as comments
-
-3. **Add Migration Guides:**
-
-   | From                   | To @wix/interact      | Difficulty |
-   | ---------------------- | --------------------- | ---------- |
-   | GSAP Timeline          | Chained interactions  | Medium     |
-   | Framer Motion variants | Effect configurations | Easy       |
-   | CSS animations only    | Time effects          | Easy       |
-   | IntersectionObserver   | viewEnter trigger     | Easy       |
-   | ScrollTrigger          | viewProgress trigger  | Medium     |
-
-### **Quick Reference Additions Needed**
-
-1. **Decision Trees/Flowcharts:**
-   - When to use which trigger type
-   - Element selection priority flowchart
-   - listContainer vs multiple elements decision tree
-   - Effect type selection guide
-
-2. **Comparison Tables:**
-   - Trigger types feature comparison
-   - Effect types capabilities matrix
-   - Browser support matrix
-   - Framework integration approaches
-
-3. **Cheat Sheets:**
-   - Common patterns quick reference
-   - Selector syntax examples
-   - Configuration templates
-   - TypeScript type helpers
-
----
-
-## **Next Steps to Execute Plan**
-
-**Phase 1: High Priority Documentation (Week 1-2)**
-
-1. Create "Lists and Dynamic Content" guide
-2. Document list management APIs
-3. Create element selection flowchart
-4. Write SSR integration guide
-5. Create 10+ list animation examples
-
-**Phase 2: Medium Priority Completion (Week 3-4)** 6. Complete "Understanding Triggers" guide 7. Expand selector pattern examples 8. Add troubleshooting sections 9. Create migration guides 10. Framework integration examples
-
-**Phase 3: Quality & Polish (Week 5-6)** 11. Validate all examples in strict TypeScript 12. Test with external developers 13. Add performance profiling guides 14. Create quick reference cards 15. Final review and team feedback
-
----
-
-**Ready to begin? Start with High Priority Item #1: Lists and Dynamic Content guide.**
diff --git a/packages/interact/dev/LIST_PLAN.md b/packages/interact/dev/LIST_PLAN.md
deleted file mode 100644
index 1b0cbb53..00000000
--- a/packages/interact/dev/LIST_PLAN.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# General Context
-
-## Available Named Effects for List Animations
-
-**Entrance Effects (Time-based):**
-
-- `FadeIn`, `SlideIn`, `BounceIn`, `ExpandIn`, `RevealIn`, `BlurIn` - basic entrance animations
-- `ShuttersIn` - specifically supports `staggered: boolean` property for built-in staggering
-- `FlipIn`, `SpinIn`, `GlideIn`, `TurnIn` - dynamic entrance effects
-- `ShapeIn` - shape-based reveals with direction control
-
-**Scroll Effects (Progress-based):**
-
-- `FadeScroll`, `BlurScroll`, `SlideScroll`, `RevealScroll`, `ShuttersScroll`, `ShapeScroll` - revealing scroll-driven animations
-- `ParallaxScroll`, `MoveScroll`, `GrowScroll`, `ShrinkScroll`, `PanScroll`, `TurnScroll` - movement-based scroll effects
-- `SpinScroll`, `TiltScroll`, `ArcScroll`, `Spin3dScroll`, `TiltScroll` - visual transformation effects
-
-**Background Effects:**
-
-- `BgParallax`, `BgFade`, `BgPan`, `BgZoom` - container-level background animations
-
-## Current Architecture Patterns
-
-**ViewProgress ranges**: `entry`, `cover`, `exit`, `contain` for different scroll phases
-**Effect types**: `namedEffect`, `keyframeEffect`, `customEffect` for different complexity levels
-
-## Common List-based Scroll Animation Patters
-
-**Sticky Container List Animations** where the container is sticky inside a longer wrapper element, and animated using translation transforms while it's sticky inside the `contain` range
-**Sticky Container List Item Animations** where the container is sticky inside a longer wrapper element, and its individual items, or their content, are animated while it's sticky inside the `contain` range using different offsets per item
-**Sticky Item List Animations** where the items are sticky inside the container, and are animated into view, or in and out of view, using various effects like transforms, clip-path, or opacity, while using either the container as the timeline with different ranges, or each item uses itself as the timeline with any range, depending on the effect
-**Sticky Item List Items' Contents Animations** where either the container or the items are sticky, and content inside the items use their containing item as the timeline for animations applied to them
-**Animating while content is stuck in view** uses the `contain` range
-**Animating while content enters view** uses the `entry` range
-**Animating while content exits view** uses the `exit` range
-
----
-
-# **LIST SCROLL ANIMATION RULES GENERATION PLAN**
-
-## **Stage 1: Core List Animation Rule Categories (Foundation)**
-
-### **1.1 Sticky Container List Animations**
-
-- **Objective**: Create rules for animations applied to list containers that are sticky-positioned within their wrapper
-- **Scope**: Container-level effects during sticky scroll phases
-- **Key Patterns**:
-  - Container horizontal sliding during sticky phase
-  - Container parallax effects during sticky phase
-  - Container reveal transitions
-  - Background transformations synchronized with scroll
-
-### **1.2 Sticky Item List Animations**
-
-- **Objective**: Generate rules for animations on individual list items that are sticky-positioned within the container
-- **Scope**: Item-level effects as items enter/exit sticky positioning
-- **Key Patterns**:
-  - Item entrance/exit animations
-  - Progressive item reveals
-  - Item transformation during sticky phases
-
-### **1.3 Sticky Item List Content Animations**
-
-- **Objective**: Generate rules for animations on content of individual list items that are sticky-positioned within the container
-- **Scope**: Coordinated animations with calculated delays
-- **Key Patterns**:
-  - Entry staggering (sequential reveals)
-  - Exit staggering (sequential dismissals)
-  - Wave-like animation propagation
-
-## **Stage 2: Named Effect Rule Patterns (20 Rules)**
-
-### **2.1 Container-Level Named Effects (5 Rules)**
-
-- **Container Parallax Rule**: `BgParallax`, `BgReveal` for sticky container backgrounds
-- **Container Transform Rule**: `PanScroll` for container-level horizontal transformation
-- **Container Background Rule**: `BgPan`, `BgSkew` for dynamic backgrounds
-
-### **2.2 List Item Named Effects (10 Rules)**
-
-- **Item Entrance/Exit Rules**: `FadeScroll`, `SlideScroll`, `ShapeScroll`, `RevealScroll`, `MoveScroll`, `ShuttersScroll` for item reveals
-- **Item Transformation Rules**: `GrowScroll`, `ShrinkScroll`, `SpinScroll`, `ArcScroll` for item scaling/rotation
-
-### **2.3 Content-Level Named Effects (5 Rules)**
-
-- **Content Reveal Rules**: `RevealScroll`, `FadeScroll` for text/image reveals within items
-- **Content Motion Rules**: `TiltScroll`, `FlipScroll` for content dynamics
-- **Content Progressive Rules**: Using entrance effects (`GrowScroll`, `FadeScroll`) triggered by scroll progress
-- **Content Interactive Rules**: Combined hover + scroll effects for rich interactions
-
-## **Stage 3: Keyframe Effect Rule Patterns (15 Rules)**
-
-### **3.1 Custom Container Keyframes (5 Rules)**
-
-- **Multi-Property Container**: Combined transform, opacity, filter effects
-- **Responsive Container**: Different keyframes for mobile vs. desktop
-- **Timed Container**: Sequential keyframe phases during sticky periods
-- **Background Container**: Complex background position/filter combinations
-- **Layout Container**: Subtle spacing/padding adjustments during scroll
-
-### **3.2 Custom Item Keyframes (7 Rules)**
-
-- **Complex Item Entrance**: Multi-property entrance with unique timing
-- **Item Position Flow**: Advanced positioning with perspective effects
-- **Item Content Coordination**: Synchronizing item wrapper with content animations
-- **Item Responsive**: Adaptive keyframes based on screen size
-- **Item Interaction**: Hover-enhanced scroll effects
-- **Item Exit Sequence**: Complex multi-stage exit animations
-- **Item State Transition**: Animations between different list states
-
-### **3.3 Custom Content Keyframes (3 Rules)**
-
-- **Text Progressive**: Letter-by-letter or word-by-word reveals
-- **Image Complex**: Multi-layer image animations with masks/filters
-- **Media Synchronized**: Video/audio content synchronized with scroll
-
-## **Stage 4: Custom Effect Rule Patterns (12 Rules)**
-
-### **4.1 Stagger Calculation Rules (4 Rules)**
-
-- **Linear Stagger**: Even delays across all items `(index / total) * maxDelay`
-- **Exponential Stagger**: Accelerating delays `Math.pow(index / total, 2) * maxDelay`
-- **Wave Stagger**: Sine wave-based delays for organic feeling
-- **Reverse Stagger**: Reverse-order animations for exit effects
-
-### **4.2 Dynamic Content Rules (4 Rules)**
-
-- **Counter Animation**: Scroll-driven number counting within items
-- **Progress Tracking**: Visual progress indicators within list context
-- **Interactive Data**: Data visualization updates during scroll
-- **Dynamic Text**: Text content that changes based on scroll position
-
-### **4.3 Complex Coordination Rules (4 Rules)**
-
-- **Multi-Layer Lists**: Coordinating background, item, and content layers
-- **Cross-Item Effects**: Items affecting neighboring items during animation
-- **Conditional Staggering**: Different stagger patterns based on conditions
-- **Adaptive Performance**: Reducing complexity based on list length/performance
-
-## **Stage 5: Configuration Factory Patterns (8 Factories)**
-
-### **5.1 List Type Factories (4 Factories)**
-
-- **`createStickyListConfig`**: For sticky-positioned list containers
-- **`createStickyItemConfig`**: For lists with sticky-positioned items
-- **`createScrollListConfig`**: For standard scroll-through lists
-- **`createInfiniteListConfig`**: For infinite scroll list patterns
-
-### **5.2 Animation Style Factories (4 Factories)**
-
-- **`createStaggeredListConfig`**: Parameterized stagger generation
-- **`createParallaxListConfig`**: Multi-layer parallax list effects
-- **`createProgressiveListConfig`**: Progressive reveal/hide patterns
-- **`createInteractiveListConfig`**: Combined hover/scroll list interactions
-
-## **Stage 6: Integration & Responsive Patterns (5 Rules)**
-
-### **6.1 Responsive Adaptation (3 Rules)**
-
-- **Mobile-First Lists**: Simplified animations for touch devices
-- **Desktop Enhancement**: Complex effects for desktop hover/scroll
-- **Performance Scaling**: Adaptive complexity based on device capabilities
-
-### **6.2 Accessibility & Performance (2 Rules)**
-
-- **Reduced Motion Support**: Alternative patterns for `prefers-reduced-motion`
-- **Performance Optimization**: Hardware acceleration and efficient property usage
-
-## **Stage 7: Documentation & Examples (Final)**
-
-### **7.1 Comprehensive Documentation**
-
-- Complete rule documentation with examples
-- Use case guides for different list scenarios
-- Performance and accessibility guidelines
-
-### **7.2 Real-World Example Configurations**
-
-- E-commerce product lists
-- Content feed animations
-- Navigation menu dynamics
-- Dashboard widget lists
-
----
-
-# **Success Criteria**
-
-1. **Comprehensive Coverage**: Rules address all major list animation scenarios (container, items, content)
-2. **Performance Optimized**: All rules use hardware-accelerated properties and efficient patterns
-3. **Responsive Ready**: Rules include mobile/desktop variations and adaptive complexity
-4. **Developer Friendly**: Configuration factories reduce boilerplate and enable quick implementation
-5. **Accessibility Compliant**: All rules respect motion preferences and performance constraints
-
----
-
-# **Implementation Approach**
-
-The plan follows a layered approach:
-
-- **Foundation** (Stage 1): Core categories and architectural patterns
-- **Named Effects** (Stage 2): Leveraging existing @wix/motion effects with list-specific patterns
-- **Custom Keyframes** (Stage 3): Precise control for unique list behaviors
-- **Advanced Custom** (Stage 4): JavaScript-powered complex interactions
-- **Factories** (Stage 5): Reusable configuration generators
-- **Integration** (Stage 6): Responsive and accessibility considerations
-- **Documentation** (Stage 7): Complete implementation guidance
-
-Each stage builds upon previous stages, ensuring comprehensive coverage while maintaining practical usability for developers implementing list scroll animations.
-
----
-
-**Switch to agent mode and type execute (or execute stage 1) to begin.**
diff --git a/packages/interact/dev/RULES_PLAN.md b/packages/interact/dev/RULES_PLAN.md
deleted file mode 100644
index 4f51c477..00000000
--- a/packages/interact/dev/RULES_PLAN.md
+++ /dev/null
@@ -1,288 +0,0 @@
-## Phase 1: Context Summary
-
-**Tools Utilized & Key Discoveries:**
-
-- Used `read_file` on core files (`interact.ts`, `types.ts`, `InteractElement.ts`, `utils.ts`) to understand the main API structure and configuration patterns
-- Used `list_dir` to explore package structure and handlers organization, discovering modular trigger system
-- Used `file_search` to find examples documentation with common usage patterns
-- Used `read_file` on motion types and handler implementations to understand effect integration patterns
-
-**Key Files, Functions, Types & Structures Involved:**
-
-1. **Core API**: `Interact` class with static `create()` method, `InteractConfig` as main configuration object
-2. **Core Types**:
-   - `InteractConfig` structure: `{effects, conditions?, interactions}`
-   - `Interaction`: `{key, selector? listContainer?, trigger, params?, conditions?, effects}`
-   - Effect types: `TimeEffect`, `ScrubEffect`, `TransitionEffect` with union `Effect`
-   - `TriggerType`: 7 types (`hover`, `click`, `viewEnter`, `pageVisible`, `animationEnd`, `viewProgress`, `pointerMove`)
-3. **Custom Element**: `<interact-element>` with required `data-interact-key` attribute
-4. **Handler System**: Modular trigger handlers in `/src/handlers/` with consistent `add/remove` pattern
-5. **Motion Integration**: Named effects from `@wix/motion` (FadeIn, SlideIn, etc.) and custom keyframe effects
-
-**Current Data Flow & Observed Patterns:**
-
-- Configuration flows through: `InteractConfig` → `parseConfig()` → `InteractCache` → Element registration → Handler binding
-- Two effect definition patterns: inline effects vs reusable effects with `effectId` references
-- Conditions system enables responsive/conditional interactions using media queries
-- Custom element wrapper manages DOM lifecycle and state via CSS custom states
-- Template patterns evident in documentation for common use cases
-
-**Reference Implementations/Utilities Found:**
-
-- Rich examples in `/docs/examples/README.md` showing entrance animations, hover effects, scroll animations
-- Template structures demonstrating configuration patterns
-- Modular handler architecture with shared utilities (`generateId`, `createTransitionCSS`)
-- Type-safe configuration patterns with comprehensive TypeScript definitions
-
-**Potential Challenges, Risks & Considerations:**
-
-- Complex discriminated union types require careful rule generation to maintain type safety
-- Multiple effect types (Time/Scrub/Transition) need different generation strategies
-- Handler registration lifecycle and cleanup patterns must be preserved
-- Integration with motion library's NamedEffect types needs consideration for effect selection
-- Custom element key matching requirements between configuration and DOM
-- **List-based interactions**: `listContainer` with dynamic mutation observer behavior needs specialized rules
-- **Element targeting complexity**: Priority order (listContainer → selector → firstElementChild) and inheritance patterns
-- **Selector non-inheritance**: Unlike `key`, `selector` and `listContainer` are NOT inherited from Interaction to Effect level
-- **Pointer-driven animations**: hitArea, centeredToTarget, symmetric/anti-symmetric patterns need careful handling
-
----
-
-## Phase 2: Formulate a Plan
-
-Based on the comprehensive exploration, here's a detailed plan for creating rules to generate Interact library code:
-
-### Stage 1: Core Configuration Generation Rules
-
-**What**: Rules for generating basic `InteractConfig` objects and `Interaction` structures per trigger type
-**Where**: Focus on all 7 trigger types with their most common patterns and use cases
-**Why**: Each trigger type has distinct patterns, parameters, and typical effects that warrant specialized rules
-**How**: Create templates for interactions of specific types with placeholders, without actual effect content
-
-**Sub-stages (each in separate files):**
-
-#### Stage 1.1: Hover Trigger Rules (`hover-rules.md`)
-
-- Rule for hover effect configuration with state management pattern
-- Rule for hover enter/leave animations pattern
-- Rule for pointer-based hover interactions with alternate pattern
-- Rule for pointer-based hover interactions with repeat pattern
-- RUle for pointer-based hover interactions with play/pause pattern
-
-#### Stage 1.2: Click Trigger Rules (`click-rules.md`)
-
-- Rule for click effect configuration with TimeEffects and alternate pattern
-- Rule for click effect configuration with TimeEffects and state pattern
-- Rule for click effect configuration with TimeEffects and repeat pattern
-- Rule for click effect configuration with state toggles and TransitionEffects pattern
-
-#### Stage 1.3: ViewEnter Trigger Rules (`viewenter-rules.md`)
-
-- Rule for entrance animation configuration with once type pattern
-- Rule for entrance animation configuration with repeat type and separate source and target pattern
-- Rule for entrance animation configuration with alternate type and separate source and target pattern
-- Rule for loop animation configuration with state type pattern
-- Rule for threshold and viewport intersection parameters pattern
-- Rule for staggered entrance animations pattern
-
-#### Stage 1.4: ViewProgress Trigger Rules (`viewprogress-rules.md`)
-
-- Rule for range-based parallax/continuous animation control with namedEffects pattern
-- Rule for range-based entry animation control with namedEffects pattern
-- Rule for range-based exit animation control with namedEffects pattern
-- Rule for range-based parallax/continuous animation control with keyframeEffects pattern
-- Rule for range-based entry animation control with keyframeEffects pattern
-- Rule for range-based exit animation control with keyframeEffects pattern
-- Rule for range-based parallax/continuous animation control with customEffects pattern
-- Rule for range-based entry animation control with customEffects pattern
-- Rule for range-based exit animation control with customEffects pattern
-
-#### Stage 1.5: PointerMove Trigger Rules (`pointermove-rules.md`)
-
-- Rule for hit area configuration (`root` vs `self`) with appropriate use cases
-- Rule for centering range to animation target using `centeredToTarget` configuration
-- Rule for symmetric pointer effects (same animation in both directions)
-- Rule for anti-symmetric pointer effects (inverted animation based on direction)
-- Rules for pointer-based effects of single elements with namedEffect
-- Rules for pointer-based parallax effects of a group of elements with namedEffect
-
-#### Stage 1.6: AnimationEnd Trigger Rules (`animationend-rules.md`)
-
-- Rule for configuration of entrance and loop animations chaining pattern
-- Rule for configuration of entrance animations chaining of different elements pattern
-
-#### Stage 1.7: PageVisible Trigger Rules (`pagevisible-rules.md`)
-
-- Rule for page load animations
-- Rule for global state management
-- Rule for one-time initialization effects
-
-#### Stage 1.8: List-Based Interaction Rules (`scroll-list-rules.md`)
-
-- Rule for `listContainer` with automatic child detection (targets all immediate children)
-- Rule for `listContainer` + `selector` for targeting specific elements within list items
-- Rule for gallery/grid interaction patterns
-- Rule for performance optimization with large lists
-
-**Common Deliverables:**
-
-- Template for base `InteractConfig` structure validation
-- Shared utilities for key generation and validation
-- Common effect pattern templates
-
-### Stage 2: Element Targeting and Selector Rules
-
-**What**: Rules for element targeting using `key`, `selector`, and `listContainer`
-**Where**: Both Interaction and Effect levels with proper inheritance/non-inheritance patterns
-**Why**: Element targeting is complex with priority order and non-obvious inheritance behavior
-
-**Deliverables:**
-
-- Rule for element targeting priority: listContainer → selector → firstElementChild
-- Rule for when `key` defaults from Interaction to Effect (when Effect.key is omitted)
-- Rule for selector non-inheritance: Effect.selector must be explicit (not inherited from Interaction.selector)
-- Rule for listContainer non-inheritance: Effect.listContainer must be explicit
-- Rule for cross-element targeting (source ≠ target) patterns
-- Rule for self-targeting patterns (source = target or Effect.key omitted)
-- Rule for nested selector patterns within custom elements
-- Rule for combining listContainer + selector for list item children
-
-### Stage 3: Effect Generation Rules
-
-**What**: Rules for generating the three effect types with appropriate defaults
-**Where**: Time effects (most common), transition effects, scrub effects
-**Why**: Effects are the core value-add and have clear patterns from documentation
-
-**Deliverables:**
-
-- Rule for TimeEffect with named effects (FadeIn, SlideIn, etc.)
-- Rule for TimeEffect with custom keyframes
-- Rule for TransitionEffect with CSS properties
-- Rule for ScrubEffect with scroll/pointer triggers
-- Effect selection helper based on trigger type
-- Rule for inline effects vs reusable effects with `effectId` references
-
-### Stage 4: Custom Element and DOM Integration Rules
-
-**What**: Rules for generating proper `<interact-element>` markup and key management
-**Where**: HTML/JSX generation with proper `data-interact-key` attributes
-**Why**: Required for library function and common source of integration errors
-
-**Deliverables:**
-
-- Rule for custom element wrapper generation
-- Rule for element key generation and validation (matching data-interact-key to config key)
-- Rule for React/JSX integration patterns
-- Rule for Vue/Angular custom element usage
-- Rule for ensuring at least one child element exists
-
-### Stage 5: Advanced Configuration Rules
-
-**What**: Rules for conditions, effect references, and complex patterns
-**Where**: Responsive interactions, reusable effects, multistep animations
-**Why**: Enables scaling beyond basic use cases
-
-**Deliverables:**
-
-- Rule for media query conditions (device size, orientation, reduced motion, dark mode)
-- Rule for container query conditions
-- Rule for reusable effect patterns with `effectId`
-- Rule for animation sequences and chaining (using animationEnd trigger)
-- Rule for responsive/conditional interactions with cascading effects
-- Rule for combining multiple conditions with AND logic
-
-### Stage 6: Type Safety and Validation Rules
-
-**What**: Rules ensuring generated code maintains TypeScript safety
-**Where**: Configuration validation, effect property validation, trigger parameter validation
-**Why**: Critical for developer experience and catching errors early
-
-**Deliverables:**
-
-- Type validation rules for each configuration pattern
-- Runtime validation helpers
-- Error message generation for common mistakes
-- IDE integration patterns
-- Discriminated union handling for Effect types
-- Parameter validation based on trigger type
-
-### Stage 7: Integration and Testing Rules
-
-**What**: Rules for testing generated interactions and integration patterns
-**Where**: Unit test generation, E2E test patterns, performance validation
-**Why**: Ensures generated code works correctly and performs well
-
-**Deliverables:**
-
-- Test case generation for interactions
-- Performance validation rules
-- Integration pattern validation
-- Documentation generation for generated code
-- Browser compatibility testing patterns
-- Accessibility testing for animations (reduced motion)
-
----
-
-**Check-in Points:**
-
-- After Stage 1: Validate all 7 trigger types generate correct configuration patterns
-- After Stage 2: Verify element targeting rules handle all selector/listContainer combinations
-- After Stage 3: Ensure effect generation covers all three types (Time/Scrub/Transition)
-- After Stage 4: Verify DOM integration works correctly with proper key matching
-- After Stage 5: Test condition cascading and responsive patterns
-- After Stage 6: Ensure type safety is maintained throughout all generated code
-- Final: Comprehensive testing of all rule combinations and edge cases
-
-**Success Criteria:**
-
-- ✅ Generated code passes TypeScript compilation with no errors
-- ✅ Generated interactions work as expected in browser
-- ✅ Rules cover 100% of documented example patterns
-- ✅ All 7 trigger types have comprehensive rule coverage
-- ✅ Element targeting rules correctly handle priority order (listContainer → selector → firstElementChild)
-- ✅ Selector and listContainer non-inheritance is properly enforced
-- ✅ List-based interactions with mutation observers work correctly
-- ✅ Pointer-driven animations support both symmetric and anti-symmetric patterns
-- ✅ Conditions system supports media queries, container queries, and cascading
-- ✅ AnimationEnd trigger enables proper animation chaining
-- ✅ Integration with existing tooling (IDE, linting, testing)
-- ✅ Generated code respects accessibility (reduced motion) preferences
-- ✅ Performance patterns for large lists and frequent updates are included
-
----
-
-## Priority Implementation Order
-
-Based on current progress and critical gaps identified:
-
-### **Phase 1: Foundation (Completed ✅)**
-
-- Stage 1.1-1.3: Basic triggers (hover, click, viewEnter) ✅
-- Stage 1.4: ViewProgress rules ✅
-- Stage 1.5: PointerMove rules ✅
-
-### **Phase 2: Critical Gaps (HIGH PRIORITY)**
-
-- **Stage 1.8**: List-Based Interaction Rules - Essential for galleries and grids
-- **Stage 2**: Element Targeting Rules - Critical for understanding selector behavior
-- **Stage 1.6-1.7**: AnimationEnd and PageVisible triggers
-
-### **Phase 3: Effect Completeness (MEDIUM PRIORITY)**
-
-- **Stage 3**: Complete effect generation rules with all three types
-- Inline vs reusable effect patterns
-- Effect cascading with conditions
-
-### **Phase 4: Integration & Advanced (LOWER PRIORITY)**
-
-- **Stage 4**: Custom element and DOM integration
-- **Stage 5**: Advanced configuration with conditions
-- **Stage 6-7**: Type safety, validation, and testing
-
-### **Next Immediate Actions:**
-
-1. Create `scroll-list-rules.md` with listContainer patterns
-2. Create element targeting guide explaining selector inheritance/non-inheritance
-3. Enhance pointer-move rules with symmetric/anti-symmetric patterns
-4. Add animationEnd chaining patterns
-5. Document performance optimization for large lists
diff --git a/packages/interact/dev/VIEW_ENTER_SPEC.md b/packages/interact/dev/VIEW_ENTER_SPEC.md
deleted file mode 100644
index ac3243c0..00000000
--- a/packages/interact/dev/VIEW_ENTER_SPEC.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# `viewEnter` Beyond `type: 'once'`
-
-This is specification document for implementing the rest of the values for `type` property of `params` for `trigger: 'viewEnter'`.
-
-- Currently only `type: once` is implemented for the `viewEnter` trigger
-- Other types that should also be implemented are: `alternate`, `repeat`, and `state`
-- The initial flow for Interactions with these types are the same as for `once`
-- These types should also track when the element exits the range \- `isIntersecting: false`
-- We’ll start by using a default exit observer for each type \- without providing an API to specify its options
-- We need to make sure we [persist](https://developer.mozilla.org/en-US/docs/Web/API/Animation/persist) the animation on these types.
-
-# `alternate`
-
-- When exiting the range the animation should be reversed.
-- On subsequent re-entry the animation should be reversed (not play, since it was reversed on last exit)
-- By default we can use the same observer as the one for entry.
-
-# `repeat`
-
-- By default we can use a separate observer that watches when the element is completely out of view
-- When exiting the range the animation should be paused and set its progress to 0 (like “stop”).
-- On subsequent re-entry the animation should be played from 0
-
-# `state`
-
-- By default we can use a separate observer that watches when the element is completely out of view
-- When exiting the range the animation should be paused.
-- On subsequent re-entry the animation should be resumed (calling `.play()` should resume it)
diff --git a/packages/interact/dev/sequences-spec.md b/packages/interact/dev/sequences-spec.md
new file mode 100644
index 00000000..68f541f0
--- /dev/null
+++ b/packages/interact/dev/sequences-spec.md
@@ -0,0 +1,166 @@
+# Sequences
+
+This is a proposal for supporting sequenced effects (also known as “timelines”) for Interact that can be declared using the Config.
+
+# Technical Design
+
+## Config spec
+
+* A Sequence is a list of `Effect`s managed by a single trigger/timeline.
+* `Effect`s in a `Sequence` are applied in their specified order inside `Interaction.sequence.effects`.
+* Reusable `Sequence`s will be declared using a new `InteractConfig.sequences` property, which is a map of Sequence declarations by a unique key.
+* `Sequence`s can be defined on an `Interaction` using a new `Interaction.sequences` property which is a list of `Sequence`s.
+* Each Sequence will have an `effects` property which contains its child Effects.
+* A `Sequence` does not have a `key` property, nor any of the other element targeting-related properties, since it by itself is not tied to an element.
+* The `Effect`s inside a `Sequence` are the objects that define that related target.
+
+## The new `sequences` property
+
+```ts
+/**
+ * Reusable Sequence declarations on the InteractConfig top-level
+ */
+type InteractConfig = {
+  sequences: {[key: string]: Sequence};
+  //...
+}
+
+/**
+ * Sequence definitions on each Interaction
+ * Like `effects`, can either reference a declaration using sequenceId
+ * Or specify values inline, or both and inlined overrides referenced declarations
+ */
+type Interaction = {
+  sequences: Sequence[];
+  //...
+};
+
+/**
+ * The Sequence type
+ */
+type Sequence = {
+  delay: number; // default 0
+  offset: number; // default 100
+  offsetEasing: string | (p: number) => number; // linear
+  align: 'start' | 'end' | 'sequence' | 'sequence-reversed';
+  effects: Effect[]
+};
+```
+
+## The `Sequence.delay`
+
+* A fixed offset of milliseconds to delay the playing of the entire Sequence  
+* Defaults to `0`
+
+## The `Sequence.offset`
+
+* A fixed amount of milliseconds to multiply the result of the `easing` function  
+* Defaults to `100`
+
+## The `Sequence.offsetEasing`
+
+* Either a JS function or a valid CSS `easing` value, or a valid `easing` name in `@wix/motion` library  
+  * A JS function takes a `number` from 0 to 1\.  
+  * An `easing` value, either valid from CSS, or in `@wix/motion`, will be translated to the corresponding function in JS or a CSS `calc()`.  
+* The mapping of each offset using the easing function as done as follows:
+
+```javascript
+// `indices` is the array of indices from 0 to Length-1
+// `easing` is the easing function
+// `offset` is the `sequence.offset` property
+const last = indices.at(-1);
+indices.map(n => easing(n / last) * last * offset | 0) // | 0 is basically flooring
+```
+
+### Easing examples
+
+```javascript
+const items = [0, 1, 2, 3, 4]
+const offset = 200
+
+const linear = t => t
+// 0, 200, 400, 300, 400
+
+const quadIn = t => t ** 2
+// 0, 50, 200, 450, 800
+
+const sinOut = t => Math.sin(t * Math.PI / 2)
+// 0, 306, 565, 739, 800
+```
+
+## The `Sequence.align`
+
+* **Ignore for now \- DO NOT implement**  
+* Specifies how to align the Effects inside the Sequence:  
+  * `start` aligns to the beginning  
+  * `end` aligns to the end  
+  * `sequence` aligns each effect’s start to the end of its preceding effect  
+  * `sequence-reverse` is same as `sequence` but starts from the last effect backwards
+
+# Effect on Effects’ `delay`
+
+* In initial phase this feature should only apply to `keyframeEffect`s and `namedEffect`s \- where we generate Web or CSS animations  
+* The result of calculated offset should be added to the Effect’s specified `delay`  
+* If an Effect is removed (e.g. when an Effect’s `condition` stops matching the state of its environment and needs to be removed) it should propagate to the corresponding Sequence to update the calculated delays  
+* If an entire Sequence is removed we should try to remove it completely without a significant overhead of propagating each Effect being removed.
+
+# Implementation
+
+* Create a new `Sequence` class in `@wix/motion` package that manages a list of `AnimationGroup` instances.
+* A `Sequence` instance manages its own playback, similar to `AnimationGroup`, only difference is its `animations` property holds `AnimationGroup` instances. Therefor, it should extend `AnimationGroup` and have a similar API.
+* Note that `Sequence` does not have a `target`, so all of its API endpoints that involve an element target should be written accordingly, or not exist if not relevant.
+* In the `@eix/interact` package `Sequence`s will be created from an `InteractConfig` for every declaration inside `Interaction.sequences`.
+
+# Appendix
+
+## A CSS solution in a futuristic world where CSS math functions are widely supported
+
+* The index of each Effect in the Sequence  and count of Effects in the Sequence are set on each target element.  
+* Generated `animation-delay` should be a `calc()` that includes the effect’s `delay` \+ the generated staggering offset as follows:
+
+```css
+@property --interact-seq-c {
+  syntax: "<number>";
+  initial-value: 1;
+  inherits: false;
+}
+
+@property --interact-seq-i {
+  syntax: "<number>";
+  initial-value: 0;
+  inherits: false;
+}
+
+.target {
+  --_interact-delay: calc(pow(var(--interact-seq-i) / var(--interact-seq-c), 2)); /* quadIn - this is here for readability, don't actually have to add as a separate property */
+  animation-delay: calc(effectDelay + var(--_interact-delay) * var(--interact-seq-c) * <sequence.offset>);
+}
+```
+
+```javascript
+// According to initial design
+{
+   interactions: [{
+     trigger: 'viewEnter',
+     sequence: {
+       offset: 150,
+       offsetEasing: 'ease-out'
+     },
+     effects: [...]
+   }]
+}
+
+// According to alternative design
+{
+   interactions: [{
+     trigger: 'viewEnter',
+     sequences: [{
+       offset: 150,
+       offsetEasing: 'ease-out',
+       effects: [{
+	  
+       }]
+     }]
+   }]
+}
+```

From ddf46333942646e6021e32aed9cb8eea67b08a9e Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Sun, 25 Jan 2026 18:51:39 +0200
Subject: [PATCH 02/29] Fixed review comments

---
 .../sequence_feature_implementation_84c01c97.plan.md   |  2 +-
 packages/interact/dev/sequences-spec.md                | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
index de7c5cff..ce2fd76f 100644
--- a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
+++ b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
@@ -108,7 +108,7 @@ export type Sequence = {
   sequenceId?: string;    // for referencing reusable sequences
   delay?: number;         // default 0
   offset?: number;        // default 100
-  offsetEasing?: string | ((p: number) => number);
+  offsetEasing?: string | ((p: number) => number); // default linear
   effects: (Effect | EffectRef)[];
 };
 
diff --git a/packages/interact/dev/sequences-spec.md b/packages/interact/dev/sequences-spec.md
index 68f541f0..8fb1123a 100644
--- a/packages/interact/dev/sequences-spec.md
+++ b/packages/interact/dev/sequences-spec.md
@@ -39,11 +39,11 @@ type Interaction = {
  * The Sequence type
  */
 type Sequence = {
-  delay: number; // default 0
-  offset: number; // default 100
-  offsetEasing: string | (p: number) => number; // linear
-  align: 'start' | 'end' | 'sequence' | 'sequence-reversed';
-  effects: Effect[]
+  delay?: number; // default 0
+  offset?: number; // default 100
+  offsetEasing?: string | (p: number) => number; // linear
+  effects: Effect[];
+  sequenceId: string;
 };
 ```
 

From d3d95643d446a24ff837847a9af5b8c9d5734946 Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Sun, 25 Jan 2026 18:54:19 +0200
Subject: [PATCH 03/29] Fixed type

---
 .cursor/plans/sequence_feature_implementation_84c01c97.plan.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
index ce2fd76f..36c6641c 100644
--- a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
+++ b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
@@ -105,7 +105,7 @@ Update `packages/interact/src/types.ts`:
 ```typescript
 // New Sequence type
 export type Sequence = {
-  sequenceId?: string;    // for referencing reusable sequences
+  sequenceId: string;    // for referencing reusable sequences
   delay?: number;         // default 0
   offset?: number;        // default 100
   offsetEasing?: string | ((p: number) => number); // default linear

From d96d47d9e84c10ae572ce1c3766679d3acf91c2f Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Sun, 25 Jan 2026 19:49:25 +0200
Subject: [PATCH 04/29] Fixed format

---
 ...ce_feature_implementation_84c01c97.plan.md | 34 +++----
 packages/interact/dev/sequences-spec.md       | 88 ++++++++++---------
 2 files changed, 63 insertions(+), 59 deletions(-)

diff --git a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
index 36c6641c..6f0e2977 100644
--- a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
+++ b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
@@ -41,7 +41,7 @@ classDiagram
         +cancel()
         +onFinish()
     }
-    
+
     class Sequence {
         +animationGroups: AnimationGroup[]
         +delay: number
@@ -54,7 +54,7 @@ classDiagram
         +onFinish()
         -calculateOffsets()
     }
-    
+
     Sequence --|> AnimationGroup : extends
     Sequence "1" --> "*" AnimationGroup : manages
 ```
@@ -71,7 +71,7 @@ Create new file `packages/motion/src/Sequence.ts`:
 - Implement `calculateOffsets()` method using the formula from spec:
 ```typescript
 const last = indices.at(-1);
-indices.map(n => easing(n / last) * last * offset | 0);
+indices.map((n) => (easing(n / last) * last * offset) | 0);
 ```
 
 - Override playback methods (`play`, `pause`, `reverse`, `cancel`) to delegate to child `AnimationGroup` instances
@@ -83,8 +83,8 @@ Update `packages/motion/src/types.ts`:
 
 ```typescript
 export type SequenceOptions = {
-  delay?: number;           // default 0
-  offset?: number;          // default 100
+  delay?: number; // default 0
+  offset?: number; // default 100
   offsetEasing?: string | ((p: number) => number);
 };
 ```
@@ -105,9 +105,9 @@ Update `packages/interact/src/types.ts`:
 ```typescript
 // New Sequence type
 export type Sequence = {
-  sequenceId: string;    // for referencing reusable sequences
-  delay?: number;         // default 0
-  offset?: number;        // default 100
+  sequenceId: string; // for referencing reusable sequences
+  delay?: number; // default 0
+  offset?: number; // default 100
   offsetEasing?: string | ((p: number) => number); // default linear
   effects: (Effect | EffectRef)[];
 };
@@ -115,7 +115,7 @@ export type Sequence = {
 // Update InteractConfig
 export type InteractConfig = {
   effects: Record<string, Effect>;
-  sequences?: Record<string, Sequence>;  // NEW: reusable sequences
+  sequences?: Record<string, Sequence>; // NEW: reusable sequences
   conditions?: Record<string, Condition>;
   interactions: Interaction[];
 };
@@ -123,7 +123,7 @@ export type InteractConfig = {
 // Update Interaction
 export type Interaction = InteractionTrigger & {
   effects: ((Effect | EffectRef) & { interactionId?: string })[];
-  sequences?: Sequence[];  // NEW: inline sequences
+  sequences?: Sequence[]; // NEW: inline sequences
 };
 ```
 
@@ -134,9 +134,11 @@ Add sequences to the cache structure in `packages/interact/src/types.ts`:
 ```typescript
 export type InteractCache = {
   effects: { [effectId: string]: Effect };
-  sequences: { [sequenceId: string]: Sequence };  // NEW
+  sequences: { [sequenceId: string]: Sequence }; // NEW
   conditions: { [conditionId: string]: Condition };
-  interactions: { /* existing structure */ };
+  interactions: {
+    /* existing structure */
+  };
 };
 ```
 
@@ -177,14 +179,12 @@ The offset calculation follows this algorithm:
 function calculateOffsets(
   count: number,
   offset: number,
-  easingFn: (t: number) => number
+  easingFn: (t: number) => number,
 ): number[] {
   if (count <= 1) return [0];
-  
+
   const last = count - 1;
-  return Array.from({ length: count }, (_, i) => 
-    (easingFn(i / last) * last * offset) | 0
-  );
+  return Array.from({ length: count }, (_, i) => (easingFn(i / last) * last * offset) | 0);
 }
 ```
 
diff --git a/packages/interact/dev/sequences-spec.md b/packages/interact/dev/sequences-spec.md
index 8fb1123a..982a7e9e 100644
--- a/packages/interact/dev/sequences-spec.md
+++ b/packages/interact/dev/sequences-spec.md
@@ -6,13 +6,13 @@ This is a proposal for supporting sequenced effects (also known as “timelines
 
 ## Config spec
 
-* A Sequence is a list of `Effect`s managed by a single trigger/timeline.
-* `Effect`s in a `Sequence` are applied in their specified order inside `Interaction.sequence.effects`.
-* Reusable `Sequence`s will be declared using a new `InteractConfig.sequences` property, which is a map of Sequence declarations by a unique key.
-* `Sequence`s can be defined on an `Interaction` using a new `Interaction.sequences` property which is a list of `Sequence`s.
-* Each Sequence will have an `effects` property which contains its child Effects.
-* A `Sequence` does not have a `key` property, nor any of the other element targeting-related properties, since it by itself is not tied to an element.
-* The `Effect`s inside a `Sequence` are the objects that define that related target.
+- A Sequence is a list of `Effect`s managed by a single trigger/timeline.
+- `Effect`s in a `Sequence` are applied in their specified order inside `Interaction.sequence.effects`.
+- Reusable `Sequence`s will be declared using a new `InteractConfig.sequences` property, which is a map of Sequence declarations by a unique key.
+- `Sequence`s can be defined on an `Interaction` using a new `Interaction.sequences` property which is a list of `Sequence`s.
+- Each Sequence will have an `effects` property which contains its child Effects.
+- A `Sequence` does not have a `key` property, nor any of the other element targeting-related properties, since it by itself is not tied to an element.
+- The `Effect`s inside a `Sequence` are the objects that define that related target.
 
 ## The new `sequences` property
 
@@ -49,91 +49,95 @@ type Sequence = {
 
 ## The `Sequence.delay`
 
-* A fixed offset of milliseconds to delay the playing of the entire Sequence  
-* Defaults to `0`
+- A fixed offset of milliseconds to delay the playing of the entire Sequence
+- Defaults to `0`
 
 ## The `Sequence.offset`
 
-* A fixed amount of milliseconds to multiply the result of the `easing` function  
-* Defaults to `100`
+- A fixed amount of milliseconds to multiply the result of the `easing` function
+- Defaults to `100`
 
 ## The `Sequence.offsetEasing`
 
-* Either a JS function or a valid CSS `easing` value, or a valid `easing` name in `@wix/motion` library  
-  * A JS function takes a `number` from 0 to 1\.  
-  * An `easing` value, either valid from CSS, or in `@wix/motion`, will be translated to the corresponding function in JS or a CSS `calc()`.  
-* The mapping of each offset using the easing function as done as follows:
+- Either a JS function or a valid CSS `easing` value, or a valid `easing` name in `@wix/motion` library
+  - A JS function takes a `number` from 0 to 1\.
+  - An `easing` value, either valid from CSS, or in `@wix/motion`, will be translated to the corresponding function in JS or a CSS `calc()`.
+- The mapping of each offset using the easing function as done as follows:
 
 ```javascript
 // `indices` is the array of indices from 0 to Length-1
 // `easing` is the easing function
 // `offset` is the `sequence.offset` property
 const last = indices.at(-1);
-indices.map(n => easing(n / last) * last * offset | 0) // | 0 is basically flooring
+indices.map((n) => (easing(n / last) * last * offset) | 0); // | 0 is basically flooring
 ```
 
 ### Easing examples
 
 ```javascript
-const items = [0, 1, 2, 3, 4]
-const offset = 200
+const items = [0, 1, 2, 3, 4];
+const offset = 200;
 
-const linear = t => t
+const linear = (t) => t;
 // 0, 200, 400, 300, 400
 
-const quadIn = t => t ** 2
+const quadIn = (t) => t ** 2;
 // 0, 50, 200, 450, 800
 
-const sinOut = t => Math.sin(t * Math.PI / 2)
+const sinOut = (t) => Math.sin((t * Math.PI) / 2);
 // 0, 306, 565, 739, 800
 ```
 
 ## The `Sequence.align`
 
-* **Ignore for now \- DO NOT implement**  
-* Specifies how to align the Effects inside the Sequence:  
-  * `start` aligns to the beginning  
-  * `end` aligns to the end  
-  * `sequence` aligns each effect’s start to the end of its preceding effect  
-  * `sequence-reverse` is same as `sequence` but starts from the last effect backwards
+- **Ignore for now \- DO NOT implement**
+- Specifies how to align the Effects inside the Sequence:
+  - `start` aligns to the beginning
+  - `end` aligns to the end
+  - `sequence` aligns each effect’s start to the end of its preceding effect
+  - `sequence-reverse` is same as `sequence` but starts from the last effect backwards
 
 # Effect on Effects’ `delay`
 
-* In initial phase this feature should only apply to `keyframeEffect`s and `namedEffect`s \- where we generate Web or CSS animations  
-* The result of calculated offset should be added to the Effect’s specified `delay`  
-* If an Effect is removed (e.g. when an Effect’s `condition` stops matching the state of its environment and needs to be removed) it should propagate to the corresponding Sequence to update the calculated delays  
-* If an entire Sequence is removed we should try to remove it completely without a significant overhead of propagating each Effect being removed.
+- In initial phase this feature should only apply to `keyframeEffect`s and `namedEffect`s \- where we generate Web or CSS animations
+- The result of calculated offset should be added to the Effect’s specified `delay`
+- If an Effect is removed (e.g. when an Effect’s `condition` stops matching the state of its environment and needs to be removed) it should propagate to the corresponding Sequence to update the calculated delays
+- If an entire Sequence is removed we should try to remove it completely without a significant overhead of propagating each Effect being removed.
 
 # Implementation
 
-* Create a new `Sequence` class in `@wix/motion` package that manages a list of `AnimationGroup` instances.
-* A `Sequence` instance manages its own playback, similar to `AnimationGroup`, only difference is its `animations` property holds `AnimationGroup` instances. Therefor, it should extend `AnimationGroup` and have a similar API.
-* Note that `Sequence` does not have a `target`, so all of its API endpoints that involve an element target should be written accordingly, or not exist if not relevant.
-* In the `@eix/interact` package `Sequence`s will be created from an `InteractConfig` for every declaration inside `Interaction.sequences`.
+- Create a new `Sequence` class in `@wix/motion` package that manages a list of `AnimationGroup` instances.
+- A `Sequence` instance manages its own playback, similar to `AnimationGroup`, only difference is its `animations` property holds `AnimationGroup` instances. Therefor, it should extend `AnimationGroup` and have a similar API.
+- Note that `Sequence` does not have a `target`, so all of its API endpoints that involve an element target should be written accordingly, or not exist if not relevant.
+- In the `@eix/interact` package `Sequence`s will be created from an `InteractConfig` for every declaration inside `Interaction.sequences`.
 
 # Appendix
 
 ## A CSS solution in a futuristic world where CSS math functions are widely supported
 
-* The index of each Effect in the Sequence  and count of Effects in the Sequence are set on each target element.  
-* Generated `animation-delay` should be a `calc()` that includes the effect’s `delay` \+ the generated staggering offset as follows:
+- The index of each Effect in the Sequence and count of Effects in the Sequence are set on each target element.
+- Generated `animation-delay` should be a `calc()` that includes the effect’s `delay` \+ the generated staggering offset as follows:
 
 ```css
 @property --interact-seq-c {
-  syntax: "<number>";
+  syntax: '<number>';
   initial-value: 1;
   inherits: false;
 }
 
 @property --interact-seq-i {
-  syntax: "<number>";
+  syntax: '<number>';
   initial-value: 0;
   inherits: false;
 }
 
 .target {
-  --_interact-delay: calc(pow(var(--interact-seq-i) / var(--interact-seq-c), 2)); /* quadIn - this is here for readability, don't actually have to add as a separate property */
-  animation-delay: calc(effectDelay + var(--_interact-delay) * var(--interact-seq-c) * <sequence.offset>);
+  --_interact-delay: calc(
+    pow(var(--interact-seq-i) / var(--interact-seq-c), 2)
+  ); /* quadIn - this is here for readability, don't actually have to add as a separate property */
+  animation-delay: calc(
+    effectDelay + var(--_interact-delay) * var(--interact-seq-c) * <sequence.offset>
+  );
 }
 ```
 
@@ -158,7 +162,7 @@ const sinOut = t => Math.sin(t * Math.PI / 2)
        offset: 150,
        offsetEasing: 'ease-out',
        effects: [{
-	  
+
        }]
      }]
    }]

From 835a015f3ed33f01af604d5f7dc9f7b2b866ee7c Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Sun, 25 Jan 2026 21:57:21 +0200
Subject: [PATCH 05/29] Fixed format

---
 .../plans/sequence_feature_implementation_84c01c97.plan.md    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
index 6f0e2977..cd2d2698 100644
--- a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
+++ b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
@@ -69,6 +69,7 @@ Create new file `packages/motion/src/Sequence.ts`:
 - Store `animationGroups: AnimationGroup[]` instead of `animations: Animation[]`
 - Add properties: `delay`, `offset`, `offsetEasing`
 - Implement `calculateOffsets()` method using the formula from spec:
+
 ```typescript
 const last = indices.at(-1);
 indices.map((n) => (easing(n / last) * last * offset) | 0);
@@ -148,7 +149,6 @@ Modify `packages/interact/src/core/Interact.ts`:
 
 1. Parse `config.sequences` into cache (similar to `config.effects`)
 2. Process `interaction.sequences` array:
-
    - Resolve `sequenceId` references from `config.sequences`
    - Process each effect within the sequence
    - Generate unique IDs for sequence effects
@@ -203,4 +203,4 @@ The calculated offsets are added to each effect's existing `delay` property.
 1. Unit tests for `Sequence` class offset calculations
 2. Unit tests for easing function integration
 3. Integration tests for sequence parsing in Interact
-4. E2E tests for staggered animations with various easing functions
\ No newline at end of file
+4. E2E tests for staggered animations with various easing functions

From cf61dd2a8bc0b7236db803289df92af1473b80f0 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Thu, 29 Jan 2026 12:55:28 +0200
Subject: [PATCH 06/29] sequnce implementation

---
 ...ce_feature_implementation_84c01c97.plan.md |  31 +-
 apps/demo/src/styles.css                      | 295 +++++++
 apps/demo/src/web/App.tsx                     |   2 +
 apps/demo/src/web/components/SequenceDemo.tsx | 246 ++++++
 .../demo/src/web/hooks/useInteractInstance.ts |   9 +-
 packages/interact/src/core/Interact.ts        | 145 ++-
 packages/interact/src/core/add.ts             |   2 +-
 packages/interact/src/types.ts                |  68 +-
 packages/motion/src/Sequence.ts               | 307 +++++++
 packages/motion/src/index.ts                  |   2 +
 packages/motion/src/types.ts                  |  24 +
 packages/motion/test/Sequence.spec.ts         | 823 ++++++++++++++++++
 12 files changed, 1916 insertions(+), 38 deletions(-)
 create mode 100644 apps/demo/src/web/components/SequenceDemo.tsx
 create mode 100644 packages/motion/src/Sequence.ts
 create mode 100644 packages/motion/test/Sequence.spec.ts

diff --git a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
index cd2d2698..ef334875 100644
--- a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
+++ b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
@@ -1,28 +1,3 @@
----
-name: Sequence Feature Implementation
-overview: Implement a new Sequence feature in @wix/motion that manages a list of AnimationGroup instances with staggered delays, and integrate it into @eix/interact for declarative configuration.
-todos:
-  - id: motion-sequence-class
-    content: Create Sequence class in @wix/motion that extends AnimationGroup and manages AnimationGroup instances
-    status: pending
-  - id: motion-types
-    content: Add SequenceOptions type to @wix/motion/types.ts and export from index.ts
-    status: pending
-  - id: interact-types
-    content: Update InteractConfig, Interaction, and InteractCache types to include sequences
-    status: pending
-  - id: interact-parse-config
-    content: Update parseConfig in Interact.ts to process sequence declarations and sequence effects
-    status: pending
-  - id: interact-add-sequence
-    content: Update add.ts to create Sequence instances and apply calculated delay offsets
-    status: pending
-  - id: handler-integration
-    content: Update trigger handlers to work with Sequence instances for coordinated playback
-    status: pending
-isProject: false
----
-
 # Sequence Feature Implementation
 
 This plan implements the Sequence feature as specified in [sequences-spec.md](packages/interact/dev/sequences-spec.md). The feature enables managing multiple Effects as a coordinated timeline with staggered delays.
@@ -69,7 +44,6 @@ Create new file `packages/motion/src/Sequence.ts`:
 - Store `animationGroups: AnimationGroup[]` instead of `animations: Animation[]`
 - Add properties: `delay`, `offset`, `offsetEasing`
 - Implement `calculateOffsets()` method using the formula from spec:
-
 ```typescript
 const last = indices.at(-1);
 indices.map((n) => (easing(n / last) * last * offset) | 0);
@@ -97,7 +71,7 @@ Update `packages/motion/src/index.ts` to export:
 - `Sequence` class
 - `SequenceOptions` type
 
-## Part 2: @eix/interact Package Changes
+## Part 2: @wix/interact Package Changes
 
 ### 2.1 Update Types
 
@@ -149,6 +123,7 @@ Modify `packages/interact/src/core/Interact.ts`:
 
 1. Parse `config.sequences` into cache (similar to `config.effects`)
 2. Process `interaction.sequences` array:
+
    - Resolve `sequenceId` references from `config.sequences`
    - Process each effect within the sequence
    - Generate unique IDs for sequence effects
@@ -203,4 +178,4 @@ The calculated offsets are added to each effect's existing `delay` property.
 1. Unit tests for `Sequence` class offset calculations
 2. Unit tests for easing function integration
 3. Integration tests for sequence parsing in Interact
-4. E2E tests for staggered animations with various easing functions
+4. E2E tests for staggered animations with various easing functions
\ No newline at end of file
diff --git a/apps/demo/src/styles.css b/apps/demo/src/styles.css
index 9b38972c..cb23523e 100644
--- a/apps/demo/src/styles.css
+++ b/apps/demo/src/styles.css
@@ -548,3 +548,298 @@ body {
   background: linear-gradient(135deg, #ff9a9e 0%, #fecfef 99%, #fecfef 100%);
   color: #333;
 }
+
+/* Sequence Demo */
+.sequence-demo-section {
+  margin-top: 2rem;
+}
+
+.sequence-demo-header {
+  margin-bottom: 1.5rem;
+}
+
+.sequence-demo-header h3 {
+  margin: 0 0 0.5rem;
+  font-size: 1.5rem;
+}
+
+.sequence-demo-description {
+  color: rgb(148 163 184 / 0.9);
+  line-height: 1.6;
+  margin: 0;
+}
+
+.sequence-demo-description code {
+  background: rgb(30 41 59 / 0.8);
+  padding: 0.15em 0.4em;
+  border-radius: 4px;
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+  font-size: 0.9em;
+  color: #a5b4fc;
+}
+
+.easing-presets {
+  margin-bottom: 1.5rem;
+}
+
+.easing-preset-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+}
+
+.easing-preset-btn {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.15rem;
+  padding: 0.5rem 0.75rem;
+  background: rgb(30 41 59 / 0.6);
+  border: 1px solid rgb(148 163 184 / 0.2);
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.easing-preset-btn:hover {
+  background: rgb(30 41 59 / 0.9);
+  border-color: rgb(148 163 184 / 0.4);
+}
+
+.easing-preset-btn.active {
+  background: linear-gradient(135deg, rgba(59, 130, 246, 0.3) 0%, rgba(139, 92, 246, 0.3) 100%);
+  border-color: #8b5cf6;
+}
+
+.preset-name {
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+  font-size: 0.85rem;
+  font-weight: 600;
+  color: #e2e8f0;
+}
+
+.preset-type {
+  font-size: 0.65rem;
+  color: #94a3b8;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.sequence-demo-layout {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2rem;
+  margin-bottom: 1.5rem;
+}
+
+@media (max-width: 900px) {
+  .sequence-demo-layout {
+    grid-template-columns: 1fr;
+  }
+}
+
+.sequence-config-editor {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.sequence-config-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.parse-error {
+  font-size: 0.75rem;
+  color: #f87171;
+  background: rgba(248, 113, 113, 0.1);
+  padding: 0.25rem 0.5rem;
+  border-radius: 4px;
+}
+
+.config-textarea {
+  width: 100%;
+  min-height: 400px;
+  padding: 1rem;
+  background: rgb(2 6 23 / 0.9);
+  border: 1px solid rgb(148 163 184 / 0.2);
+  border-radius: 8px;
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  color: #a5b4fc;
+  resize: vertical;
+  tab-size: 2;
+}
+
+.config-textarea:focus {
+  outline: none;
+  border-color: rgb(59 130 246 / 0.5);
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+}
+
+.sequence-buttons {
+  display: flex;
+  gap: 0.75rem;
+}
+
+.sequence-apply-button,
+.sequence-reset-button {
+  flex: 1;
+  padding: 0.75rem 1.5rem;
+  background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
+  border: none;
+  border-radius: 8px;
+  color: white;
+  font-weight: 600;
+  font-size: 0.9rem;
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.sequence-reset-button {
+  background: rgb(71 85 105 / 0.8);
+}
+
+.sequence-apply-button:hover,
+.sequence-reset-button:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 20px rgba(59, 130, 246, 0.3);
+}
+
+.sequence-apply-button:active,
+.sequence-reset-button:active {
+  transform: translateY(0);
+}
+
+.sequence-demo-preview {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.sequence-trigger-area {
+  background: rgb(30 41 59 / 0.5);
+  border: 2px dashed rgb(148 163 184 / 0.3);
+  border-radius: 1rem;
+  padding: 1.5rem;
+  cursor: pointer;
+  transition: border-color 0.2s ease, background 0.2s ease;
+}
+
+.sequence-trigger-area:hover {
+  border-color: rgb(59 130 246 / 0.5);
+  background: rgb(30 41 59 / 0.7);
+}
+
+.sequence-trigger-hint {
+  text-align: center;
+  color: rgb(148 163 184 / 0.7);
+  font-size: 0.85rem;
+  margin: 0 0 1rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+}
+
+.sequence-items-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 0.75rem;
+}
+
+@media (max-width: 600px) {
+  .sequence-items-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+.sequence-item {
+  aspect-ratio: 1;
+  min-width: 80px;
+  background: linear-gradient(135deg, var(--item-color) 0%, color-mix(in srgb, var(--item-color) 70%, white) 100%);
+  border-radius: 12px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 4px 20px color-mix(in srgb, var(--item-color) 40%, transparent);
+  transition: transform 0.2s ease;
+}
+
+.sequence-item:hover {
+  transform: scale(1.05);
+}
+
+.sequence-item-label {
+  color: white;
+  font-weight: 700;
+  font-size: 0.9rem;
+  text-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+}
+
+.sequence-timing-viz {
+  background: rgb(30 41 59 / 0.4);
+  border-radius: 0.75rem;
+  padding: 1rem 1.25rem;
+  margin-bottom: 1rem;
+}
+
+.timing-bars {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.timing-bar-row {
+  display: grid;
+  grid-template-columns: 60px 1fr 60px;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.timing-bar-label {
+  font-size: 0.8rem;
+  color: rgb(148 163 184 / 0.8);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.timing-bar-track {
+  height: 8px;
+  background: rgb(15 23 42 / 0.6);
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.timing-bar-fill {
+  height: 100%;
+  border-radius: 4px;
+  transition: width 0.3s ease;
+}
+
+.timing-bar-value {
+  font-size: 0.8rem;
+  color: rgb(148 163 184 / 0.9);
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+  text-align: right;
+}
+
+.sequence-formula {
+  background: rgb(30 41 59 / 0.4);
+  border-radius: 0.75rem;
+  padding: 1rem 1.25rem;
+  text-align: center;
+}
+
+.formula-code {
+  display: inline-block;
+  background: rgb(15 23 42 / 0.8);
+  padding: 0.5em 1em;
+  border-radius: 6px;
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+  font-size: 0.9rem;
+  color: #a5b4fc;
+}
diff --git a/apps/demo/src/web/App.tsx b/apps/demo/src/web/App.tsx
index bf456e85..d338dbf9 100644
--- a/apps/demo/src/web/App.tsx
+++ b/apps/demo/src/web/App.tsx
@@ -3,6 +3,7 @@ import { ScrollShowcase } from './components/ScrollShowcase';
 import { ResponsiveDemo } from './components/ResponsiveDemo';
 import { SelectorConditionDemo } from './components/SelectorConditionDemo';
 import { PointerMoveDemo } from './components/PointerMoveDemo';
+import { SequenceDemo } from './components/SequenceDemo';
 
 const heroCopy = [
   'Tune triggers, easings, and delays in real time.',
@@ -35,6 +36,7 @@ function App() {
       </header>
 
       <Playground />
+      <SequenceDemo />
       <SelectorConditionDemo />
       <div className="scroll-showcase-wrapper">
         <ResponsiveDemo />
diff --git a/apps/demo/src/web/components/SequenceDemo.tsx b/apps/demo/src/web/components/SequenceDemo.tsx
new file mode 100644
index 00000000..68f86b4b
--- /dev/null
+++ b/apps/demo/src/web/components/SequenceDemo.tsx
@@ -0,0 +1,246 @@
+import { useState, useMemo, useCallback } from 'react';
+import type { InteractConfig } from '@wix/interact/web';
+import { useInteractInstance } from '../hooks/useInteractInstance';
+
+const createConfig = (offsetEasing: string): InteractConfig => ({
+  effects: {
+    'seq-effect-0': {
+      key: 'seq-item-1',
+      duration: 600,
+      easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+      fill: 'both',
+      keyframeEffect: {
+        name: 'seq-entrance-0',
+        keyframes: [
+          { transform: 'translateY(40px) scale(0.8)', opacity: 0 },
+          { transform: 'translateY(0) scale(1)', opacity: 1 },
+        ],
+      },
+    },
+    'seq-effect-1': {
+      key: 'seq-item-2',
+      duration: 600,
+      easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+      fill: 'both',
+      keyframeEffect: {
+        name: 'seq-entrance-1',
+        keyframes: [
+          { transform: 'translateY(40px) scale(0.8)', opacity: 0 },
+          { transform: 'translateY(0) scale(1)', opacity: 1 },
+        ],
+      },
+    },
+    'seq-effect-2': {
+      key: 'seq-item-3',
+      duration: 600,
+      easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+      fill: 'both',
+      keyframeEffect: {
+        name: 'seq-entrance-2',
+        keyframes: [
+          { transform: 'translateY(40px) scale(0.8)', opacity: 0 },
+          { transform: 'translateY(0) scale(1)', opacity: 1 },
+        ],
+      },
+    },
+    'seq-effect-3': {
+      key: 'seq-item-4',
+      duration: 600,
+      easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+      fill: 'both',
+      keyframeEffect: {
+        name: 'seq-entrance-3',
+        keyframes: [
+          { transform: 'translateY(40px) scale(0.8)', opacity: 0 },
+          { transform: 'translateY(0) scale(1)', opacity: 1 },
+        ],
+      },
+    },
+    'seq-effect-4': {
+      key: 'seq-item-5',
+      duration: 600,
+      easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+      fill: 'both',
+      keyframeEffect: {
+        name: 'seq-entrance-4',
+        keyframes: [
+          { transform: 'translateY(40px) scale(0.8)', opacity: 0 },
+          { transform: 'translateY(0) scale(1)', opacity: 1 },
+        ],
+      },
+    },
+    'seq-effect-5': {
+      key: 'seq-item-6',
+      duration: 600,
+      easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+      fill: 'both',
+      keyframeEffect: {
+        name: 'seq-entrance-5',
+        keyframes: [
+          { transform: 'translateY(40px) scale(0.8)', opacity: 0 },
+          { transform: 'translateY(0) scale(1)', opacity: 1 },
+        ],
+      },
+    },
+  },
+  sequences: {
+    'entrance-sequence': {
+      sequenceId: 'entrance-sequence',
+      delay: 0,
+      offset: 120,
+      offsetEasing,
+      effects: [
+        { effectId: 'seq-effect-0' },
+        { effectId: 'seq-effect-1' },
+        { effectId: 'seq-effect-2' },
+        { effectId: 'seq-effect-3' },
+        { effectId: 'seq-effect-4' },
+        { effectId: 'seq-effect-5' },
+      ],
+    },
+  },
+  interactions: [
+    {
+      key: 'sequence-trigger',
+      trigger: 'viewEnter',
+      params: { type: 'repeat', threshold: 0.5 },
+      sequences: [{ sequenceId: 'entrance-sequence' }],
+    },
+  ],
+});
+
+// Easing presets showcasing different types
+const easingPresets = [
+  { name: 'linear', value: 'linear', description: 'Named easing' },
+  { name: 'quadOut', value: 'quadOut', description: 'Named easing' },
+  { name: 'expoIn', value: 'expoIn', description: 'Named easing' },
+  { name: 'ease-out', value: 'cubic-bezier(0.4, 0, 0.2, 1)', description: 'CSS cubic-bezier' },
+  { name: 'ease-in', value: 'cubic-bezier(0.4, 0, 1, 1)', description: 'CSS cubic-bezier' },
+  { name: 'overshoot', value: 'cubic-bezier(0.34, 1.56, 0.64, 1)', description: 'CSS cubic-bezier (y > 1)' },
+  { name: 'back-in', value: 'cubic-bezier(0.6, -0.28, 0.735, 0.045)', description: 'CSS cubic-bezier (y < 0)' },
+];
+
+const sequenceItems = [
+  { id: 1, label: 'First', color: '#3b82f6' },
+  { id: 2, label: 'Second', color: '#8b5cf6' },
+  { id: 3, label: 'Third', color: '#ec4899' },
+  { id: 4, label: 'Fourth', color: '#f97316' },
+  { id: 5, label: 'Fifth', color: '#22c55e' },
+  { id: 6, label: 'Sixth', color: '#06b6d4' },
+];
+
+export const SequenceDemo = () => {
+  const [triggerKey, setTriggerKey] = useState(0);
+  const [configText, setConfigText] = useState(() => JSON.stringify(createConfig('quadOut'), null, 2));
+  const [parseError, setParseError] = useState<string | null>(null);
+  const [activePreset, setActivePreset] = useState('quadOut');
+
+  const config = useMemo(() => {
+    try {
+      const parsed = JSON.parse(configText);
+      setParseError(null);
+      return parsed as InteractConfig;
+    } catch (e) {
+      setParseError((e as Error).message);
+      return createConfig('quadOut');
+    }
+  }, [configText]);
+
+  useInteractInstance(config, triggerKey);
+
+  const handleApply = () => {
+    setTriggerKey((prev) => prev + 1);
+  };
+
+  const handleReset = () => {
+    setConfigText(JSON.stringify(createConfig('quadOut'), null, 2));
+    setActivePreset('quadOut');
+    setTriggerKey((prev) => prev + 1);
+  };
+
+  const handlePresetClick = useCallback((preset: typeof easingPresets[0]) => {
+    setConfigText(JSON.stringify(createConfig(preset.value), null, 2));
+    setActivePreset(preset.value);
+    setTriggerKey((prev) => prev + 1);
+  }, []);
+
+  return (
+    <section className="sequence-demo-section panel">
+      <div className="sequence-demo-header">
+        <p className="scroll-label">Sequence Feature</p>
+        <h3>Staggered Animations</h3>
+        <p className="sequence-demo-description">
+          Use <code>offsetEasing</code> to control stagger timing. Supports named easings, 
+          CSS <code>cubic-bezier()</code> strings, and custom functions.
+        </p>
+      </div>
+
+      <div className="easing-presets">
+        <p className="scroll-label">Try Different Easing Types</p>
+        <div className="easing-preset-buttons">
+          {easingPresets.map((preset) => (
+            <button
+              key={preset.value}
+              className={`easing-preset-btn ${activePreset === preset.value ? 'active' : ''}`}
+              onClick={() => handlePresetClick(preset)}
+              title={`${preset.description}: ${preset.value}`}
+            >
+              <span className="preset-name">{preset.name}</span>
+              <span className="preset-type">{preset.description}</span>
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="sequence-demo-layout">
+        <div className="sequence-config-editor">
+          <div className="sequence-config-header">
+            <p className="scroll-label">InteractConfig (editable JSON)</p>
+            {parseError && <span className="parse-error">Parse error: {parseError}</span>}
+          </div>
+          <textarea
+            className="config-textarea"
+            value={configText}
+            onChange={(e) => setConfigText(e.target.value)}
+            spellCheck={false}
+          />
+          <div className="sequence-buttons">
+            <button className="sequence-apply-button" onClick={handleApply}>
+              Apply & Replay
+            </button>
+            <button className="sequence-reset-button" onClick={handleReset}>
+              Reset to Default
+            </button>
+          </div>
+        </div>
+
+        <div className="sequence-demo-preview">
+          <interact-element data-interact-key="sequence-trigger">
+            <div className="sequence-trigger-area">
+              <p className="sequence-trigger-hint">Scroll into view or click Apply & Replay</p>
+              <div className="sequence-items-grid">
+                {sequenceItems.map((item) => (
+                  <interact-element key={item.id} data-interact-key={`seq-item-${item.id}`}>
+                    <div
+                      className="sequence-item"
+                      style={{ '--item-color': item.color } as React.CSSProperties}
+                    >
+                      <span className="sequence-item-label">{item.label}</span>
+                    </div>
+                  </interact-element>
+                ))}
+              </div>
+            </div>
+          </interact-element>
+        </div>
+      </div>
+
+      <div className="sequence-formula">
+        <p className="scroll-label">Offset Formula</p>
+        <code className="formula-code">
+          delay + (easing(index / lastIndex) × lastIndex × offset)
+        </code>
+      </div>
+    </section>
+  );
+};
diff --git a/apps/demo/src/web/hooks/useInteractInstance.ts b/apps/demo/src/web/hooks/useInteractInstance.ts
index f8fa2332..f149b36d 100644
--- a/apps/demo/src/web/hooks/useInteractInstance.ts
+++ b/apps/demo/src/web/hooks/useInteractInstance.ts
@@ -3,13 +3,18 @@ import { Interact, type InteractConfig } from '@wix/interact/web';
 
 export const useInteractInstance = (
   config: InteractConfig,
+  keyOrOptions?: number | { useCutsomElement?: boolean },
   options?: { useCutsomElement?: boolean },
 ) => {
+  // Support both (config, options) and (config, key, options) signatures
+  const key = typeof keyOrOptions === 'number' ? keyOrOptions : undefined;
+  const opts = typeof keyOrOptions === 'object' ? keyOrOptions : options;
+
   useEffect(() => {
-    const instance = Interact.create(config, options);
+    const instance = Interact.create(config, opts);
 
     return () => {
       instance.destroy();
     };
-  }, [config, options]);
+  }, [config, opts, key]);
 };
diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index 4e19a6ec..dee5efa3 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -8,11 +8,13 @@ import {
   ViewEnterHandlerModule,
   IInteractionController,
   IInteractElement,
+  Sequence,
+  SequenceRef,
 } from '../types';
 import { getInterpolatedKey } from './utilities';
 import { generateId } from '../utils';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
-import { registerEffects } from '@wix/motion';
+import { registerEffects, calculateOffsets, jsEasings, parseCubicBezier } from '@wix/motion';
 
 function _convertToKeyTemplate(key: string) {
   return key.replace(/\[([-\w]+)]/g, '[]');
@@ -40,7 +42,7 @@ export class Interact {
   static controllerCache = new Map<string, IInteractionController>();
 
   constructor() {
-    this.dataCache = { effects: {}, conditions: {}, interactions: {} };
+    this.dataCache = { effects: {}, sequences: {}, conditions: {}, interactions: {} };
     this.addedInteractions = {};
     this.mediaQueryListeners = new Map();
     this.listInteractionsCache = {};
@@ -90,7 +92,7 @@ export class Interact {
     this.addedInteractions = {};
     this.listInteractionsCache = {};
     this.controllers.clear();
-    this.dataCache = { effects: {}, conditions: {}, interactions: {} };
+    this.dataCache = { effects: {}, sequences: {}, conditions: {}, interactions: {} };
     Interact.instances.splice(Interact.instances.indexOf(this), 1);
   }
 
@@ -220,6 +222,126 @@ export class Interact {
 
 let interactionIdCounter = 0;
 
+/**
+ * Resolves an easing value to a function.
+ * Supports:
+ * - Direct function references
+ * - Named easings from @wix/motion library
+ * - CSS cubic-bezier strings (e.g., "cubic-bezier(0.4, 0, 0.2, 1)")
+ */
+function resolveEasingFunction(
+  easing: string | ((t: number) => number) | undefined,
+): (t: number) => number {
+  if (typeof easing === 'function') {
+    return easing;
+  }
+
+  if (typeof easing === 'string') {
+    // Check named easings first
+    if (easing in jsEasings) {
+      return jsEasings[easing as keyof typeof jsEasings];
+    }
+
+    // Try parsing as cubic-bezier
+    const bezierFn = parseCubicBezier(easing);
+    if (bezierFn) {
+      return bezierFn;
+    }
+  }
+
+  return jsEasings.linear;
+}
+
+/**
+ * Resolves a sequence reference or inline sequence to a full Sequence object.
+ */
+function resolveSequence(
+  seqOrRef: Sequence | SequenceRef,
+  configSequences: Record<string, Sequence>,
+): Sequence | null {
+  const sequenceId = seqOrRef.sequenceId;
+
+  // Check if it's a reference (has sequenceId but no effects)
+  if (!('effects' in seqOrRef) || !seqOrRef.effects) {
+    const referencedSequence = configSequences[sequenceId];
+    if (!referencedSequence) {
+      console.warn(`Sequence with id "${sequenceId}" not found in config.sequences`);
+      return null;
+    }
+
+    // Merge overrides from the reference
+    return {
+      ...referencedSequence,
+      delay: seqOrRef.delay ?? referencedSequence.delay,
+      offset: seqOrRef.offset ?? referencedSequence.offset,
+      offsetEasing: seqOrRef.offsetEasing ?? referencedSequence.offsetEasing,
+    };
+  }
+
+  // It's an inline sequence
+  return seqOrRef as Sequence;
+}
+
+/**
+ * Expands effects from sequences into the effects array with calculated staggered delays.
+ */
+function expandSequenceEffects(
+  interaction: Interaction,
+  configSequences: Record<string, Sequence>,
+  configEffects: Record<string, Effect>,
+): (Effect | EffectRef)[] {
+  const expandedEffects: (Effect | EffectRef)[] = [];
+
+  // Process sequences and add their effects with calculated delays
+  if (interaction.sequences) {
+    for (const seqOrRef of interaction.sequences) {
+      const sequence = resolveSequence(seqOrRef, configSequences);
+      if (!sequence) continue;
+
+      const delay = sequence.delay ?? 0;
+      const offset = sequence.offset ?? 100;
+      const easingFn = resolveEasingFunction(sequence.offsetEasing);
+
+      // Calculate staggered offsets for this sequence
+      const offsets = calculateOffsets(sequence.effects.length, offset, easingFn);
+
+      // Process each effect in the sequence
+      sequence.effects.forEach((effect, index) => {
+        // Resolve effect reference if needed
+        let resolvedEffect: Effect | EffectRef;
+        if ('effectId' in effect && effect.effectId && !('duration' in effect || 'namedEffect' in effect || 'keyframeEffect' in effect || 'customEffect' in effect)) {
+          // It's a reference
+          const referencedEffect = configEffects[effect.effectId];
+          if (referencedEffect) {
+            resolvedEffect = { ...referencedEffect, ...effect };
+          } else {
+            resolvedEffect = effect;
+          }
+        } else {
+          resolvedEffect = effect;
+        }
+
+        // Calculate the total delay for this effect (sequence delay + staggered offset + effect's own delay)
+        const effectDelay = ('delay' in resolvedEffect ? (resolvedEffect as any).delay : 0) || 0;
+        const calculatedDelay = delay + offsets[index] + effectDelay;
+
+        // Create a new effect with the calculated delay
+        const effectWithDelay: Effect | EffectRef = {
+          ...resolvedEffect,
+          delay: calculatedDelay,
+          // Mark this effect as part of a sequence for potential cleanup tracking
+          _sequenceId: sequence.sequenceId,
+          _sequenceIndex: index,
+        } as any;
+
+        expandedEffects.push(effectWithDelay);
+      });
+    }
+  }
+
+  return expandedEffects;
+}
+
 export function getSelector(
   d: Interaction | Effect,
   {
@@ -249,12 +371,13 @@ export function getSelector(
  */
 function parseConfig(config: InteractConfig, useCutsomElement: boolean = false): InteractCache {
   const conditions = config.conditions || {};
+  const sequences = config.sequences || {};
   const interactions: InteractCache['interactions'] = {};
 
   config.interactions?.forEach((interaction_) => {
     const source = interaction_.key;
     const interactionIdx = ++interactionIdCounter;
-    const { effects: effects_, ...rest } = interaction_;
+    const { effects: effects_, sequences: sequences_, ...rest } = interaction_;
 
     if (!source) {
       console.error(`Interaction ${interactionIdx} is missing a key for source element.`);
@@ -270,10 +393,19 @@ function parseConfig(config: InteractConfig, useCutsomElement: boolean = false):
       };
     }
 
+    /*
+     * Expand sequence effects and combine with direct effects
+     */
+    const sequenceEffects = expandSequenceEffects(
+      { ...interaction_, sequences: sequences_ } as Interaction,
+      sequences,
+      config.effects || {},
+    );
+
     /*
      * Cache interaction trigger by source element
      */
-    const effects = Array.from(effects_);
+    const effects = Array.from([...(effects_ || []), ...sequenceEffects]);
     effects.reverse(); // reverse to ensure the first effect is the one that will be applied first
     const interaction = { ...rest, effects };
 
@@ -318,7 +450,7 @@ function parseConfig(config: InteractConfig, useCutsomElement: boolean = false):
       }
 
       const interactionId = `${target}::${effectId}::${interactionIdx}`;
-      effect.interactionId = interactionId;
+      (effect as any).interactionId = interactionId;
       interactions[source].interactionIds.add(interactionId);
 
       if (target === source) {
@@ -350,6 +482,7 @@ function parseConfig(config: InteractConfig, useCutsomElement: boolean = false):
 
   return {
     effects: config.effects || {},
+    sequences,
     conditions,
     interactions,
   };
diff --git a/packages/interact/src/core/add.ts b/packages/interact/src/core/add.ts
index e837e589..ec694cc3 100644
--- a/packages/interact/src/core/add.ts
+++ b/packages/interact/src/core/add.ts
@@ -147,7 +147,7 @@ function _addInteraction(
 
   const interactionsToApply: InteractionsToApply = [];
 
-  interaction.effects.forEach((effect) => {
+  (interaction.effects || []).forEach((effect) => {
     const effectId = (effect as EffectRef).effectId;
 
     const effectOptions = {
diff --git a/packages/interact/src/types.ts b/packages/interact/src/types.ts
index 7bffa724..445aee35 100644
--- a/packages/interact/src/types.ts
+++ b/packages/interact/src/types.ts
@@ -147,6 +147,56 @@ export type EffectRef = EffectBase & { effectId: string };
 
 export type Effect = EffectBase & (TimeEffect | ScrubEffect | TransitionEffect);
 
+/**
+ * A Sequence is a group of Effects managed as a coordinated timeline with staggered delays.
+ */
+export type Sequence = {
+  /**
+   * Unique identifier for referencing this sequence from Interaction.sequences
+   */
+  sequenceId: string;
+  /**
+   * Fixed delay in milliseconds before the entire sequence starts.
+   * @default 0
+   */
+  delay?: number;
+  /**
+   * Base offset in milliseconds between each effect in the sequence.
+   * @default 100
+   */
+  offset?: number;
+  /**
+   * Easing function to apply to offset calculation.
+   * Can be a JS function, a named easing from @wix/motion, or a CSS easing value.
+   * @default 'linear'
+   */
+  offsetEasing?: string | ((t: number) => number);
+  /**
+   * The effects that belong to this sequence.
+   * Effects will be applied in order with calculated staggered delays.
+   */
+  effects: (Effect | EffectRef)[];
+};
+
+/**
+ * Reference to a reusable Sequence defined in InteractConfig.sequences
+ */
+export type SequenceRef = {
+  sequenceId: string;
+  /**
+   * Override the delay defined in the referenced sequence
+   */
+  delay?: number;
+  /**
+   * Override the offset defined in the referenced sequence
+   */
+  offset?: number;
+  /**
+   * Override the offsetEasing defined in the referenced sequence
+   */
+  offsetEasing?: string | ((t: number) => number);
+};
+
 export type Condition = {
   type: 'media' | 'container' | 'selector';
   predicate?: string;
@@ -163,11 +213,24 @@ export type InteractionTrigger = {
 };
 
 export type Interaction = InteractionTrigger & {
-  effects: ((Effect | EffectRef) & { interactionId?: string })[];
+  /**
+   * Direct effects to apply for this interaction.
+   * Can be omitted if only using sequences.
+   */
+  effects?: ((Effect | EffectRef) & { interactionId?: string })[];
+  /**
+   * Sequences of effects to apply for this interaction.
+   * Each sequence groups effects with staggered delays.
+   */
+  sequences?: (Sequence | SequenceRef)[];
 };
 
 export type InteractConfig = {
   effects: Record<string, Effect>;
+  /**
+   * Reusable Sequence declarations that can be referenced by Interaction.sequences
+   */
+  sequences?: Record<string, Sequence>;
   conditions?: Record<string, Condition>;
   interactions: Interaction[];
 };
@@ -264,6 +327,9 @@ export type InteractCache = {
   effects: {
     [effectId: string]: Effect;
   };
+  sequences: {
+    [sequenceId: string]: Sequence;
+  };
   conditions: {
     [conditionId: string]: Condition;
   };
diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
new file mode 100644
index 00000000..9bdfe645
--- /dev/null
+++ b/packages/motion/src/Sequence.ts
@@ -0,0 +1,307 @@
+import { AnimationGroup } from './AnimationGroup';
+import { jsEasings } from './easings';
+import { SequenceOptions } from './types';
+
+/**
+ * Creates a cubic-bezier easing function from control points.
+ * Based on WebKit's implementation.
+ */
+export function createCubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
+  // Calculate the polynomial coefficients
+  const cx = 3 * x1;
+  const bx = 3 * (x2 - x1) - cx;
+  const ax = 1 - cx - bx;
+
+  const cy = 3 * y1;
+  const by = 3 * (y2 - y1) - cy;
+  const ay = 1 - cy - by;
+
+  // Sample the curve's x value at parameter t
+  const sampleCurveX = (t: number) => ((ax * t + bx) * t + cx) * t;
+
+  // Sample the curve's y value at parameter t
+  const sampleCurveY = (t: number) => ((ay * t + by) * t + cy) * t;
+
+  // Derivative of x with respect to t
+  const sampleCurveDerivativeX = (t: number) => (3 * ax * t + 2 * bx) * t + cx;
+
+  // Given an x value, find the corresponding t using Newton-Raphson
+  const solveCurveX = (x: number): number => {
+    let t = x;
+
+    // Newton-Raphson iteration (usually converges in 4-8 iterations)
+    for (let i = 0; i < 8; i++) {
+      const xError = sampleCurveX(t) - x;
+      if (Math.abs(xError) < 1e-6) {
+        return t;
+      }
+      const dx = sampleCurveDerivativeX(t);
+      if (Math.abs(dx) < 1e-6) {
+        break;
+      }
+      t -= xError / dx;
+    }
+
+    // Fall back to bisection if Newton-Raphson fails
+    let t0 = 0;
+    let t1 = 1;
+    t = x;
+
+    while (t0 < t1) {
+      const xMid = sampleCurveX(t);
+      if (Math.abs(xMid - x) < 1e-6) {
+        return t;
+      }
+      if (x > xMid) {
+        t0 = t;
+      } else {
+        t1 = t;
+      }
+      t = (t1 - t0) / 2 + t0;
+    }
+
+    return t;
+  };
+
+  return (x: number): number => {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    return sampleCurveY(solveCurveX(x));
+  };
+}
+
+/**
+ * Parses a CSS cubic-bezier string and returns an easing function.
+ * @example parseCubicBezier("cubic-bezier(0.4, 0, 0.2, 1)") // returns easing function
+ */
+export function parseCubicBezier(str: string): ((t: number) => number) | null {
+  const match = str.match(/cubic-bezier\s*\(\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^)]+)\s*\)/i);
+  if (!match) return null;
+
+  const [, x1, y1, x2, y2] = match.map((v, i) => (i === 0 ? v : parseFloat(v)));
+  if ([x1, y1, x2, y2].some((v) => typeof v !== 'number' || isNaN(v as number))) {
+    return null;
+  }
+
+  return createCubicBezier(x1 as number, y1 as number, x2 as number, y2 as number);
+}
+
+/**
+ * Resolves an easing value to a function.
+ * Supports:
+ * - Direct function references
+ * - Named easings from @wix/motion library
+ * - CSS cubic-bezier strings (e.g., "cubic-bezier(0.4, 0, 0.2, 1)")
+ * - Defaults to linear if not found
+ */
+function resolveEasingFunction(
+  easing: string | ((t: number) => number) | undefined,
+): (t: number) => number {
+  if (typeof easing === 'function') {
+    return easing;
+  }
+
+  if (typeof easing === 'string') {
+    // Check named easings first
+    if (easing in jsEasings) {
+      return jsEasings[easing as keyof typeof jsEasings];
+    }
+
+    // Try parsing as cubic-bezier
+    const bezierFn = parseCubicBezier(easing);
+    if (bezierFn) {
+      return bezierFn;
+    }
+  }
+
+  // Default to linear
+  return jsEasings.linear;
+}
+
+/**
+ * Calculate staggered delay offsets for a sequence of effects.
+ *
+ * @param count - The number of effects in the sequence
+ * @param offset - The base offset in milliseconds (default 100)
+ * @param easingFn - The easing function to apply to the offset calculation
+ * @returns An array of calculated delay offsets in milliseconds
+ *
+ * @example
+ * // Linear easing with 5 items and 200ms offset
+ * calculateOffsets(5, 200, linear) // [0, 200, 400, 600, 800]
+ *
+ * @example
+ * // QuadIn easing with 5 items and 200ms offset
+ * calculateOffsets(5, 200, quadIn) // [0, 50, 200, 450, 800]
+ */
+export function calculateOffsets(
+  count: number,
+  offset: number,
+  easingFn: (t: number) => number,
+): number[] {
+  if (count <= 1) {
+    return [0];
+  }
+
+  const last = count - 1;
+  return Array.from({ length: count }, (_, i) => (easingFn(i / last) * last * offset) | 0);
+}
+
+/**
+ * @class Sequence
+ *
+ * A class that manages multiple AnimationGroup instances as a coordinated timeline
+ * with staggered delays. Extends AnimationGroup to inherit the playback control API.
+ *
+ * @example
+ * const sequence = new Sequence([group1, group2, group3], {
+ *   delay: 0,
+ *   offset: 100,
+ *   offsetEasing: 'quadIn'
+ * });
+ * sequence.play();
+ */
+export class Sequence extends AnimationGroup {
+  animationGroups: AnimationGroup[];
+  sequenceDelay: number;
+  offset: number;
+  offsetEasing: (t: number) => number;
+  private _calculatedOffsets: number[];
+
+  constructor(animationGroups: AnimationGroup[], options?: SequenceOptions) {
+    // Pass an empty array to parent since we manage AnimationGroups, not Animations directly
+    // We'll override the relevant methods to work with AnimationGroups
+    const allAnimations = animationGroups.flatMap((group) => group.animations);
+    super(allAnimations, options);
+
+    this.animationGroups = animationGroups;
+    this.sequenceDelay = options?.delay ?? 0;
+    this.offset = options?.offset ?? 100;
+    this.offsetEasing = resolveEasingFunction(options?.offsetEasing);
+
+    // Calculate offsets for each animation group
+    this._calculatedOffsets = calculateOffsets(
+      animationGroups.length,
+      this.offset,
+      this.offsetEasing,
+    );
+
+    // Apply calculated delays to each animation group
+    this._applyDelays();
+  }
+
+  /**
+   * Apply the calculated staggered delays to each animation group's animations.
+   * The delay is added to any existing delay on each animation.
+   */
+  private _applyDelays(): void {
+    this.animationGroups.forEach((group, index) => {
+      const groupDelay = this.sequenceDelay + this._calculatedOffsets[index];
+
+      for (const animation of group.animations) {
+        const timing = animation.effect?.getTiming();
+        if (timing) {
+          const existingDelay = (timing.delay as number) || 0;
+          animation.effect?.updateTiming({
+            delay: existingDelay + groupDelay,
+          });
+        }
+      }
+    });
+  }
+
+  /**
+   * Get the calculated offset for a specific index in the sequence.
+   */
+  getOffsetAt(index: number): number {
+    return this._calculatedOffsets[index] ?? 0;
+  }
+
+  /**
+   * Get all calculated offsets.
+   */
+  getOffsets(): number[] {
+    return [...this._calculatedOffsets];
+  }
+
+  /**
+   * Recalculate offsets. Useful when animation groups are modified.
+   */
+  recalculateOffsets(): void {
+    this._calculatedOffsets = calculateOffsets(
+      this.animationGroups.length,
+      this.offset,
+      this.offsetEasing,
+    );
+  }
+
+  override async play(callback?: () => void): Promise<void> {
+    await this.ready;
+
+    for (const group of this.animationGroups) {
+      group.play();
+    }
+
+    // Wait for all animation groups to be ready
+    await Promise.all(this.animationGroups.map((group) => group.ready));
+
+    if (callback) {
+      callback();
+    }
+  }
+
+  override pause(): void {
+    for (const group of this.animationGroups) {
+      group.pause();
+    }
+  }
+
+  override async reverse(callback?: () => void): Promise<void> {
+    await this.ready;
+
+    for (const group of this.animationGroups) {
+      group.reverse();
+    }
+
+    // Wait for all animation groups to be ready
+    await Promise.all(this.animationGroups.map((group) => group.ready));
+
+    if (callback) {
+      callback();
+    }
+  }
+
+  override cancel(): void {
+    for (const group of this.animationGroups) {
+      group.cancel();
+    }
+  }
+
+  override setPlaybackRate(rate: number): void {
+    for (const group of this.animationGroups) {
+      group.setPlaybackRate(rate);
+    }
+  }
+
+  override async onFinish(callback: () => void): Promise<void> {
+    try {
+      await Promise.all(this.animationGroups.map((group) => group.finished));
+      callback();
+    } catch (_error) {
+      console.warn('Sequence animation was interrupted - aborting onFinish callback - ', _error);
+    }
+  }
+
+  override get finished(): Promise<Animation[]> {
+    // Return a promise that resolves when all animation groups finish
+    // We flatten the nested arrays since each group's finished returns Animation[]
+    return Promise.all(this.animationGroups.map((group) => group.finished)).then((results) =>
+      results.flat(),
+    );
+  }
+
+  override get playState(): AnimationPlayState {
+    // Return the playState of the first animation group, or 'idle' if no groups exist
+    return this.animationGroups[0]?.playState ?? 'idle';
+  }
+}
diff --git a/packages/motion/src/index.ts b/packages/motion/src/index.ts
index 29ac5116..203c57fb 100644
--- a/packages/motion/src/index.ts
+++ b/packages/motion/src/index.ts
@@ -3,3 +3,5 @@ export * from './types';
 export { registerEffects } from './api/registry';
 export * from './utils';
 export * from './easings';
+export { AnimationGroup } from './AnimationGroup';
+export { Sequence, calculateOffsets, createCubicBezier, parseCubicBezier } from './Sequence';
diff --git a/packages/motion/src/types.ts b/packages/motion/src/types.ts
index eec8bf15..f88d85a3 100644
--- a/packages/motion/src/types.ts
+++ b/packages/motion/src/types.ts
@@ -217,6 +217,30 @@ export type AnimationGroupOptions = AnimationOptions & {
   measured?: Promise<void>;
 };
 
+/**
+ * Options for creating a Sequence of AnimationGroups with staggered delays.
+ */
+export type SequenceOptions = AnimationGroupOptions & {
+  /**
+   * Fixed delay in milliseconds before the entire sequence starts.
+   * @default 0
+   */
+  delay?: number;
+  /**
+   * Base offset in milliseconds between each effect in the sequence.
+   * The actual delay for each effect is calculated using this value
+   * multiplied by the result of the offsetEasing function.
+   * @default 100
+   */
+  offset?: number;
+  /**
+   * Easing function to apply to offset calculation.
+   * Can be a JS function, a named easing from @wix/motion, or a CSS easing value.
+   * @default 'linear'
+   */
+  offsetEasing?: string | ((t: number) => number);
+};
+
 export type Shape = 'ellipse' | 'circle' | 'rectangle' | 'diamond' | 'window';
 
 export interface ScrubScrollScene {
diff --git a/packages/motion/test/Sequence.spec.ts b/packages/motion/test/Sequence.spec.ts
new file mode 100644
index 00000000..3d5bbf9d
--- /dev/null
+++ b/packages/motion/test/Sequence.spec.ts
@@ -0,0 +1,823 @@
+import { describe, expect, test, vi, beforeEach, Mock } from 'vitest';
+import { Sequence, calculateOffsets, parseCubicBezier, createCubicBezier } from '../src/Sequence';
+import { AnimationGroup } from '../src/AnimationGroup';
+import { linear, quadIn, sineOut, cubicIn, expoIn, quadOut, cubicOut } from '../src/easings';
+
+// Mock AnimationGroup
+vi.mock('../src/AnimationGroup', () => ({
+  AnimationGroup: vi.fn(),
+}));
+
+describe('Sequence', () => {
+  describe('calculateOffsets()', () => {
+    test('should return [0] for count <= 1', () => {
+      expect(calculateOffsets(0, 100, linear)).toEqual([0]);
+      expect(calculateOffsets(1, 100, linear)).toEqual([0]);
+    });
+
+    test('should calculate linear offsets correctly', () => {
+      // 5 items with 200ms offset, linear easing
+      // indices: [0, 1, 2, 3, 4], last = 4
+      // linear(0/4) * 4 * 200 = 0 * 800 = 0
+      // linear(1/4) * 4 * 200 = 0.25 * 800 = 200
+      // linear(2/4) * 4 * 200 = 0.5 * 800 = 400
+      // linear(3/4) * 4 * 200 = 0.75 * 800 = 600
+      // linear(4/4) * 4 * 200 = 1 * 800 = 800
+      const result = calculateOffsets(5, 200, linear);
+      expect(result).toEqual([0, 200, 400, 600, 800]);
+    });
+
+    test('should calculate quadIn offsets correctly', () => {
+      // 5 items with 200ms offset, quadIn easing (t^2)
+      // indices: [0, 1, 2, 3, 4], last = 4
+      // quadIn(0/4) * 4 * 200 = 0^2 * 800 = 0
+      // quadIn(1/4) * 4 * 200 = 0.0625 * 800 = 50
+      // quadIn(2/4) * 4 * 200 = 0.25 * 800 = 200
+      // quadIn(3/4) * 4 * 200 = 0.5625 * 800 = 450
+      // quadIn(4/4) * 4 * 200 = 1 * 800 = 800
+      const result = calculateOffsets(5, 200, quadIn);
+      expect(result).toEqual([0, 50, 200, 450, 800]);
+    });
+
+    test('should calculate sineOut offsets correctly', () => {
+      // 5 items with 200ms offset, sineOut easing
+      const result = calculateOffsets(5, 200, sineOut);
+      // sineOut(0) = 0
+      // sineOut(0.25) ≈ 0.3827
+      // sineOut(0.5) ≈ 0.7071
+      // sineOut(0.75) ≈ 0.9239
+      // sineOut(1) = 1
+      expect(result[0]).toBe(0);
+      expect(result[1]).toBeGreaterThan(200); // faster start
+      expect(result[2]).toBeGreaterThan(400); // much faster
+      expect(result[3]).toBeGreaterThan(600); // slowing down
+      expect(result[4]).toBe(800);
+    });
+
+    test('should calculate cubicIn offsets correctly', () => {
+      // 5 items with 100ms offset, cubicIn easing (t^3)
+      const result = calculateOffsets(5, 100, cubicIn);
+      expect(result[0]).toBe(0);
+      expect(result[1]).toBeLessThan(100); // slow start
+      expect(result[2]).toBeLessThan(200); // still slow
+      expect(result[3]).toBeLessThan(300); // accelerating
+      expect(result[4]).toBe(400); // last = 4, so 4 * 100 = 400
+    });
+
+    test('should handle different offset values', () => {
+      const result50 = calculateOffsets(3, 50, linear);
+      expect(result50).toEqual([0, 50, 100]);
+
+      const result150 = calculateOffsets(3, 150, linear);
+      expect(result150).toEqual([0, 150, 300]);
+
+      const result1000 = calculateOffsets(3, 1000, linear);
+      expect(result1000).toEqual([0, 1000, 2000]);
+    });
+
+    test('should floor results using bitwise OR', () => {
+      // Test that fractional results are floored
+      const result = calculateOffsets(3, 100, (t) => t * 0.333);
+      // (0.333 * 0) * 2 * 100 = 0
+      // (0.333 * 0.5) * 2 * 100 = 33.3 → 33
+      // (0.333 * 1) * 2 * 100 = 66.6 → 66
+      expect(result[0]).toBe(0);
+      expect(result[1]).toBe(33);
+      expect(result[2]).toBe(66);
+    });
+  });
+
+  describe('Sequence class', () => {
+    let mockAnimations: any[];
+    let mockAnimationGroups: any[];
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+
+      // Create mock animations with effects
+      mockAnimations = [
+        {
+          id: 'anim-1',
+          play: vi.fn(),
+          pause: vi.fn(),
+          reverse: vi.fn(),
+          cancel: vi.fn(),
+          ready: Promise.resolve(),
+          finished: Promise.resolve(),
+          playState: 'idle',
+          playbackRate: 1,
+          effect: {
+            getTiming: vi.fn(() => ({ delay: 0, duration: 1000, iterations: 1 })),
+            updateTiming: vi.fn(),
+            getComputedTiming: vi.fn(() => ({ progress: 0 })),
+          },
+        },
+        {
+          id: 'anim-2',
+          play: vi.fn(),
+          pause: vi.fn(),
+          reverse: vi.fn(),
+          cancel: vi.fn(),
+          ready: Promise.resolve(),
+          finished: Promise.resolve(),
+          playState: 'idle',
+          playbackRate: 1,
+          effect: {
+            getTiming: vi.fn(() => ({ delay: 100, duration: 800, iterations: 1 })),
+            updateTiming: vi.fn(),
+            getComputedTiming: vi.fn(() => ({ progress: 0.5 })),
+          },
+        },
+        {
+          id: 'anim-3',
+          play: vi.fn(),
+          pause: vi.fn(),
+          reverse: vi.fn(),
+          cancel: vi.fn(),
+          ready: Promise.resolve(),
+          finished: Promise.resolve(),
+          playState: 'running',
+          playbackRate: 1,
+          effect: {
+            getTiming: vi.fn(() => ({ delay: 50, duration: 1200, iterations: 1 })),
+            updateTiming: vi.fn(),
+            getComputedTiming: vi.fn(() => ({ progress: 0.25 })),
+          },
+        },
+      ];
+
+      // Create mock AnimationGroups
+      mockAnimationGroups = [
+        {
+          animations: [mockAnimations[0]],
+          options: {},
+          ready: Promise.resolve(),
+          isCSS: false,
+          play: vi.fn().mockResolvedValue(undefined),
+          pause: vi.fn(),
+          reverse: vi.fn().mockResolvedValue(undefined),
+          cancel: vi.fn(),
+          setPlaybackRate: vi.fn(),
+          getProgress: vi.fn(() => 0),
+          finished: Promise.resolve(),
+          playState: 'idle',
+        },
+        {
+          animations: [mockAnimations[1]],
+          options: {},
+          ready: Promise.resolve(),
+          isCSS: false,
+          play: vi.fn().mockResolvedValue(undefined),
+          pause: vi.fn(),
+          reverse: vi.fn().mockResolvedValue(undefined),
+          cancel: vi.fn(),
+          setPlaybackRate: vi.fn(),
+          getProgress: vi.fn(() => 0.5),
+          finished: Promise.resolve(),
+          playState: 'idle',
+        },
+        {
+          animations: [mockAnimations[2]],
+          options: {},
+          ready: Promise.resolve(),
+          isCSS: false,
+          play: vi.fn().mockResolvedValue(undefined),
+          pause: vi.fn(),
+          reverse: vi.fn().mockResolvedValue(undefined),
+          cancel: vi.fn(),
+          setPlaybackRate: vi.fn(),
+          getProgress: vi.fn(() => 0.25),
+          finished: Promise.resolve(),
+          playState: 'running',
+        },
+      ];
+
+      // Mock AnimationGroup constructor to pass through the groups
+      (AnimationGroup as Mock).mockImplementation(function (
+        this: any,
+        animations: any[],
+        options: any,
+      ) {
+        this.animations = animations;
+        this.options = options;
+        this.ready = options?.measured || Promise.resolve();
+        this.isCSS = false;
+        return this;
+      });
+    });
+
+    test('should create a Sequence with default options', () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      expect(sequence.animationGroups).toBe(mockAnimationGroups);
+      expect(sequence.sequenceDelay).toBe(0);
+      expect(sequence.offset).toBe(100);
+      expect(typeof sequence.offsetEasing).toBe('function');
+    });
+
+    test('should create a Sequence with custom delay', () => {
+      const sequence = new Sequence(mockAnimationGroups, { delay: 500 });
+
+      expect(sequence.sequenceDelay).toBe(500);
+    });
+
+    test('should create a Sequence with custom offset', () => {
+      const sequence = new Sequence(mockAnimationGroups, { offset: 200 });
+
+      expect(sequence.offset).toBe(200);
+    });
+
+    test('should create a Sequence with string easing name', () => {
+      const sequence = new Sequence(mockAnimationGroups, { offsetEasing: 'quadIn' });
+
+      // Test that it resolves to the quadIn function
+      expect(sequence.offsetEasing(0.5)).toBeCloseTo(quadIn(0.5));
+    });
+
+    test('should create a Sequence with custom easing function', () => {
+      const customEasing = (t: number) => t * t * t;
+      const sequence = new Sequence(mockAnimationGroups, { offsetEasing: customEasing });
+
+      expect(sequence.offsetEasing).toBe(customEasing);
+    });
+
+    test('should fall back to linear for unknown easing names', () => {
+      const sequence = new Sequence(mockAnimationGroups, { offsetEasing: 'unknownEasing' });
+
+      // Should fall back to linear
+      expect(sequence.offsetEasing(0.5)).toBe(0.5);
+    });
+
+    test('should calculate correct offsets on construction', () => {
+      const sequence = new Sequence(mockAnimationGroups, { offset: 100 });
+      const offsets = sequence.getOffsets();
+
+      // 3 groups, linear easing, 100ms offset
+      // last = 2
+      // linear(0/2) * 2 * 100 = 0
+      // linear(1/2) * 2 * 100 = 100
+      // linear(2/2) * 2 * 100 = 200
+      expect(offsets).toEqual([0, 100, 200]);
+    });
+
+    test('should apply delays to animation groups', () => {
+      // Creating the sequence applies delays to the animation groups
+      new Sequence(mockAnimationGroups, { delay: 50, offset: 100 });
+
+      // First group: delay = 50 + 0 = 50, existing delay = 0 → total = 50
+      expect(mockAnimations[0].effect.updateTiming).toHaveBeenCalledWith({ delay: 50 });
+
+      // Second group: delay = 50 + 100 = 150, existing delay = 100 → total = 250
+      expect(mockAnimations[1].effect.updateTiming).toHaveBeenCalledWith({ delay: 250 });
+
+      // Third group: delay = 50 + 200 = 250, existing delay = 50 → total = 300
+      expect(mockAnimations[2].effect.updateTiming).toHaveBeenCalledWith({ delay: 300 });
+    });
+
+    test('getOffsetAt should return offset for specific index', () => {
+      const sequence = new Sequence(mockAnimationGroups, { offset: 150 });
+
+      expect(sequence.getOffsetAt(0)).toBe(0);
+      expect(sequence.getOffsetAt(1)).toBe(150);
+      expect(sequence.getOffsetAt(2)).toBe(300);
+      expect(sequence.getOffsetAt(99)).toBe(0); // out of bounds
+    });
+
+    test('recalculateOffsets should update offsets', () => {
+      const sequence = new Sequence(mockAnimationGroups, { offset: 100 });
+      expect(sequence.getOffsets()).toEqual([0, 100, 200]);
+
+      // Change offset and recalculate
+      sequence.offset = 200;
+      sequence.recalculateOffsets();
+
+      expect(sequence.getOffsets()).toEqual([0, 200, 400]);
+    });
+
+    test('play should call play on all animation groups', async () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      await sequence.play();
+
+      for (const group of mockAnimationGroups) {
+        expect(group.play).toHaveBeenCalled();
+      }
+    });
+
+    test('play should execute callback after all groups are ready', async () => {
+      const sequence = new Sequence(mockAnimationGroups);
+      const callback = vi.fn();
+
+      await sequence.play(callback);
+
+      expect(callback).toHaveBeenCalled();
+    });
+
+    test('pause should call pause on all animation groups', () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      sequence.pause();
+
+      for (const group of mockAnimationGroups) {
+        expect(group.pause).toHaveBeenCalled();
+      }
+    });
+
+    test('reverse should call reverse on all animation groups', async () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      await sequence.reverse();
+
+      for (const group of mockAnimationGroups) {
+        expect(group.reverse).toHaveBeenCalled();
+      }
+    });
+
+    test('reverse should execute callback after all groups are ready', async () => {
+      const sequence = new Sequence(mockAnimationGroups);
+      const callback = vi.fn();
+
+      await sequence.reverse(callback);
+
+      expect(callback).toHaveBeenCalled();
+    });
+
+    test('cancel should call cancel on all animation groups', () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      sequence.cancel();
+
+      for (const group of mockAnimationGroups) {
+        expect(group.cancel).toHaveBeenCalled();
+      }
+    });
+
+    test('setPlaybackRate should set rate on all animation groups', () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      sequence.setPlaybackRate(2);
+
+      for (const group of mockAnimationGroups) {
+        expect(group.setPlaybackRate).toHaveBeenCalledWith(2);
+      }
+    });
+
+    test('onFinish should call callback when all groups finish', async () => {
+      const sequence = new Sequence(mockAnimationGroups);
+      const callback = vi.fn();
+
+      await sequence.onFinish(callback);
+
+      expect(callback).toHaveBeenCalled();
+    });
+
+    test('finished getter should return promise that resolves when all groups finish', async () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      const result = await sequence.finished;
+
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    test('playState getter should return first group playState', () => {
+      const sequence = new Sequence(mockAnimationGroups);
+
+      // mockAnimationGroups[0].playState is 'idle'
+      expect(sequence.playState).toBe('idle');
+    });
+
+    test('playState should return idle for empty sequence', () => {
+      const emptySequence = new Sequence([]);
+
+      expect(emptySequence.playState).toBe('idle');
+    });
+  });
+
+  describe('Sequence with various easing functions', () => {
+    test('should correctly apply expoIn easing', () => {
+      const result = calculateOffsets(5, 100, expoIn);
+
+      // expoIn has very slow start, fast end
+      expect(result[0]).toBe(0);
+      expect(result[1]).toBeLessThan(10); // very slow start
+      expect(result[4]).toBe(400); // ends at 4 * 100
+    });
+
+    test('should correctly apply custom exponential easing', () => {
+      const customExpo = (t: number) => t ** 4; // quartic
+
+      const result = calculateOffsets(5, 100, customExpo);
+
+      expect(result[0]).toBe(0);
+      expect(result[1]).toBeLessThan(50); // slow start
+      expect(result[4]).toBe(400);
+    });
+  });
+
+  describe('parseCubicBezier()', () => {
+    test('should parse valid cubic-bezier string', () => {
+      const fn = parseCubicBezier('cubic-bezier(0.4, 0, 0.2, 1)');
+      expect(fn).not.toBeNull();
+      expect(typeof fn).toBe('function');
+    });
+
+    test('should return correct values for standard ease-out curve', () => {
+      // Standard Material Design ease-out: cubic-bezier(0, 0, 0.2, 1)
+      const fn = parseCubicBezier('cubic-bezier(0, 0, 0.2, 1)')!;
+
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+      // This ease-out starts fast (y > x for small x values)
+      expect(fn(0.25)).toBeGreaterThan(0.25);
+      expect(fn(0.5)).toBeGreaterThan(0.5);
+    });
+
+    test('should return correct values for ease-in curve', () => {
+      // Standard ease-in: cubic-bezier(0.4, 0, 1, 1)
+      const fn = parseCubicBezier('cubic-bezier(0.4, 0, 1, 1)')!;
+
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+      // ease-in starts slow
+      expect(fn(0.25)).toBeLessThan(0.25);
+      expect(fn(0.5)).toBeLessThan(0.5);
+    });
+
+    test('should handle overshoot cubic-bezier values', () => {
+      // Overshoot: cubic-bezier(0.34, 1.56, 0.64, 1)
+      const fn = parseCubicBezier('cubic-bezier(0.34, 1.56, 0.64, 1)')!;
+
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+      // The curve overshoots past 1 in the middle
+      const midValues = [fn(0.3), fn(0.4), fn(0.5), fn(0.6)];
+      const hasOvershoot = midValues.some((v) => v > 1);
+      expect(hasOvershoot).toBe(true);
+    });
+
+    test('should handle whitespace variations', () => {
+      const fn1 = parseCubicBezier('cubic-bezier(0.4,0,0.2,1)');
+      const fn2 = parseCubicBezier('cubic-bezier( 0.4 , 0 , 0.2 , 1 )');
+      const fn3 = parseCubicBezier('cubic-bezier(  0.4,  0,  0.2,  1  )');
+
+      expect(fn1).not.toBeNull();
+      expect(fn2).not.toBeNull();
+      expect(fn3).not.toBeNull();
+
+      // All should produce same results
+      expect(fn1!(0.5)).toBeCloseTo(fn2!(0.5), 5);
+      expect(fn2!(0.5)).toBeCloseTo(fn3!(0.5), 5);
+    });
+
+    test('should be case insensitive', () => {
+      const fn1 = parseCubicBezier('cubic-bezier(0.4, 0, 0.2, 1)');
+      const fn2 = parseCubicBezier('CUBIC-BEZIER(0.4, 0, 0.2, 1)');
+      const fn3 = parseCubicBezier('Cubic-Bezier(0.4, 0, 0.2, 1)');
+
+      expect(fn1).not.toBeNull();
+      expect(fn2).not.toBeNull();
+      expect(fn3).not.toBeNull();
+    });
+
+    test('should return null for invalid strings', () => {
+      expect(parseCubicBezier('ease')).toBeNull();
+      expect(parseCubicBezier('linear')).toBeNull();
+      expect(parseCubicBezier('cubic-bezier()')).toBeNull();
+      expect(parseCubicBezier('cubic-bezier(0.4)')).toBeNull();
+      expect(parseCubicBezier('cubic-bezier(0.4, 0, 0.2)')).toBeNull();
+      expect(parseCubicBezier('bezier(0.4, 0, 0.2, 1)')).toBeNull();
+      expect(parseCubicBezier('cubic-bezier(a, b, c, d)')).toBeNull();
+    });
+
+    test('should handle negative values', () => {
+      // Back easing uses negative values
+      const fn = parseCubicBezier('cubic-bezier(0.6, -0.28, 0.735, 0.045)')!;
+
+      expect(fn).not.toBeNull();
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+    });
+
+    test('should handle values greater than 1 for y coordinates', () => {
+      // Values > 1 for y1, y2 cause overshoot
+      const fn = parseCubicBezier('cubic-bezier(0.175, 0.885, 0.32, 1.275)')!;
+
+      expect(fn).not.toBeNull();
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+    });
+  });
+
+  describe('createCubicBezier()', () => {
+    test('should create linear-like function for (0, 0, 1, 1)', () => {
+      const fn = createCubicBezier(0, 0, 1, 1);
+
+      expect(fn(0)).toBe(0);
+      expect(fn(0.5)).toBeCloseTo(0.5, 2);
+      expect(fn(1)).toBe(1);
+    });
+
+    test('should create ease-out function for (0, 0, 0.2, 1)', () => {
+      const fn = createCubicBezier(0, 0, 0.2, 1);
+
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+      // ease-out: fast start, slow end
+      expect(fn(0.25)).toBeGreaterThan(0.25);
+    });
+
+    test('should create ease-in function for (0.4, 0, 1, 1)', () => {
+      const fn = createCubicBezier(0.4, 0, 1, 1);
+
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+      // ease-in: slow start, fast end
+      expect(fn(0.25)).toBeLessThan(0.25);
+    });
+
+    test('should handle boundary values correctly', () => {
+      const fn = createCubicBezier(0.25, 0.1, 0.25, 1);
+
+      expect(fn(0)).toBe(0);
+      expect(fn(1)).toBe(1);
+      expect(fn(-0.5)).toBe(0); // clamp below 0
+      expect(fn(1.5)).toBe(1); // clamp above 1
+    });
+  });
+
+  describe('Sequence easing resolution', () => {
+    let mockAnimationGroups: any[];
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+
+      mockAnimationGroups = [
+        {
+          animations: [
+            {
+              effect: {
+                getTiming: vi.fn(() => ({ delay: 0 })),
+                updateTiming: vi.fn(),
+              },
+            },
+          ],
+          play: vi.fn().mockResolvedValue(undefined),
+          pause: vi.fn(),
+          reverse: vi.fn().mockResolvedValue(undefined),
+          cancel: vi.fn(),
+          setPlaybackRate: vi.fn(),
+          getProgress: vi.fn(() => 0),
+          finished: Promise.resolve(),
+          playState: 'idle',
+        },
+        {
+          animations: [
+            {
+              effect: {
+                getTiming: vi.fn(() => ({ delay: 0 })),
+                updateTiming: vi.fn(),
+              },
+            },
+          ],
+          play: vi.fn().mockResolvedValue(undefined),
+          pause: vi.fn(),
+          reverse: vi.fn().mockResolvedValue(undefined),
+          cancel: vi.fn(),
+          setPlaybackRate: vi.fn(),
+          getProgress: vi.fn(() => 0),
+          finished: Promise.resolve(),
+          playState: 'idle',
+        },
+        {
+          animations: [
+            {
+              effect: {
+                getTiming: vi.fn(() => ({ delay: 0 })),
+                updateTiming: vi.fn(),
+              },
+            },
+          ],
+          play: vi.fn().mockResolvedValue(undefined),
+          pause: vi.fn(),
+          reverse: vi.fn().mockResolvedValue(undefined),
+          cancel: vi.fn(),
+          setPlaybackRate: vi.fn(),
+          getProgress: vi.fn(() => 0),
+          finished: Promise.resolve(),
+          playState: 'idle',
+        },
+      ];
+
+      (AnimationGroup as Mock).mockImplementation(function (
+        this: any,
+        animations: any[],
+        options: any,
+      ) {
+        this.animations = animations;
+        this.options = options;
+        this.ready = Promise.resolve();
+        this.isCSS = false;
+        return this;
+      });
+    });
+
+    describe('Named easing strings', () => {
+      test('should resolve "linear" easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'linear',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBeCloseTo(linear(0.5));
+        expect(sequence.getOffsets()).toEqual([0, 100, 200]);
+      });
+
+      test('should resolve "quadIn" easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'quadIn',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBeCloseTo(quadIn(0.5));
+      });
+
+      test('should resolve "quadOut" easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'quadOut',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBeCloseTo(quadOut(0.5));
+        // quadOut is faster at start, so middle item should have higher offset
+        expect(sequence.getOffsets()[1]).toBeGreaterThan(100);
+      });
+
+      test('should resolve "cubicIn" easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'cubicIn',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBeCloseTo(cubicIn(0.5));
+      });
+
+      test('should resolve "cubicOut" easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'cubicOut',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBeCloseTo(cubicOut(0.5));
+      });
+
+      test('should resolve "expoIn" easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'expoIn',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBeCloseTo(expoIn(0.5));
+      });
+
+      test('should resolve "sineOut" easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'sineOut',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBeCloseTo(sineOut(0.5));
+      });
+
+      test('should fall back to linear for unknown easing name', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'unknownEasing',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBe(0.5); // linear
+      });
+    });
+
+    describe('CSS cubic-bezier strings', () => {
+      test('should resolve cubic-bezier easing string', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0)).toBe(0);
+        expect(sequence.offsetEasing(1)).toBe(1);
+        // Material ease-out: fast start
+        expect(sequence.offsetEasing(0.5)).toBeGreaterThan(0.5);
+      });
+
+      test('should resolve cubic-bezier with negative values (back easing)', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'cubic-bezier(0.6, -0.28, 0.735, 0.045)',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0)).toBe(0);
+        expect(sequence.offsetEasing(1)).toBe(1);
+      });
+
+      test('should resolve cubic-bezier with overshoot values', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0)).toBe(0);
+        expect(sequence.offsetEasing(1)).toBe(1);
+        // Should overshoot in the middle
+        const midValues = [0.3, 0.4, 0.5, 0.6].map((t) => sequence.offsetEasing(t));
+        expect(midValues.some((v) => v > 1)).toBe(true);
+      });
+
+      test('should handle CSS standard ease curves', () => {
+        // CSS ease: cubic-bezier(0.25, 0.1, 0.25, 1)
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'cubic-bezier(0.25, 0.1, 0.25, 1)',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0)).toBe(0);
+        expect(sequence.offsetEasing(1)).toBe(1);
+      });
+
+      test('should fall back to linear for malformed cubic-bezier', () => {
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: 'cubic-bezier(invalid)',
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBe(0.5); // linear fallback
+      });
+    });
+
+    describe('Custom function easings', () => {
+      test('should use provided function directly', () => {
+        const customEasing = (t: number) => t * t; // quadratic
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: customEasing,
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing).toBe(customEasing);
+        expect(sequence.offsetEasing(0.5)).toBe(0.25);
+      });
+
+      test('should handle cubic function', () => {
+        const cubicFn = (t: number) => t * t * t;
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: cubicFn,
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.5)).toBe(0.125);
+      });
+
+      test('should handle step function', () => {
+        const stepFn = (t: number) => (t < 0.5 ? 0 : 1);
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: stepFn,
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0.25)).toBe(0);
+        expect(sequence.offsetEasing(0.75)).toBe(1);
+      });
+
+      test('should handle bounce-like function', () => {
+        // Simple bounce that overshoots
+        const bounceFn = (t: number) => {
+          if (t < 0.5) return 4 * t * t * t;
+          return 1 - Math.pow(-2 * t + 2, 3) / 2;
+        };
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: bounceFn,
+          offset: 100,
+        });
+
+        expect(sequence.offsetEasing(0)).toBe(0);
+        expect(sequence.offsetEasing(1)).toBe(1);
+      });
+
+      test('should calculate offsets correctly with custom function', () => {
+        // Square root for ease-out effect
+        const sqrtEasing = (t: number) => Math.sqrt(t);
+        const sequence = new Sequence(mockAnimationGroups, {
+          offsetEasing: sqrtEasing,
+          offset: 100,
+        });
+
+        const offsets = sequence.getOffsets();
+        expect(offsets[0]).toBe(0);
+        // sqrt(0.5) ≈ 0.707, so offset should be ~141
+        expect(offsets[1]).toBeGreaterThan(130);
+        expect(offsets[1]).toBeLessThan(150);
+        expect(offsets[2]).toBe(200);
+      });
+    });
+  });
+});

From 32a21491cfd0770c5c5369e4f762da6a9668fdad Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Sun, 1 Feb 2026 12:04:41 +0200
Subject: [PATCH 07/29] implement sequences

---
 packages/motion/src/Sequence.ts       |  73 +--------
 packages/motion/test/Sequence.spec.ts | 213 ++++++++------------------
 2 files changed, 65 insertions(+), 221 deletions(-)

diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index 9bdfe645..b42987c2 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -235,73 +235,8 @@ export class Sequence extends AnimationGroup {
     );
   }
 
-  override async play(callback?: () => void): Promise<void> {
-    await this.ready;
-
-    for (const group of this.animationGroups) {
-      group.play();
-    }
-
-    // Wait for all animation groups to be ready
-    await Promise.all(this.animationGroups.map((group) => group.ready));
-
-    if (callback) {
-      callback();
-    }
-  }
-
-  override pause(): void {
-    for (const group of this.animationGroups) {
-      group.pause();
-    }
-  }
-
-  override async reverse(callback?: () => void): Promise<void> {
-    await this.ready;
-
-    for (const group of this.animationGroups) {
-      group.reverse();
-    }
-
-    // Wait for all animation groups to be ready
-    await Promise.all(this.animationGroups.map((group) => group.ready));
-
-    if (callback) {
-      callback();
-    }
-  }
-
-  override cancel(): void {
-    for (const group of this.animationGroups) {
-      group.cancel();
-    }
-  }
-
-  override setPlaybackRate(rate: number): void {
-    for (const group of this.animationGroups) {
-      group.setPlaybackRate(rate);
-    }
-  }
-
-  override async onFinish(callback: () => void): Promise<void> {
-    try {
-      await Promise.all(this.animationGroups.map((group) => group.finished));
-      callback();
-    } catch (_error) {
-      console.warn('Sequence animation was interrupted - aborting onFinish callback - ', _error);
-    }
-  }
-
-  override get finished(): Promise<Animation[]> {
-    // Return a promise that resolves when all animation groups finish
-    // We flatten the nested arrays since each group's finished returns Animation[]
-    return Promise.all(this.animationGroups.map((group) => group.finished)).then((results) =>
-      results.flat(),
-    );
-  }
-
-  override get playState(): AnimationPlayState {
-    // Return the playState of the first animation group, or 'idle' if no groups exist
-    return this.animationGroups[0]?.playState ?? 'idle';
-  }
+  // Note: play(), pause(), reverse(), cancel(), setPlaybackRate(), onFinish(),
+  // finished, and playState are inherited from AnimationGroup.
+  // Since we pass all flattened animations to super(), the parent's
+  // implementations work correctly on the same Animation objects.
 }
diff --git a/packages/motion/test/Sequence.spec.ts b/packages/motion/test/Sequence.spec.ts
index 3d5bbf9d..cc9efbad 100644
--- a/packages/motion/test/Sequence.spec.ts
+++ b/packages/motion/test/Sequence.spec.ts
@@ -1,12 +1,14 @@
-import { describe, expect, test, vi, beforeEach, Mock } from 'vitest';
+import { describe, expect, test, vi, beforeEach, beforeAll } from 'vitest';
 import { Sequence, calculateOffsets, parseCubicBezier, createCubicBezier } from '../src/Sequence';
 import { AnimationGroup } from '../src/AnimationGroup';
 import { linear, quadIn, sineOut, cubicIn, expoIn, quadOut, cubicOut } from '../src/easings';
 
-// Mock AnimationGroup
-vi.mock('../src/AnimationGroup', () => ({
-  AnimationGroup: vi.fn(),
-}));
+// Stub CSSAnimation for Node.js environment
+beforeAll(() => {
+  if (typeof globalThis.CSSAnimation === 'undefined') {
+    (globalThis as any).CSSAnimation = class CSSAnimation {};
+  }
+});
 
 describe('Sequence', () => {
   describe('calculateOffsets()', () => {
@@ -89,7 +91,7 @@ describe('Sequence', () => {
 
   describe('Sequence class', () => {
     let mockAnimations: any[];
-    let mockAnimationGroups: any[];
+    let mockAnimationGroups: AnimationGroup[];
 
     beforeEach(() => {
       vi.clearAllMocks();
@@ -146,64 +148,12 @@ describe('Sequence', () => {
         },
       ];
 
-      // Create mock AnimationGroups
+      // Create real AnimationGroup instances with mock animations
       mockAnimationGroups = [
-        {
-          animations: [mockAnimations[0]],
-          options: {},
-          ready: Promise.resolve(),
-          isCSS: false,
-          play: vi.fn().mockResolvedValue(undefined),
-          pause: vi.fn(),
-          reverse: vi.fn().mockResolvedValue(undefined),
-          cancel: vi.fn(),
-          setPlaybackRate: vi.fn(),
-          getProgress: vi.fn(() => 0),
-          finished: Promise.resolve(),
-          playState: 'idle',
-        },
-        {
-          animations: [mockAnimations[1]],
-          options: {},
-          ready: Promise.resolve(),
-          isCSS: false,
-          play: vi.fn().mockResolvedValue(undefined),
-          pause: vi.fn(),
-          reverse: vi.fn().mockResolvedValue(undefined),
-          cancel: vi.fn(),
-          setPlaybackRate: vi.fn(),
-          getProgress: vi.fn(() => 0.5),
-          finished: Promise.resolve(),
-          playState: 'idle',
-        },
-        {
-          animations: [mockAnimations[2]],
-          options: {},
-          ready: Promise.resolve(),
-          isCSS: false,
-          play: vi.fn().mockResolvedValue(undefined),
-          pause: vi.fn(),
-          reverse: vi.fn().mockResolvedValue(undefined),
-          cancel: vi.fn(),
-          setPlaybackRate: vi.fn(),
-          getProgress: vi.fn(() => 0.25),
-          finished: Promise.resolve(),
-          playState: 'running',
-        },
+        new AnimationGroup([mockAnimations[0]] as unknown as Animation[]),
+        new AnimationGroup([mockAnimations[1]] as unknown as Animation[]),
+        new AnimationGroup([mockAnimations[2]] as unknown as Animation[]),
       ];
-
-      // Mock AnimationGroup constructor to pass through the groups
-      (AnimationGroup as Mock).mockImplementation(function (
-        this: any,
-        animations: any[],
-        options: any,
-      ) {
-        this.animations = animations;
-        this.options = options;
-        this.ready = options?.measured || Promise.resolve();
-        this.isCSS = false;
-        return this;
-      });
     });
 
     test('should create a Sequence with default options', () => {
@@ -294,17 +244,21 @@ describe('Sequence', () => {
       expect(sequence.getOffsets()).toEqual([0, 200, 400]);
     });
 
-    test('play should call play on all animation groups', async () => {
+    // Note: play(), pause(), reverse(), cancel(), setPlaybackRate(), onFinish(),
+    // finished, and playState are inherited from AnimationGroup.
+    // These tests verify that the underlying animations are controlled correctly.
+
+    test('play should call play on all underlying animations', async () => {
       const sequence = new Sequence(mockAnimationGroups);
 
       await sequence.play();
 
-      for (const group of mockAnimationGroups) {
-        expect(group.play).toHaveBeenCalled();
+      for (const animation of mockAnimations) {
+        expect(animation.play).toHaveBeenCalled();
       }
     });
 
-    test('play should execute callback after all groups are ready', async () => {
+    test('play should execute callback after all animations are ready', async () => {
       const sequence = new Sequence(mockAnimationGroups);
       const callback = vi.fn();
 
@@ -313,27 +267,27 @@ describe('Sequence', () => {
       expect(callback).toHaveBeenCalled();
     });
 
-    test('pause should call pause on all animation groups', () => {
+    test('pause should call pause on all underlying animations', () => {
       const sequence = new Sequence(mockAnimationGroups);
 
       sequence.pause();
 
-      for (const group of mockAnimationGroups) {
-        expect(group.pause).toHaveBeenCalled();
+      for (const animation of mockAnimations) {
+        expect(animation.pause).toHaveBeenCalled();
       }
     });
 
-    test('reverse should call reverse on all animation groups', async () => {
+    test('reverse should call reverse on all underlying animations', async () => {
       const sequence = new Sequence(mockAnimationGroups);
 
       await sequence.reverse();
 
-      for (const group of mockAnimationGroups) {
-        expect(group.reverse).toHaveBeenCalled();
+      for (const animation of mockAnimations) {
+        expect(animation.reverse).toHaveBeenCalled();
       }
     });
 
-    test('reverse should execute callback after all groups are ready', async () => {
+    test('reverse should execute callback after all animations are ready', async () => {
       const sequence = new Sequence(mockAnimationGroups);
       const callback = vi.fn();
 
@@ -342,27 +296,27 @@ describe('Sequence', () => {
       expect(callback).toHaveBeenCalled();
     });
 
-    test('cancel should call cancel on all animation groups', () => {
+    test('cancel should call cancel on all underlying animations', () => {
       const sequence = new Sequence(mockAnimationGroups);
 
       sequence.cancel();
 
-      for (const group of mockAnimationGroups) {
-        expect(group.cancel).toHaveBeenCalled();
+      for (const animation of mockAnimations) {
+        expect(animation.cancel).toHaveBeenCalled();
       }
     });
 
-    test('setPlaybackRate should set rate on all animation groups', () => {
+    test('setPlaybackRate should set rate on all underlying animations', () => {
       const sequence = new Sequence(mockAnimationGroups);
 
       sequence.setPlaybackRate(2);
 
-      for (const group of mockAnimationGroups) {
-        expect(group.setPlaybackRate).toHaveBeenCalledWith(2);
+      for (const animation of mockAnimations) {
+        expect(animation.playbackRate).toBe(2);
       }
     });
 
-    test('onFinish should call callback when all groups finish', async () => {
+    test('onFinish should call callback when all animations finish', async () => {
       const sequence = new Sequence(mockAnimationGroups);
       const callback = vi.fn();
 
@@ -371,7 +325,7 @@ describe('Sequence', () => {
       expect(callback).toHaveBeenCalled();
     });
 
-    test('finished getter should return promise that resolves when all groups finish', async () => {
+    test('finished getter should return promise that resolves when all animations finish', async () => {
       const sequence = new Sequence(mockAnimationGroups);
 
       const result = await sequence.finished;
@@ -379,17 +333,17 @@ describe('Sequence', () => {
       expect(Array.isArray(result)).toBe(true);
     });
 
-    test('playState getter should return first group playState', () => {
+    test('playState getter should return first animation playState', () => {
       const sequence = new Sequence(mockAnimationGroups);
 
-      // mockAnimationGroups[0].playState is 'idle'
+      // mockAnimations[0].playState is 'idle'
       expect(sequence.playState).toBe('idle');
     });
 
-    test('playState should return idle for empty sequence', () => {
+    test('playState should return undefined for empty sequence', () => {
       const emptySequence = new Sequence([]);
 
-      expect(emptySequence.playState).toBe('idle');
+      expect(emptySequence.playState).toBeUndefined();
     });
   });
 
@@ -546,79 +500,34 @@ describe('Sequence', () => {
   });
 
   describe('Sequence easing resolution', () => {
-    let mockAnimationGroups: any[];
+    let mockAnimationGroups: AnimationGroup[];
 
     beforeEach(() => {
       vi.clearAllMocks();
 
-      mockAnimationGroups = [
-        {
-          animations: [
-            {
-              effect: {
-                getTiming: vi.fn(() => ({ delay: 0 })),
-                updateTiming: vi.fn(),
-              },
-            },
-          ],
-          play: vi.fn().mockResolvedValue(undefined),
-          pause: vi.fn(),
-          reverse: vi.fn().mockResolvedValue(undefined),
-          cancel: vi.fn(),
-          setPlaybackRate: vi.fn(),
-          getProgress: vi.fn(() => 0),
-          finished: Promise.resolve(),
-          playState: 'idle',
-        },
-        {
-          animations: [
-            {
-              effect: {
-                getTiming: vi.fn(() => ({ delay: 0 })),
-                updateTiming: vi.fn(),
-              },
-            },
-          ],
-          play: vi.fn().mockResolvedValue(undefined),
-          pause: vi.fn(),
-          reverse: vi.fn().mockResolvedValue(undefined),
-          cancel: vi.fn(),
-          setPlaybackRate: vi.fn(),
-          getProgress: vi.fn(() => 0),
-          finished: Promise.resolve(),
-          playState: 'idle',
-        },
-        {
-          animations: [
-            {
-              effect: {
-                getTiming: vi.fn(() => ({ delay: 0 })),
-                updateTiming: vi.fn(),
-              },
-            },
-          ],
-          play: vi.fn().mockResolvedValue(undefined),
-          pause: vi.fn(),
-          reverse: vi.fn().mockResolvedValue(undefined),
-          cancel: vi.fn(),
-          setPlaybackRate: vi.fn(),
-          getProgress: vi.fn(() => 0),
-          finished: Promise.resolve(),
-          playState: 'idle',
+      // Create mock animations
+      const createMockAnimation = () => ({
+        play: vi.fn(),
+        pause: vi.fn(),
+        reverse: vi.fn(),
+        cancel: vi.fn(),
+        ready: Promise.resolve(),
+        finished: Promise.resolve(),
+        playState: 'idle',
+        playbackRate: 1,
+        effect: {
+          getTiming: vi.fn(() => ({ delay: 0 })),
+          updateTiming: vi.fn(),
+          getComputedTiming: vi.fn(() => ({ progress: 0 })),
         },
-      ];
-
-      (AnimationGroup as Mock).mockImplementation(function (
-        this: any,
-        animations: any[],
-        options: any,
-      ) {
-        this.animations = animations;
-        this.options = options;
-        this.ready = Promise.resolve();
-        this.isCSS = false;
-        return this;
       });
+
+      // Create real AnimationGroup instances
+      mockAnimationGroups = [
+        new AnimationGroup([createMockAnimation()] as unknown as Animation[]),
+        new AnimationGroup([createMockAnimation()] as unknown as Animation[]),
+        new AnimationGroup([createMockAnimation()] as unknown as Animation[]),
+      ];
     });
 
     describe('Named easing strings', () => {

From 8edb4736b57b0ac45ff1b056174f4fc75268524e Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Sun, 1 Feb 2026 14:53:52 +0200
Subject: [PATCH 08/29] refactor Interact.rs

---
 packages/interact/src/core/Interact.ts | 38 +++++++++++++-------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index dee5efa3..b83e42a8 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -20,6 +20,14 @@ function _convertToKeyTemplate(key: string) {
   return key.replace(/\[([-\w]+)]/g, '[]');
 }
 
+/** Keys that indicate an effect has its own definition (not just a reference) */
+const EFFECT_DEFINITION_KEYS = ['duration', 'namedEffect', 'keyframeEffect', 'customEffect'] as const;
+
+/** Check if an effect is just a reference to another effect (has effectId but no definition) */
+function isEffectReference(effect: Effect | EffectRef): effect is EffectRef {
+  return 'effectId' in effect && !EFFECT_DEFINITION_KEYS.some((key) => key in effect);
+}
+
 export class Interact {
   static defineInteractElement?: () => boolean;
   dataCache: InteractCache;
@@ -260,16 +268,14 @@ function resolveSequence(
   configSequences: Record<string, Sequence>,
 ): Sequence | null {
   const sequenceId = seqOrRef.sequenceId;
-
-  // Check if it's a reference (has sequenceId but no effects)
   if (!('effects' in seqOrRef) || !seqOrRef.effects) {
     const referencedSequence = configSequences[sequenceId];
+
     if (!referencedSequence) {
       console.warn(`Sequence with id "${sequenceId}" not found in config.sequences`);
       return null;
     }
 
-    // Merge overrides from the reference
     return {
       ...referencedSequence,
       delay: seqOrRef.delay ?? referencedSequence.delay,
@@ -278,8 +284,7 @@ function resolveSequence(
     };
   }
 
-  // It's an inline sequence
-  return seqOrRef as Sequence;
+  return seqOrRef;
 }
 
 /**
@@ -292,7 +297,6 @@ function expandSequenceEffects(
 ): (Effect | EffectRef)[] {
   const expandedEffects: (Effect | EffectRef)[] = [];
 
-  // Process sequences and add their effects with calculated delays
   if (interaction.sequences) {
     for (const seqOrRef of interaction.sequences) {
       const sequence = resolveSequence(seqOrRef, configSequences);
@@ -301,28 +305,24 @@ function expandSequenceEffects(
       const delay = sequence.delay ?? 0;
       const offset = sequence.offset ?? 100;
       const easingFn = resolveEasingFunction(sequence.offsetEasing);
-
-      // Calculate staggered offsets for this sequence
       const offsets = calculateOffsets(sequence.effects.length, offset, easingFn);
 
-      // Process each effect in the sequence
       sequence.effects.forEach((effect, index) => {
-        // Resolve effect reference if needed
-        let resolvedEffect: Effect | EffectRef;
-        if ('effectId' in effect && effect.effectId && !('duration' in effect || 'namedEffect' in effect || 'keyframeEffect' in effect || 'customEffect' in effect)) {
-          // It's a reference
+        let resolvedEffect: Effect;
+        if (isEffectReference(effect)) {
           const referencedEffect = configEffects[effect.effectId];
-          if (referencedEffect) {
-            resolvedEffect = { ...referencedEffect, ...effect };
-          } else {
-            resolvedEffect = effect;
-          }
+          resolvedEffect = referencedEffect ? { ...referencedEffect, ...effect } : effect;
         } else {
           resolvedEffect = effect;
         }
 
         // Calculate the total delay for this effect (sequence delay + staggered offset + effect's own delay)
-        const effectDelay = ('delay' in resolvedEffect ? (resolvedEffect as any).delay : 0) || 0;
+        let effectDelay;
+        if('delay' in resolvedEffect) {
+          effectDelay = resolvedEffect.delay ?? 0;
+        } else {
+          effectDelay = 0;
+        }
         const calculatedDelay = delay + offsets[index] + effectDelay;
 
         // Create a new effect with the calculated delay

From 45e76e2e64f636609f3c2bc6d975fc5a3ec2575d Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Sun, 1 Feb 2026 15:10:32 +0200
Subject: [PATCH 09/29] remove unused comments and move logic to utils

---
 packages/motion/src/Sequence.ts | 197 +-------------------------------
 packages/motion/src/index.ts    |   2 +-
 packages/motion/src/utils.ts    |  81 +++++++++++++
 3 files changed, 86 insertions(+), 194 deletions(-)

diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index b42987c2..9fa5e408 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -1,166 +1,7 @@
 import { AnimationGroup } from './AnimationGroup';
-import { jsEasings } from './easings';
 import { SequenceOptions } from './types';
+import { calculateOffsets, resolveEasingFunction } from './utils';
 
-/**
- * Creates a cubic-bezier easing function from control points.
- * Based on WebKit's implementation.
- */
-export function createCubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
-  // Calculate the polynomial coefficients
-  const cx = 3 * x1;
-  const bx = 3 * (x2 - x1) - cx;
-  const ax = 1 - cx - bx;
-
-  const cy = 3 * y1;
-  const by = 3 * (y2 - y1) - cy;
-  const ay = 1 - cy - by;
-
-  // Sample the curve's x value at parameter t
-  const sampleCurveX = (t: number) => ((ax * t + bx) * t + cx) * t;
-
-  // Sample the curve's y value at parameter t
-  const sampleCurveY = (t: number) => ((ay * t + by) * t + cy) * t;
-
-  // Derivative of x with respect to t
-  const sampleCurveDerivativeX = (t: number) => (3 * ax * t + 2 * bx) * t + cx;
-
-  // Given an x value, find the corresponding t using Newton-Raphson
-  const solveCurveX = (x: number): number => {
-    let t = x;
-
-    // Newton-Raphson iteration (usually converges in 4-8 iterations)
-    for (let i = 0; i < 8; i++) {
-      const xError = sampleCurveX(t) - x;
-      if (Math.abs(xError) < 1e-6) {
-        return t;
-      }
-      const dx = sampleCurveDerivativeX(t);
-      if (Math.abs(dx) < 1e-6) {
-        break;
-      }
-      t -= xError / dx;
-    }
-
-    // Fall back to bisection if Newton-Raphson fails
-    let t0 = 0;
-    let t1 = 1;
-    t = x;
-
-    while (t0 < t1) {
-      const xMid = sampleCurveX(t);
-      if (Math.abs(xMid - x) < 1e-6) {
-        return t;
-      }
-      if (x > xMid) {
-        t0 = t;
-      } else {
-        t1 = t;
-      }
-      t = (t1 - t0) / 2 + t0;
-    }
-
-    return t;
-  };
-
-  return (x: number): number => {
-    if (x <= 0) return 0;
-    if (x >= 1) return 1;
-    return sampleCurveY(solveCurveX(x));
-  };
-}
-
-/**
- * Parses a CSS cubic-bezier string and returns an easing function.
- * @example parseCubicBezier("cubic-bezier(0.4, 0, 0.2, 1)") // returns easing function
- */
-export function parseCubicBezier(str: string): ((t: number) => number) | null {
-  const match = str.match(/cubic-bezier\s*\(\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^)]+)\s*\)/i);
-  if (!match) return null;
-
-  const [, x1, y1, x2, y2] = match.map((v, i) => (i === 0 ? v : parseFloat(v)));
-  if ([x1, y1, x2, y2].some((v) => typeof v !== 'number' || isNaN(v as number))) {
-    return null;
-  }
-
-  return createCubicBezier(x1 as number, y1 as number, x2 as number, y2 as number);
-}
-
-/**
- * Resolves an easing value to a function.
- * Supports:
- * - Direct function references
- * - Named easings from @wix/motion library
- * - CSS cubic-bezier strings (e.g., "cubic-bezier(0.4, 0, 0.2, 1)")
- * - Defaults to linear if not found
- */
-function resolveEasingFunction(
-  easing: string | ((t: number) => number) | undefined,
-): (t: number) => number {
-  if (typeof easing === 'function') {
-    return easing;
-  }
-
-  if (typeof easing === 'string') {
-    // Check named easings first
-    if (easing in jsEasings) {
-      return jsEasings[easing as keyof typeof jsEasings];
-    }
-
-    // Try parsing as cubic-bezier
-    const bezierFn = parseCubicBezier(easing);
-    if (bezierFn) {
-      return bezierFn;
-    }
-  }
-
-  // Default to linear
-  return jsEasings.linear;
-}
-
-/**
- * Calculate staggered delay offsets for a sequence of effects.
- *
- * @param count - The number of effects in the sequence
- * @param offset - The base offset in milliseconds (default 100)
- * @param easingFn - The easing function to apply to the offset calculation
- * @returns An array of calculated delay offsets in milliseconds
- *
- * @example
- * // Linear easing with 5 items and 200ms offset
- * calculateOffsets(5, 200, linear) // [0, 200, 400, 600, 800]
- *
- * @example
- * // QuadIn easing with 5 items and 200ms offset
- * calculateOffsets(5, 200, quadIn) // [0, 50, 200, 450, 800]
- */
-export function calculateOffsets(
-  count: number,
-  offset: number,
-  easingFn: (t: number) => number,
-): number[] {
-  if (count <= 1) {
-    return [0];
-  }
-
-  const last = count - 1;
-  return Array.from({ length: count }, (_, i) => (easingFn(i / last) * last * offset) | 0);
-}
-
-/**
- * @class Sequence
- *
- * A class that manages multiple AnimationGroup instances as a coordinated timeline
- * with staggered delays. Extends AnimationGroup to inherit the playback control API.
- *
- * @example
- * const sequence = new Sequence([group1, group2, group3], {
- *   delay: 0,
- *   offset: 100,
- *   offsetEasing: 'quadIn'
- * });
- * sequence.play();
- */
 export class Sequence extends AnimationGroup {
   animationGroups: AnimationGroup[];
   sequenceDelay: number;
@@ -169,8 +10,6 @@ export class Sequence extends AnimationGroup {
   private _calculatedOffsets: number[];
 
   constructor(animationGroups: AnimationGroup[], options?: SequenceOptions) {
-    // Pass an empty array to parent since we manage AnimationGroups, not Animations directly
-    // We'll override the relevant methods to work with AnimationGroups
     const allAnimations = animationGroups.flatMap((group) => group.animations);
     super(allAnimations, options);
 
@@ -178,61 +17,33 @@ export class Sequence extends AnimationGroup {
     this.sequenceDelay = options?.delay ?? 0;
     this.offset = options?.offset ?? 100;
     this.offsetEasing = resolveEasingFunction(options?.offsetEasing);
-
-    // Calculate offsets for each animation group
-    this._calculatedOffsets = calculateOffsets(
-      animationGroups.length,
-      this.offset,
-      this.offsetEasing,
-    );
-
-    // Apply calculated delays to each animation group
+    this._calculatedOffsets = calculateOffsets(animationGroups.length, this.offset, this.offsetEasing);
     this._applyDelays();
   }
 
-  /**
-   * Apply the calculated staggered delays to each animation group's animations.
-   * The delay is added to any existing delay on each animation.
-   */
   private _applyDelays(): void {
     this.animationGroups.forEach((group, index) => {
       const groupDelay = this.sequenceDelay + this._calculatedOffsets[index];
-
       for (const animation of group.animations) {
         const timing = animation.effect?.getTiming();
         if (timing) {
           const existingDelay = (timing.delay as number) || 0;
-          animation.effect?.updateTiming({
-            delay: existingDelay + groupDelay,
-          });
+          animation.effect?.updateTiming({ delay: existingDelay + groupDelay });
         }
       }
     });
   }
 
-  /**
-   * Get the calculated offset for a specific index in the sequence.
-   */
   getOffsetAt(index: number): number {
     return this._calculatedOffsets[index] ?? 0;
   }
 
-  /**
-   * Get all calculated offsets.
-   */
   getOffsets(): number[] {
     return [...this._calculatedOffsets];
   }
 
-  /**
-   * Recalculate offsets. Useful when animation groups are modified.
-   */
   recalculateOffsets(): void {
-    this._calculatedOffsets = calculateOffsets(
-      this.animationGroups.length,
-      this.offset,
-      this.offsetEasing,
-    );
+    this._calculatedOffsets = calculateOffsets(this.animationGroups.length, this.offset, this.offsetEasing);
   }
 
   // Note: play(), pause(), reverse(), cancel(), setPlaybackRate(), onFinish(),
diff --git a/packages/motion/src/index.ts b/packages/motion/src/index.ts
index 203c57fb..26de44a9 100644
--- a/packages/motion/src/index.ts
+++ b/packages/motion/src/index.ts
@@ -4,4 +4,4 @@ export { registerEffects } from './api/registry';
 export * from './utils';
 export * from './easings';
 export { AnimationGroup } from './AnimationGroup';
-export { Sequence, calculateOffsets, createCubicBezier, parseCubicBezier } from './Sequence';
+export { Sequence } from './Sequence';
diff --git a/packages/motion/src/utils.ts b/packages/motion/src/utils.ts
index a974f0a9..e1d25dcc 100644
--- a/packages/motion/src/utils.ts
+++ b/packages/motion/src/utils.ts
@@ -1,4 +1,5 @@
 import { cssEasings, jsEasings } from './easings';
+
 export function getCssUnits(type: 'percentage' | string) {
   return type === 'percentage' ? '%' : type || 'px';
 }
@@ -12,3 +13,83 @@ export function getJsEasing(
 ): ((t: number) => number) | undefined {
   return easing ? jsEasings[easing as keyof typeof jsEasings] : undefined;
 }
+
+export function createCubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
+  const cx = 3 * x1;
+  const bx = 3 * (x2 - x1) - cx;
+  const ax = 1 - cx - bx;
+
+  const cy = 3 * y1;
+  const by = 3 * (y2 - y1) - cy;
+  const ay = 1 - cy - by;
+
+  const sampleCurveX = (t: number) => ((ax * t + bx) * t + cx) * t;
+  const sampleCurveY = (t: number) => ((ay * t + by) * t + cy) * t;
+  const sampleCurveDerivativeX = (t: number) => (3 * ax * t + 2 * bx) * t + cx;
+
+  const solveCurveX = (x: number): number => {
+    let t = x;
+
+    for (let i = 0; i < 8; i++) {
+      const xError = sampleCurveX(t) - x;
+      if (Math.abs(xError) < 1e-6) return t;
+      const dx = sampleCurveDerivativeX(t);
+      if (Math.abs(dx) < 1e-6) break;
+      t -= xError / dx;
+    }
+
+    let t0 = 0;
+    let t1 = 1;
+    t = x;
+
+    while (t0 < t1) {
+      const xMid = sampleCurveX(t);
+      if (Math.abs(xMid - x) < 1e-6) return t;
+      if (x > xMid) t0 = t;
+      else t1 = t;
+      t = (t1 - t0) / 2 + t0;
+    }
+
+    return t;
+  };
+
+  return (x: number): number => {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    return sampleCurveY(solveCurveX(x));
+  };
+}
+
+export function parseCubicBezier(str: string): ((t: number) => number) | null {
+  const match = str.match(/cubic-bezier\s*\(\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^)]+)\s*\)/i);
+  if (!match) return null;
+
+  const [, x1, y1, x2, y2] = match.map((v, i) => (i === 0 ? v : parseFloat(v)));
+  if ([x1, y1, x2, y2].some((v) => typeof v !== 'number' || isNaN(v as number))) return null;
+
+  return createCubicBezier(x1 as number, y1 as number, x2 as number, y2 as number);
+}
+
+export function resolveEasingFunction(
+  easing: string | ((t: number) => number) | undefined,
+): (t: number) => number {
+  if (typeof easing === 'function') return easing;
+
+  if (typeof easing === 'string') {
+    if (easing in jsEasings) return jsEasings[easing as keyof typeof jsEasings];
+    const bezierFn = parseCubicBezier(easing);
+    if (bezierFn) return bezierFn;
+  }
+
+  return jsEasings.linear;
+}
+
+export function calculateOffsets(
+  count: number,
+  offset: number,
+  easingFn: (t: number) => number,
+): number[] {
+  if (count <= 1) return [0];
+  const last = count - 1;
+  return Array.from({ length: count }, (_, i) => (easingFn(i / last) * last * offset) | 0);
+}

From bf183a1032514339a2aeed927c9eaf5d7f888486 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Mon, 2 Feb 2026 11:39:45 +0200
Subject: [PATCH 10/29] update implementation

---
 packages/interact/src/core/Interact.ts      | 67 +++++------------
 packages/interact/src/core/add.ts           | 31 +++++++-
 packages/interact/src/handlers/click.ts     |  8 +++
 packages/interact/src/handlers/hover.ts     |  8 +++
 packages/interact/src/handlers/viewEnter.ts |  8 +++
 packages/interact/src/types.ts              | 48 +------------
 packages/interact/test/mini.spec.ts         |  8 +++
 packages/interact/test/react.spec.tsx       |  8 +++
 packages/interact/test/viewEnter.spec.ts    |  8 +++
 packages/interact/test/web.spec.ts          |  8 +++
 packages/motion/src/api/sequenceRegistry.ts | 79 +++++++++++++++++++++
 packages/motion/src/index.ts                |  2 +
 packages/motion/src/motion.ts               | 25 ++++++-
 packages/motion/test/Sequence.spec.ts       |  3 +-
 14 files changed, 211 insertions(+), 100 deletions(-)
 create mode 100644 packages/motion/src/api/sequenceRegistry.ts

diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index b83e42a8..040025f0 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -14,7 +14,7 @@ import {
 import { getInterpolatedKey } from './utilities';
 import { generateId } from '../utils';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
-import { registerEffects, calculateOffsets, jsEasings, parseCubicBezier } from '@wix/motion';
+import { registerEffects, SequenceRegistry } from '@wix/motion';
 
 function _convertToKeyTemplate(key: string) {
   return key.replace(/\[([-\w]+)]/g, '[]');
@@ -101,6 +101,7 @@ export class Interact {
     this.listInteractionsCache = {};
     this.controllers.clear();
     this.dataCache = { effects: {}, sequences: {}, conditions: {}, interactions: {} };
+    SequenceRegistry.clear();
     Interact.instances.splice(Interact.instances.indexOf(this), 1);
   }
 
@@ -178,6 +179,7 @@ export class Interact {
     });
     Interact.instances.length = 0;
     Interact.controllerCache.clear();
+    SequenceRegistry.clear();
   }
 
   static setup(options: {
@@ -230,36 +232,6 @@ export class Interact {
 
 let interactionIdCounter = 0;
 
-/**
- * Resolves an easing value to a function.
- * Supports:
- * - Direct function references
- * - Named easings from @wix/motion library
- * - CSS cubic-bezier strings (e.g., "cubic-bezier(0.4, 0, 0.2, 1)")
- */
-function resolveEasingFunction(
-  easing: string | ((t: number) => number) | undefined,
-): (t: number) => number {
-  if (typeof easing === 'function') {
-    return easing;
-  }
-
-  if (typeof easing === 'string') {
-    // Check named easings first
-    if (easing in jsEasings) {
-      return jsEasings[easing as keyof typeof jsEasings];
-    }
-
-    // Try parsing as cubic-bezier
-    const bezierFn = parseCubicBezier(easing);
-    if (bezierFn) {
-      return bezierFn;
-    }
-  }
-
-  return jsEasings.linear;
-}
-
 /**
  * Resolves a sequence reference or inline sequence to a full Sequence object.
  */
@@ -288,7 +260,8 @@ function resolveSequence(
 }
 
 /**
- * Expands effects from sequences into the effects array with calculated staggered delays.
+ * Expands effects from sequences into the effects array with sequence metadata.
+ * Delay calculation is handled by the Sequence class in @wix/motion.
  */
 function expandSequenceEffects(
   interaction: Interaction,
@@ -302,11 +275,14 @@ function expandSequenceEffects(
       const sequence = resolveSequence(seqOrRef, configSequences);
       if (!sequence) continue;
 
-      const delay = sequence.delay ?? 0;
-      const offset = sequence.offset ?? 100;
-      const easingFn = resolveEasingFunction(sequence.offsetEasing);
-      const offsets = calculateOffsets(sequence.effects.length, offset, easingFn);
+      // Store sequence options to pass to Sequence class
+      const sequenceOptions = {
+        delay: sequence.delay ?? 0,
+        offset: sequence.offset ?? 100,
+        offsetEasing: sequence.offsetEasing,
+      };
 
+      const totalEffects = sequence.effects.length;
       sequence.effects.forEach((effect, index) => {
         let resolvedEffect: Effect;
         if (isEffectReference(effect)) {
@@ -316,25 +292,16 @@ function expandSequenceEffects(
           resolvedEffect = effect;
         }
 
-        // Calculate the total delay for this effect (sequence delay + staggered offset + effect's own delay)
-        let effectDelay;
-        if('delay' in resolvedEffect) {
-          effectDelay = resolvedEffect.delay ?? 0;
-        } else {
-          effectDelay = 0;
-        }
-        const calculatedDelay = delay + offsets[index] + effectDelay;
-
-        // Create a new effect with the calculated delay
-        const effectWithDelay: Effect | EffectRef = {
+        // Mark effect with sequence metadata (delay calculation deferred to Sequence class)
+        const effectWithMetadata: Effect | EffectRef = {
           ...resolvedEffect,
-          delay: calculatedDelay,
-          // Mark this effect as part of a sequence for potential cleanup tracking
           _sequenceId: sequence.sequenceId,
           _sequenceIndex: index,
+          _sequenceTotal: totalEffects,
+          _sequenceOptions: sequenceOptions,
         } as any;
 
-        expandedEffects.push(effectWithDelay);
+        expandedEffects.push(effectWithMetadata);
       });
     }
   }
diff --git a/packages/interact/src/core/add.ts b/packages/interact/src/core/add.ts
index ec694cc3..695ade6b 100644
--- a/packages/interact/src/core/add.ts
+++ b/packages/interact/src/core/add.ts
@@ -8,11 +8,14 @@ import type {
   InteractionTrigger,
   CreateTransitionCSSParams,
   IInteractionController,
+  TimeEffect,
 } from '../types';
 import { createTransitionCSS, getMediaQuery, getSelectorCondition } from '../utils';
 import { getInterpolatedKey } from './utilities';
 import { Interact, getSelector } from './Interact';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
+import { SequenceRegistry } from '@wix/motion';
+import { effectToAnimationOptions } from '../handlers/utilities';
 
 type InteractionsToApply = Array<
   [
@@ -234,7 +237,33 @@ function _addInteraction(
   });
 
   // apply the effects in reverse to return to the order specified by the user to ensure order of composition is as defined
-  interactionsToApply.reverse().forEach((interaction) => {
+  interactionsToApply.reverse();
+
+  // First pass: Register all sequence effects before calling handlers
+  // This ensures the full Sequence can be created when handlers request it
+  interactionsToApply.forEach(([, , effect, , targetElements]) => {
+    const sequenceEffect = effect as Effect & {
+      _sequenceId?: string;
+      _sequenceIndex?: number;
+      _sequenceTotal?: number;
+      _sequenceOptions?: { delay?: number; offset?: number; offsetEasing?: string | ((t: number) => number) };
+    };
+    if (sequenceEffect._sequenceId && 'duration' in effect) {
+      const targets = Array.isArray(targetElements) ? targetElements : [targetElements];
+      targets.forEach((target) => {
+        SequenceRegistry.registerEffect(sequenceEffect._sequenceId!, {
+          target,
+          effectOptions: effectToAnimationOptions(effect as TimeEffect),
+          sequenceOptions: sequenceEffect._sequenceOptions || {},
+          index: sequenceEffect._sequenceIndex ?? 0,
+          total: sequenceEffect._sequenceTotal ?? 1,
+        });
+      });
+    }
+  });
+
+  // Second pass: Apply all interactions (handlers will now get fully-created Sequences)
+  interactionsToApply.forEach((interaction) => {
     _applyInteraction(...interaction);
   });
 }
diff --git a/packages/interact/src/handlers/click.ts b/packages/interact/src/handlers/click.ts
index adc73923..997aef90 100644
--- a/packages/interact/src/handlers/click.ts
+++ b/packages/interact/src/handlers/click.ts
@@ -25,6 +25,14 @@ function createTimeEffectHandler(
   reducedMotion: boolean = false,
   selectorCondition?: string,
 ) {
+  // For sequence effects, only the first effect (index 0) controls playback
+  const sequenceIndex = (effect as any)._sequenceIndex;
+  const isSequenceEffect = sequenceIndex !== undefined;
+  if (isSequenceEffect && sequenceIndex !== 0) {
+    // Non-leader sequence effects don't need handlers - the leader controls the Sequence
+    return () => {};
+  }
+
   const animation = getAnimation(
     element,
     effectToAnimationOptions(effect),
diff --git a/packages/interact/src/handlers/hover.ts b/packages/interact/src/handlers/hover.ts
index e7c59a2c..b9e9a997 100644
--- a/packages/interact/src/handlers/hover.ts
+++ b/packages/interact/src/handlers/hover.ts
@@ -25,6 +25,14 @@ function createTimeEffectHandler(
   reducedMotion: boolean = false,
   selectorCondition?: string,
 ) {
+  // For sequence effects, only the first effect (index 0) controls playback
+  const sequenceIndex = (effect as any)._sequenceIndex;
+  const isSequenceEffect = sequenceIndex !== undefined;
+  if (isSequenceEffect && sequenceIndex !== 0) {
+    // Non-leader sequence effects don't need handlers - the leader controls the Sequence
+    return () => {};
+  }
+
   const animation = getAnimation(
     element,
     effectToAnimationOptions(effect),
diff --git a/packages/interact/src/handlers/viewEnter.ts b/packages/interact/src/handlers/viewEnter.ts
index d59ff193..d946bb6b 100644
--- a/packages/interact/src/handlers/viewEnter.ts
+++ b/packages/interact/src/handlers/viewEnter.ts
@@ -139,6 +139,14 @@ function addViewEnterHandler(
   options: ViewEnterParams = {},
   { reducedMotion, selectorCondition }: InteractOptions = {},
 ) {
+  // For sequence effects, only the first effect (index 0) controls playback
+  const sequenceIndex = (effect as any)._sequenceIndex;
+  const isSequenceEffect = sequenceIndex !== undefined;
+  if (isSequenceEffect && sequenceIndex !== 0) {
+    // Non-leader sequence effects don't need handlers - the leader controls the Sequence
+    return;
+  }
+
   const mergedOptions = { ...viewEnterOptions, ...options };
   const type = mergedOptions.type || 'once';
   const animation = getAnimation(
diff --git a/packages/interact/src/types.ts b/packages/interact/src/types.ts
index 445aee35..0dad3f37 100644
--- a/packages/interact/src/types.ts
+++ b/packages/interact/src/types.ts
@@ -147,53 +147,18 @@ export type EffectRef = EffectBase & { effectId: string };
 
 export type Effect = EffectBase & (TimeEffect | ScrubEffect | TransitionEffect);
 
-/**
- * A Sequence is a group of Effects managed as a coordinated timeline with staggered delays.
- */
 export type Sequence = {
-  /**
-   * Unique identifier for referencing this sequence from Interaction.sequences
-   */
   sequenceId: string;
-  /**
-   * Fixed delay in milliseconds before the entire sequence starts.
-   * @default 0
-   */
   delay?: number;
-  /**
-   * Base offset in milliseconds between each effect in the sequence.
-   * @default 100
-   */
   offset?: number;
-  /**
-   * Easing function to apply to offset calculation.
-   * Can be a JS function, a named easing from @wix/motion, or a CSS easing value.
-   * @default 'linear'
-   */
   offsetEasing?: string | ((t: number) => number);
-  /**
-   * The effects that belong to this sequence.
-   * Effects will be applied in order with calculated staggered delays.
-   */
   effects: (Effect | EffectRef)[];
 };
 
-/**
- * Reference to a reusable Sequence defined in InteractConfig.sequences
- */
 export type SequenceRef = {
   sequenceId: string;
-  /**
-   * Override the delay defined in the referenced sequence
-   */
   delay?: number;
-  /**
-   * Override the offset defined in the referenced sequence
-   */
-  offset?: number;
-  /**
-   * Override the offsetEasing defined in the referenced sequence
-   */
+  offset?: number
   offsetEasing?: string | ((t: number) => number);
 };
 
@@ -213,23 +178,12 @@ export type InteractionTrigger = {
 };
 
 export type Interaction = InteractionTrigger & {
-  /**
-   * Direct effects to apply for this interaction.
-   * Can be omitted if only using sequences.
-   */
   effects?: ((Effect | EffectRef) & { interactionId?: string })[];
-  /**
-   * Sequences of effects to apply for this interaction.
-   * Each sequence groups effects with staggered delays.
-   */
   sequences?: (Sequence | SequenceRef)[];
 };
 
 export type InteractConfig = {
   effects: Record<string, Effect>;
-  /**
-   * Reusable Sequence declarations that can be referenced by Interaction.sequences
-   */
   sequences?: Record<string, Sequence>;
   conditions?: Record<string, Condition>;
   interactions: Interaction[];
diff --git a/packages/interact/test/mini.spec.ts b/packages/interact/test/mini.spec.ts
index 2f9b4ff4..f1d7587b 100644
--- a/packages/interact/test/mini.spec.ts
+++ b/packages/interact/test/mini.spec.ts
@@ -30,6 +30,14 @@ vi.mock('@wix/motion', () => {
       });
     }),
     registerEffects: vi.fn(),
+    SequenceRegistry: {
+      configs: new Map(),
+      sequences: new Map(),
+      registerEffect: vi.fn(),
+      getOrCreateSequence: vi.fn(),
+      clear: vi.fn(),
+      clearSequence: vi.fn(),
+    },
   };
 
   return mock;
diff --git a/packages/interact/test/react.spec.tsx b/packages/interact/test/react.spec.tsx
index b45283d5..f995b037 100644
--- a/packages/interact/test/react.spec.tsx
+++ b/packages/interact/test/react.spec.tsx
@@ -29,6 +29,14 @@ vi.mock('@wix/motion', () => {
       });
     }),
     registerEffects: vi.fn(),
+    SequenceRegistry: {
+      configs: new Map(),
+      sequences: new Map(),
+      registerEffect: vi.fn(),
+      getOrCreateSequence: vi.fn(),
+      clear: vi.fn(),
+      clearSequence: vi.fn(),
+    },
   };
 
   return mock;
diff --git a/packages/interact/test/viewEnter.spec.ts b/packages/interact/test/viewEnter.spec.ts
index 388a95a3..d896a9d9 100644
--- a/packages/interact/test/viewEnter.spec.ts
+++ b/packages/interact/test/viewEnter.spec.ts
@@ -14,6 +14,14 @@ vi.mock('@wix/motion', () => ({
     ready: Promise.resolve(),
   }),
   registerEffects: vi.fn(),
+  SequenceRegistry: {
+    configs: new Map(),
+    sequences: new Map(),
+    registerEffect: vi.fn(),
+    getOrCreateSequence: vi.fn(),
+    clear: vi.fn(),
+    clearSequence: vi.fn(),
+  },
 }));
 
 vi.mock('fastdom', () => ({
diff --git a/packages/interact/test/web.spec.ts b/packages/interact/test/web.spec.ts
index 12b690aa..a0b5bf4a 100644
--- a/packages/interact/test/web.spec.ts
+++ b/packages/interact/test/web.spec.ts
@@ -30,6 +30,14 @@ vi.mock('@wix/motion', () => {
       });
     }),
     registerEffects: vi.fn(),
+    SequenceRegistry: {
+      configs: new Map(),
+      sequences: new Map(),
+      registerEffect: vi.fn(),
+      getOrCreateSequence: vi.fn(),
+      clear: vi.fn(),
+      clearSequence: vi.fn(),
+    },
   };
 
   return mock;
diff --git a/packages/motion/src/api/sequenceRegistry.ts b/packages/motion/src/api/sequenceRegistry.ts
new file mode 100644
index 00000000..651422ae
--- /dev/null
+++ b/packages/motion/src/api/sequenceRegistry.ts
@@ -0,0 +1,79 @@
+import type { AnimationGroup } from '../AnimationGroup';
+import type { SequenceOptions } from '../types';
+import { Sequence } from '../Sequence';
+
+export type SequenceEffectConfig = {
+  target: HTMLElement;
+  effectOptions: Record<string, unknown>;
+  sequenceOptions: SequenceOptions;
+  index: number;
+  total: number;
+};
+
+type GetAnimationFn = (
+  target: HTMLElement,
+  options: Record<string, unknown>,
+  trigger?: undefined,
+  reducedMotion?: boolean,
+) => AnimationGroup | null;
+
+let getAnimationFn: GetAnimationFn | null = null;
+
+export const SequenceRegistry = {
+  configs: new Map<string, SequenceEffectConfig[]>(),
+  sequences: new Map<string, Sequence>(),
+
+  setGetAnimationFn(fn: GetAnimationFn) {
+    getAnimationFn = fn;
+  },
+
+  registerEffect(sequenceId: string, config: SequenceEffectConfig) {
+    const list = this.configs.get(sequenceId) || [];
+    list.push(config);
+    this.configs.set(sequenceId, list);
+  },
+
+  getOrCreateSequence(sequenceId: string, reducedMotion?: boolean): Sequence | null {
+    if (this.sequences.has(sequenceId)) {
+      return this.sequences.get(sequenceId)!;
+    }
+
+    const configs = this.configs.get(sequenceId);
+    if (!configs?.length || !getAnimationFn) return null;
+
+    // Check if all effects have been registered
+    const expectedTotal = configs[0].total;
+    if (configs.length < expectedTotal) {
+      return null; // Not all effects registered yet
+    }
+
+    // Sort by index to ensure correct order
+    configs.sort((a, b) => a.index - b.index);
+
+    // Create all AnimationGroups
+    const groups: AnimationGroup[] = [];
+    for (const cfg of configs) {
+      const animation = getAnimationFn(cfg.target, cfg.effectOptions, undefined, reducedMotion);
+      if (animation) {
+        groups.push(animation);
+      }
+    }
+
+    if (!groups.length) return null;
+
+    // Create Sequence (applies delays internally)
+    const sequence = new Sequence(groups, configs[0].sequenceOptions);
+    this.sequences.set(sequenceId, sequence);
+    return sequence;
+  },
+
+  clear() {
+    this.configs.clear();
+    this.sequences.clear();
+  },
+
+  clearSequence(sequenceId: string) {
+    this.configs.delete(sequenceId);
+    this.sequences.delete(sequenceId);
+  },
+};
diff --git a/packages/motion/src/index.ts b/packages/motion/src/index.ts
index 26de44a9..febe9b3c 100644
--- a/packages/motion/src/index.ts
+++ b/packages/motion/src/index.ts
@@ -1,6 +1,8 @@
 export * from './motion';
 export * from './types';
 export { registerEffects } from './api/registry';
+export { SequenceRegistry } from './api/sequenceRegistry';
+export type { SequenceEffectConfig } from './api/sequenceRegistry';
 export * from './utils';
 export * from './easings';
 export { AnimationGroup } from './AnimationGroup';
diff --git a/packages/motion/src/motion.ts b/packages/motion/src/motion.ts
index be14ef08..2e0fa1fb 100644
--- a/packages/motion/src/motion.ts
+++ b/packages/motion/src/motion.ts
@@ -192,7 +192,10 @@ function getScrubScene(
   } as ScrubPointerScene;
 }
 
-function getAnimation(
+import { SequenceRegistry } from './api/sequenceRegistry';
+
+// Internal function for creating individual animations (used by registry)
+function _createAnimation(
   target: HTMLElement | string | null,
   animationOptions: AnimationOptions,
   trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
@@ -211,6 +214,26 @@ function getAnimation(
   return getWebAnimation(target, animationOptions, trigger, { reducedMotion });
 }
 
+// Set up registry with animation creation function
+SequenceRegistry.setGetAnimationFn((target, options, trigger, reducedMotion) => {
+  return _createAnimation(target, options as AnimationOptions, trigger, reducedMotion) as AnimationGroup | null;
+});
+
+function getAnimation(
+  target: HTMLElement | string | null,
+  animationOptions: AnimationOptions,
+  trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
+  reducedMotion: boolean = false,
+): AnimationGroup | MouseAnimationInstance | null {
+  // Check if this is a sequence effect
+  const sequenceId = (animationOptions as AnimationOptions & { _sequenceId?: string })._sequenceId;
+  if (sequenceId) {
+    return SequenceRegistry.getOrCreateSequence(sequenceId, reducedMotion);
+  }
+
+  return _createAnimation(target, animationOptions, trigger, reducedMotion);
+}
+
 export {
   getCSSAnimation,
   getWebAnimation,
diff --git a/packages/motion/test/Sequence.spec.ts b/packages/motion/test/Sequence.spec.ts
index cc9efbad..c48f4247 100644
--- a/packages/motion/test/Sequence.spec.ts
+++ b/packages/motion/test/Sequence.spec.ts
@@ -1,5 +1,6 @@
 import { describe, expect, test, vi, beforeEach, beforeAll } from 'vitest';
-import { Sequence, calculateOffsets, parseCubicBezier, createCubicBezier } from '../src/Sequence';
+import { Sequence } from '../src/Sequence';
+import { calculateOffsets, parseCubicBezier, createCubicBezier } from '../src/utils';
 import { AnimationGroup } from '../src/AnimationGroup';
 import { linear, quadIn, sineOut, cubicIn, expoIn, quadOut, cubicOut } from '../src/easings';
 

From 754e2f6bb1169ea0a0e601fcd9299463937fdf81 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Mon, 2 Feb 2026 15:36:46 +0200
Subject: [PATCH 11/29] refactor addDelays

---
 packages/motion/src/AnimationGroup.ts | 10 ++++++++++
 packages/motion/src/Sequence.ts       | 12 +++---------
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/packages/motion/src/AnimationGroup.ts b/packages/motion/src/AnimationGroup.ts
index eb2750e0..2eef6f79 100644
--- a/packages/motion/src/AnimationGroup.ts
+++ b/packages/motion/src/AnimationGroup.ts
@@ -22,6 +22,16 @@ export class AnimationGroup {
     this.isCSS = animations[0] instanceof CSSAnimation;
   }
 
+  applyGroupDelay(delay: number) {
+    for (const animation of this.animations) {
+      const timing = animation.effect?.getTiming();
+      if (timing) {
+        const existingDelay = (timing.delay as number) || 0;
+        animation.effect?.updateTiming({ delay: existingDelay + delay });
+      }
+    }
+  }
+
   getProgress() {
     return this.animations[0]?.effect?.getComputedTiming().progress || 0;
   }
diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index 9fa5e408..119d9950 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -24,15 +24,9 @@ export class Sequence extends AnimationGroup {
   private _applyDelays(): void {
     this.animationGroups.forEach((group, index) => {
       const groupDelay = this.sequenceDelay + this._calculatedOffsets[index];
-      for (const animation of group.animations) {
-        const timing = animation.effect?.getTiming();
-        if (timing) {
-          const existingDelay = (timing.delay as number) || 0;
-          animation.effect?.updateTiming({ delay: existingDelay + groupDelay });
-        }
-      }
-    });
-  }
+      group.applyGroupDelay(groupDelay);
+  })
+}
 
   getOffsetAt(index: number): number {
     return this._calculatedOffsets[index] ?? 0;

From 836efec1fb58cd910220771f361ac4e3d58d1203 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Mon, 2 Feb 2026 15:46:44 +0200
Subject: [PATCH 12/29] add support for linear easing function

---
 apps/demo/src/web/components/SequenceDemo.tsx |  4 +-
 packages/motion/src/utils.ts                  | 66 +++++++++++++++++++
 packages/motion/test/Sequence.spec.ts         | 60 ++++++++++++++++-
 3 files changed, 128 insertions(+), 2 deletions(-)

diff --git a/apps/demo/src/web/components/SequenceDemo.tsx b/apps/demo/src/web/components/SequenceDemo.tsx
index 68f86b4b..be756e20 100644
--- a/apps/demo/src/web/components/SequenceDemo.tsx
+++ b/apps/demo/src/web/components/SequenceDemo.tsx
@@ -118,6 +118,8 @@ const easingPresets = [
   { name: 'ease-in', value: 'cubic-bezier(0.4, 0, 1, 1)', description: 'CSS cubic-bezier' },
   { name: 'overshoot', value: 'cubic-bezier(0.34, 1.56, 0.64, 1)', description: 'CSS cubic-bezier (y > 1)' },
   { name: 'back-in', value: 'cubic-bezier(0.6, -0.28, 0.735, 0.045)', description: 'CSS cubic-bezier (y < 0)' },
+  { name: 'linear ramp', value: 'linear(0, 0.5, 1)', description: 'CSS linear()' },
+  { name: 'fast-then-slow', value: 'linear(0, 0.3 50%, 1)', description: 'CSS linear()' },
 ];
 
 const sequenceItems = [
@@ -171,7 +173,7 @@ export const SequenceDemo = () => {
         <h3>Staggered Animations</h3>
         <p className="sequence-demo-description">
           Use <code>offsetEasing</code> to control stagger timing. Supports named easings, 
-          CSS <code>cubic-bezier()</code> strings, and custom functions.
+          CSS <code>cubic-bezier()</code>, CSS <code>linear()</code>, and custom functions.
         </p>
       </div>
 
diff --git a/packages/motion/src/utils.ts b/packages/motion/src/utils.ts
index e1d25dcc..71e327e7 100644
--- a/packages/motion/src/utils.ts
+++ b/packages/motion/src/utils.ts
@@ -70,6 +70,70 @@ export function parseCubicBezier(str: string): ((t: number) => number) | null {
   return createCubicBezier(x1 as number, y1 as number, x2 as number, y2 as number);
 }
 
+type LinearStop = { value: number; position: number };
+
+export function createLinear(stops: LinearStop[]): (t: number) => number {
+  if (stops.length === 0) return () => 0;
+  if (stops.length === 1) return () => stops[0].value;
+
+  // Sort stops by position
+  const sorted = [...stops].sort((a, b) => a.position - b.position);
+
+  return (t: number): number => {
+    if (t <= 0) return sorted[0].value;
+    if (t >= 1) return sorted[sorted.length - 1].value;
+
+    // Find the two stops to interpolate between
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const current = sorted[i];
+      const next = sorted[i + 1];
+
+      if (t >= current.position && t <= next.position) {
+        const range = next.position - current.position;
+        if (range === 0) return current.value;
+        const localT = (t - current.position) / range;
+        return current.value + (next.value - current.value) * localT;
+      }
+    }
+
+    return sorted[sorted.length - 1].value;
+  };
+}
+
+export function parseLinear(str: string): ((t: number) => number) | null {
+  const match = str.match(/^linear\s*\(\s*(.+)\s*\)$/i);
+  if (!match) return null;
+
+  const content = match[1];
+  const parts = content.split(',').map((s) => s.trim());
+  if (parts.length < 2) return null;
+
+  const stops: LinearStop[] = [];
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i].trim();
+    // Match value with optional percentage: "0.5" or "0.5 75%"
+    const valueMatch = part.match(/^(-?[\d.]+)(?:\s+(-?[\d.]+)%)?$/);
+    if (!valueMatch) return null;
+
+    const value = parseFloat(valueMatch[1]);
+    if (isNaN(value)) return null;
+
+    let position: number;
+    if (valueMatch[2] !== undefined) {
+      // Explicit percentage provided
+      position = parseFloat(valueMatch[2]) / 100;
+    } else {
+      // Auto-distribute: first is 0%, last is 100%, others evenly spaced
+      position = i / (parts.length - 1);
+    }
+
+    stops.push({ value, position });
+  }
+
+  return createLinear(stops);
+}
+
 export function resolveEasingFunction(
   easing: string | ((t: number) => number) | undefined,
 ): (t: number) => number {
@@ -79,6 +143,8 @@ export function resolveEasingFunction(
     if (easing in jsEasings) return jsEasings[easing as keyof typeof jsEasings];
     const bezierFn = parseCubicBezier(easing);
     if (bezierFn) return bezierFn;
+    const linearFn = parseLinear(easing);
+    if (linearFn) return linearFn;
   }
 
   return jsEasings.linear;
diff --git a/packages/motion/test/Sequence.spec.ts b/packages/motion/test/Sequence.spec.ts
index c48f4247..38114cdc 100644
--- a/packages/motion/test/Sequence.spec.ts
+++ b/packages/motion/test/Sequence.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test, vi, beforeEach, beforeAll } from 'vitest';
 import { Sequence } from '../src/Sequence';
-import { calculateOffsets, parseCubicBezier, createCubicBezier } from '../src/utils';
+import { calculateOffsets, parseCubicBezier, createCubicBezier, parseLinear, createLinear } from '../src/utils';
 import { AnimationGroup } from '../src/AnimationGroup';
 import { linear, quadIn, sineOut, cubicIn, expoIn, quadOut, cubicOut } from '../src/easings';
 
@@ -500,6 +500,64 @@ describe('Sequence', () => {
     });
   });
 
+  describe('parseLinear()', () => {
+    test('should parse simple linear(0, 1) with auto-distributed stops', () => {
+      const fn = parseLinear('linear(0, 1)');
+      expect(fn).not.toBeNull();
+
+      expect(fn!(0)).toBe(0);
+      expect(fn!(0.5)).toBe(0.5);
+      expect(fn!(1)).toBe(1);
+    });
+
+    test('should parse linear with explicit percentage stops', () => {
+      const fn = parseLinear('linear(0, 0.75 25%, 1)');
+      expect(fn).not.toBeNull();
+
+      expect(fn!(0)).toBe(0);
+      expect(fn!(0.25)).toBe(0.75); // explicit 75% at 25% progress
+      expect(fn!(1)).toBe(1);
+      // Between 25% and 100%: interpolate from 0.75 to 1
+      expect(fn!(0.625)).toBeCloseTo(0.875, 5); // midpoint between 0.25 and 1
+    });
+
+    test('should return null for invalid input', () => {
+      expect(parseLinear('not-linear')).toBeNull();
+      expect(parseLinear('linear()')).toBeNull();
+      expect(parseLinear('linear(0)')).toBeNull(); // needs at least 2 stops
+      expect(parseLinear('cubic-bezier(0, 0, 1, 1)')).toBeNull();
+    });
+  });
+
+  describe('createLinear()', () => {
+    test('should create step-like easing with multiple stops', () => {
+      // Create a "stairs" effect: 0 until 50%, then jump to 1
+      const fn = createLinear([
+        { value: 0, position: 0 },
+        { value: 0, position: 0.5 },
+        { value: 1, position: 0.5 },
+        { value: 1, position: 1 },
+      ]);
+
+      expect(fn(0)).toBe(0);
+      expect(fn(0.25)).toBe(0);
+      expect(fn(0.5)).toBe(0); // at exact boundary, returns first matching stop
+      expect(fn(0.75)).toBe(1);
+      expect(fn(1)).toBe(1);
+    });
+
+    test('should handle boundary values correctly', () => {
+      const fn = createLinear([
+        { value: 0.2, position: 0 },
+        { value: 0.8, position: 1 },
+      ]);
+
+      expect(fn(-0.5)).toBe(0.2); // clamp below returns first stop value
+      expect(fn(1.5)).toBe(0.8); // clamp above returns last stop value
+      expect(fn(0.5)).toBeCloseTo(0.5, 5); // midpoint
+    });
+  });
+
   describe('Sequence easing resolution', () => {
     let mockAnimationGroups: AnimationGroup[];
 

From cc08dc0d0f785aca35f347eae2aa38e60619aa45 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Mon, 2 Feb 2026 22:15:55 +0200
Subject: [PATCH 13/29] support reverse for sequences

---
 apps/demo/src/web/components/SequenceDemo.tsx |  4 ++--
 packages/motion/src/AnimationGroup.ts         |  4 ++--
 packages/motion/src/Sequence.ts               | 15 +++++++++++----
 3 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/apps/demo/src/web/components/SequenceDemo.tsx b/apps/demo/src/web/components/SequenceDemo.tsx
index be756e20..484bd44c 100644
--- a/apps/demo/src/web/components/SequenceDemo.tsx
+++ b/apps/demo/src/web/components/SequenceDemo.tsx
@@ -102,8 +102,8 @@ const createConfig = (offsetEasing: string): InteractConfig => ({
   interactions: [
     {
       key: 'sequence-trigger',
-      trigger: 'viewEnter',
-      params: { type: 'repeat', threshold: 0.5 },
+      trigger: 'click',
+      params: { type: 'alternate', threshold: 0.5 },
       sequences: [{ sequenceId: 'entrance-sequence' }],
     },
   ],
diff --git a/packages/motion/src/AnimationGroup.ts b/packages/motion/src/AnimationGroup.ts
index 2eef6f79..0228ba36 100644
--- a/packages/motion/src/AnimationGroup.ts
+++ b/packages/motion/src/AnimationGroup.ts
@@ -22,12 +22,12 @@ export class AnimationGroup {
     this.isCSS = animations[0] instanceof CSSAnimation;
   }
 
-  applyGroupDelay(delay: number) {
+  applyGroupDelay(delay: number, endDelay?: number) {
     for (const animation of this.animations) {
       const timing = animation.effect?.getTiming();
       if (timing) {
         const existingDelay = (timing.delay as number) || 0;
-        animation.effect?.updateTiming({ delay: existingDelay + delay });
+        animation.effect?.updateTiming({ delay: existingDelay + delay, endDelay});
       }
     }
   }
diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index 119d9950..3ed8e8bc 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -22,11 +22,18 @@ export class Sequence extends AnimationGroup {
   }
 
   private _applyDelays(): void {
+    const minOffset = Math.min(...this._calculatedOffsets);
+    const maxOffset = Math.max(...this._calculatedOffsets);
+    const totalSpan = maxOffset - minOffset;
+  
     this.animationGroups.forEach((group, index) => {
-      const groupDelay = this.sequenceDelay + this._calculatedOffsets[index];
-      group.applyGroupDelay(groupDelay);
-  })
-}
+      // Normalize offset to be non-negative
+      const normalizedOffset = this._calculatedOffsets[index] - minOffset;
+      const groupDelay = this.sequenceDelay + normalizedOffset;
+      const endDelay = totalSpan - normalizedOffset;
+      group.applyGroupDelay(groupDelay, endDelay);
+    });
+  }
 
   getOffsetAt(index: number): number {
     return this._calculatedOffsets[index] ?? 0;

From 5a73cbf57874debbf9fe3a3ff6f13dc475de0380 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Mon, 2 Feb 2026 22:27:35 +0200
Subject: [PATCH 14/29] normalize offsets only if minOffset is negative

---
 packages/motion/src/Sequence.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index 3ed8e8bc..5fef7713 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -28,7 +28,7 @@ export class Sequence extends AnimationGroup {
   
     this.animationGroups.forEach((group, index) => {
       // Normalize offset to be non-negative
-      const normalizedOffset = this._calculatedOffsets[index] - minOffset;
+      const normalizedOffset = minOffset < 0 ? this._calculatedOffsets[index] - minOffset : this._calculatedOffsets[index];
       const groupDelay = this.sequenceDelay + normalizedOffset;
       const endDelay = totalSpan - normalizedOffset;
       group.applyGroupDelay(groupDelay, endDelay);

From bf2d8150df902dec909a697a17719b99b40bc8b7 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Mon, 2 Feb 2026 22:49:37 +0200
Subject: [PATCH 15/29] clear cache if sequence is re-registered

---
 packages/motion/src/api/sequenceRegistry.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/motion/src/api/sequenceRegistry.ts b/packages/motion/src/api/sequenceRegistry.ts
index 651422ae..b08fb6fc 100644
--- a/packages/motion/src/api/sequenceRegistry.ts
+++ b/packages/motion/src/api/sequenceRegistry.ts
@@ -28,6 +28,12 @@ export const SequenceRegistry = {
   },
 
   registerEffect(sequenceId: string, config: SequenceEffectConfig) {
+    // Clear cached sequence if re-registering (replay scenario)
+    if (this.sequences.has(sequenceId)) {
+      this.sequences.delete(sequenceId);
+      this.configs.delete(sequenceId);
+    }
+
     const list = this.configs.get(sequenceId) || [];
     list.push(config);
     this.configs.set(sequenceId, list);

From 1d393c8ad9752e57763ac7ff9eb5abd6cf77c348 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Tue, 3 Feb 2026 10:21:09 +0200
Subject: [PATCH 16/29] readd deleted specs

---
 packages/interact/dev/DOCS_PLAN.md       | 463 +++++++++++++++++++++++
 packages/interact/dev/LIST_PLAN.md       | 212 +++++++++++
 packages/interact/dev/RULES_PLAN.md      | 288 ++++++++++++++
 packages/interact/dev/VIEW_ENTER_SPEC.md |  28 ++
 4 files changed, 991 insertions(+)
 create mode 100644 packages/interact/dev/DOCS_PLAN.md
 create mode 100644 packages/interact/dev/LIST_PLAN.md
 create mode 100644 packages/interact/dev/RULES_PLAN.md
 create mode 100644 packages/interact/dev/VIEW_ENTER_SPEC.md

diff --git a/packages/interact/dev/DOCS_PLAN.md b/packages/interact/dev/DOCS_PLAN.md
new file mode 100644
index 00000000..ae3b5eb2
--- /dev/null
+++ b/packages/interact/dev/DOCS_PLAN.md
@@ -0,0 +1,463 @@
+## Context Summary
+
+**Key Files, Functions, Types & Structures Involved:**
+
+1. **Main API Files:**
+   - `src/index.ts` - Public exports: `Interact` class, `add()`, `remove()` functions, and all types
+   - `src/interact.ts` - Core `Interact` class with static methods and instance management
+   - `src/types.ts` - Comprehensive type definitions (238 lines) including triggers, effects, configurations
+
+2. **Core Components:**
+   - `src/InteractElement.ts` - Custom element implementation with state management
+   - `src/utils.ts` - Utility functions for ID generation, CSS transition creation, media queries
+   - `src/handlers/` - Directory with 7 trigger handlers: `click`, `hover`, `viewEnter`, `viewProgress`, `pointerMove`, `animationEnd`, and `utilities`
+
+3. **Key Types & Interfaces:**
+   - `InteractConfig` - Main configuration object structure
+   - `Interaction` - Defines source, trigger, effects relationship
+   - `Effect` types - `TimeEffect`, `ScrubEffect`, `TransitionEffect`
+   - `TriggerType` - Union of supported triggers: 'hover', 'click', 'viewEnter', 'pageVisible', 'animationEnd', 'viewProgress', 'pointerMove'
+
+**Current Data Flow & Observed Patterns:**
+
+1. **Configuration-driven Architecture:** Users provide `InteractConfig` with effects, conditions, and interactions
+2. **Custom Element Integration:** Uses `<interact-element>` with `data-interact-key` attributes
+3. **Event Management:** Trigger handlers register/remove DOM event listeners
+4. **State Management:** Effects applied via CSS custom states or data attributes
+5. **Dependency on @wix/motion:** Integrates with Wix's motion library for animations
+6. **Dynamic List Management:** Built-in mutation observers for tracking list item additions/removals
+7. **Element Selection Priority:** Sophisticated selector system with `listContainer`, `selector`, and fallback to first child
+8. **Effect Cascading:** Condition-based effect layering similar to CSS cascade
+
+**Reference Implementations/Utilities Found:**
+
+- `packages/interact-playground/` - Comprehensive examples showing real usage patterns
+- Integration with `@wix/motion` for animation effects
+- Test suite (`__tests__/interact.spec.ts`) with 1194 lines of test cases showing API usage
+- Minimal existing documentation (current README is 9 lines with basic Yoshi links)
+
+**Potential Challenges, Risks & Considerations:**
+
+1. **Complex API Surface:** The package exports extensive types and configuration options
+2. **Browser Compatibility:** Uses modern APIs like `ElementInternals` with legacy fallbacks
+3. **Integration Complexity:** Requires understanding of custom elements, CSS states, and motion library
+4. **Configuration Structure:** Multi-level nested configuration can be overwhelming for new users
+5. **Missing Documentation:** Currently minimal documentation for a feature-rich package
+
+---
+
+## Phase 2: Documentation Plan for @wix/interact Package
+
+Based on my comprehensive analysis, I'll create a detailed plan for writing comprehensive documentation for the `@interact` package.
+
+### **Stage 1: Foundation Documentation Structure**
+
+**What:** Create the core documentation framework and main README
+**Where:**
+
+- Update `packages/interact/README.md`
+- Create `packages/interact/docs/` directory structure
+  **Why:** Establish clear information architecture and entry points for different user types
+
+**Deliverables:**
+
+- Enhanced main README with quick start, installation, and overview
+- Documentation directory structure following monorepo patterns
+- Table of contents and navigation structure
+
+### **Stage 2: API Reference Documentation**
+
+**What:** Comprehensive API documentation for all public interfaces
+**Where:** `packages/interact/docs/api/` directory
+**Why:** Developers need detailed reference documentation for all classes, methods, and types
+
+**Deliverables:**
+
+- `Interact` class documentation (static methods, instance methods, properties)
+  - Document `Interact.forceReducedMotion` static property
+- Function documentation (`add()`, `remove()`)
+  - Add `addListItems(root, key, listContainer, elements)` documentation
+  - Add `removeListItems(elements)` documentation
+- Complete type definitions with examples
+- Configuration object schemas and validation rules
+- Custom element API (`<interact-element>`)
+  - Document `watchChildList(listContainer)` method
+- Element selection priority documentation
+  - `listContainer` + `selector` combinations
+  - Resolution order and fallback behavior
+
+### **Stage 3: Concept Guides**
+
+**What:** Educational content explaining core concepts and architecture
+**Where:** `packages/interact/docs/guides/` directory
+**Why:** Users need to understand the mental model and design philosophy
+
+**Deliverables:**
+
+- "Getting Started" tutorial with first interaction ✅ (complete)
+- "Understanding Triggers" - all 7 trigger types with examples (expand/complete)
+- "Effects and Animations" - integration with @wix/motion ✅ (complete)
+- "Configuration Structure" - nested config organization ✅ (complete)
+- "Custom Elements" - how interact-element works ✅ (complete)
+- "State Management" - CSS states vs data attributes (complete/expand)
+- "Conditions and Media Queries" - responsive interactions ✅ (complete)
+- **NEW: "Lists and Dynamic Content"** - Working with dynamic lists (HIGH PRIORITY)
+  - When to use `listContainer` vs multiple elements
+  - How mutation observers track list changes automatically
+  - Staggered animations for list items
+  - Performance considerations for large lists
+  - Examples: animated galleries, dynamic to-do lists, filtered product grids
+  - Add/remove item animations
+  - Infinite scroll integration patterns
+
+### **Stage 4: Usage Examples and Patterns**
+
+**What:** Practical examples and common patterns
+**Where:** `packages/interact/docs/examples/` directory
+**Why:** Developers learn best from working examples and common use cases
+
+**Deliverables:**
+
+- Prefer using examples of Effects using `keyframeEffect` over `namedEffect`
+- Basic examples for each trigger type (extracted from playground)
+- Advanced patterns (chaining animations, conditional effects)
+- Integration examples (with React, vanilla JS)
+- Performance optimization patterns
+- Common pitfalls and troubleshooting
+
+**NEW: Expanded Example Categories:**
+
+- **List Patterns** (HIGH PRIORITY):
+  - Staggered entrance animations for list items (10+ variations)
+  - Add/remove item animations with smooth transitions
+  - Sorting and filtering with animated transitions
+  - Infinite scroll integration patterns
+  - Grid-to-list layout transitions
+  - Drag-and-drop with visual feedback
+- **Selector Pattern Examples:**
+  - Complex component targeting strategies
+  - `listContainer` + `selector` combinations with real use cases
+  - Dynamic selector strategies for SPAs
+  - Nested component interactions
+  - Cross-element targeting patterns
+
+- **Effect Cascading Examples:**
+  - Responsive effect variations using effect-level conditions
+  - Mobile-first progressive enhancement patterns
+  - Graceful degradation with accessibility
+  - Theme-aware animations (light/dark mode)
+  - Performance-based effect selection
+
+- **Code Quality Standards:**
+  - All examples include TypeScript types
+  - Both vanilla JS and React versions
+  - Before/after HTML structure shown
+  - Common gotchas documented as comments
+  - Copy-paste ready with zero modifications needed
+
+### **Stage 5: Migration and Integration Guides**
+
+**What:** Guides for adopting and integrating the package
+**Where:** `packages/interact/docs/integration/` directory
+**Why:** Teams need guidance on how to adopt this into existing projects
+
+**Deliverables:**
+
+- Integration with different frameworks (React, vanilla JS, Vue, Angular, Svelte)
+- Migration from other animation libraries (GSAP, Framer Motion, CSS-only)
+  - Side-by-side comparison examples
+  - Feature mapping tables
+  - Migration checklists
+- Best practices for performance
+- Testing strategies for interactions
+- Debugging and development tools
+
+**NEW: Server-Side Rendering (SSR) Guide** (HIGH PRIORITY):
+
+- Hydration strategies and timing
+- When to initialize Interact (useEffect, componentDidMount, etc.)
+- Avoiding hydration mismatches
+- Next.js integration patterns
+  - App Router (React Server Components)
+  - Pages Router
+  - Client component boundaries
+- Remix integration
+- SvelteKit integration
+- Framework-specific list handling with SSR
+- Progressive enhancement patterns for SSR
+
+### **Stage 6: Advanced Topics**
+
+**What:** Deep-dive technical documentation
+**Where:** `packages/interact/docs/advanced/` directory
+**Why:** Power users and contributors need detailed technical information
+
+**Deliverables:**
+
+- Architecture overview and design decisions
+- Custom trigger development guide
+- Browser compatibility and polyfills
+- Performance optimization techniques
+- Contributing guidelines
+
+### **Implementation Priority Levels**
+
+Given that significant documentation already exists, prioritize work as follows:
+
+**🔴 High Priority (Complete First):**
+
+1. Lists and Dynamic Content guide (new, critical missing feature)
+2. List management API documentation (`addListItems`, `removeListItems`, `watchChildList`)
+3. SSR integration patterns (common pain point for modern frameworks)
+4. Element selection priority flowchart/decision tree
+5. List pattern examples (10+ variations)
+6. Complete "Understanding Triggers" guide (expand existing)
+7. Expand "State Management" guide with list-specific patterns
+
+**🟡 Medium Priority:** 8. Selector pattern examples (complex targeting strategies) 9. Effect cascading examples with conditions 10. Migration guides from GSAP/Framer Motion 11. Framework-specific integration examples (Vue, Angular) 12. Performance optimization patterns for lists 13. Troubleshooting sections for each major feature
+
+**🟢 Lower Priority:** 14. Advanced topics (custom trigger development) 15. Browser compatibility deep-dives 16. Contributing guidelines 17. Experimental features documentation
+
+### **Check-in Points:**
+
+1. **After High Priority Items:** Review with team and early adopters
+2. **After Stage 3:** Validate concept explanations with subject matter experts
+3. **After Stage 4:** Test examples with actual users/developers (must be copy-paste ready)
+4. **After Stage 5:** Validate SSR patterns with framework experts
+5. **After Stage 6:** Final review for completeness and accuracy
+
+### **Success Criteria:**
+
+**User Experience Metrics:**
+
+- ✅ New developers can get first interaction working in under 10 minutes
+- ✅ Developer can implement a staggered list animation in under 5 minutes
+- ✅ Zero ambiguity in element selection priority behavior (flowchart/decision tree)
+- ✅ All example code runs without modification (copy-paste ready)
+- ✅ SSR/hydration works first time for Next.js, Remix, SvelteKit
+
+**Documentation Coverage:**
+
+- ✅ All public APIs have comprehensive documentation with examples
+- ✅ All 7 trigger types fully documented with real-world examples
+- ✅ List management features completely documented (mutation observers, etc.)
+- ✅ Common use cases are covered with copy-paste examples
+- ✅ Advanced users can extend the system with custom triggers
+- ✅ Common framework integrations (React, Vue, Vanilla) all documented
+
+**Quality Standards:**
+
+- ✅ Performance best practices clearly stated for each pattern
+- ✅ Accessibility considerations documented for all interaction types
+- ✅ Browser compatibility clearly stated with workarounds
+- ✅ Troubleshooting section for each major feature
+- ✅ Migration paths from GSAP/Framer Motion documented
+- ✅ Documentation follows monorepo standards and patterns
+
+**Validation Tests:**
+
+- ✅ 5+ external developers test documentation and provide feedback
+- ✅ All code examples validated in TypeScript strict mode
+- ✅ Examples tested in React, Vue, and vanilla JS environments
+- ✅ SSR patterns validated in production-like environments
+
+### **Documentation Tools & Format:**
+
+- Markdown files for consistency with monorepo
+- TypeScript code examples with syntax highlighting
+- Interactive examples linking to playground
+- Auto-generated API docs from TypeScript comments
+- Clear cross-references between related concepts
+
+---
+
+## **Identified Content Gaps & Specific Topics to Address**
+
+### **Critical Missing Documentation**
+
+1. **`listContainer` Feature** (🔴 High Priority)
+
+   ```typescript
+   // This pattern is used throughout the codebase but poorly documented
+   {
+     key: 'gallery',
+     listContainer: '.gallery-grid',     // Selects container
+     selector: '.gallery-item img',      // Selects within each child
+     trigger: 'hover',
+     effects: [/* ... */]
+   }
+   ```
+
+   **Required Coverage:**
+   - How `listContainer` works with mutation observers
+   - When to use vs multiple separate elements
+   - Performance implications of list vs individual elements
+   - Staggered animation patterns
+   - Memory management for large lists
+
+2. **Element Selection Priority** (🔴 High Priority)
+
+   **Resolution Order (needs clear flowchart):**
+
+   ```
+   1. listContainer specified?
+      → Yes: Match children using selector (or all immediate children)
+      → No: Continue to step 2
+
+   2. selector specified?
+      → Yes: querySelector within interact-element
+      → No: Use first child element (fallback)
+   ```
+
+   **Edge Cases to Document:**
+   - What happens when `listContainer` + `selector` matches nothing?
+   - Inheritance behavior from Interaction to Effect
+   - Selector specificity and combinators
+
+3. **Dynamic List Management** (🔴 High Priority)
+
+   **API Methods Missing Docs:**
+   - `watchChildList(listContainer: string): void`
+   - `addListItems(root, key, listContainer, elements)`
+   - `removeListItems(elements)`
+   - `_observers` WeakMap structure
+
+   **Behavior to Document:**
+   - Automatic mutation tracking setup
+   - When observers are created/destroyed
+   - Performance with rapid DOM changes
+   - Interaction with frameworks' virtual DOM
+
+4. **Effect Cascading with Conditions** (🟡 Medium Priority)
+
+   **Pattern to Document:**
+
+   ```typescript
+   // Effects cascade like CSS - last matching wins
+   effects: [
+     {
+       key: 'card',
+       effectId: 'slide-mobile',
+       conditions: ['mobile'], // Applies on mobile
+     },
+     {
+       key: 'card',
+       effectId: 'slide-tablet',
+       conditions: ['tablet'], // Overrides on tablet
+     },
+     {
+       key: 'card',
+       effectId: 'slide-desktop',
+       conditions: ['desktop'], // Overrides on desktop
+     },
+   ];
+   ```
+
+5. **SSR and Hydration** (🔴 High Priority)
+
+   **Framework Patterns Needed:**
+   - Next.js App Router (use client boundaries)
+   - Next.js Pages Router (useEffect timing)
+   - Remix (clientLoader vs useEffect)
+   - SvelteKit (onMount timing)
+   - Common hydration pitfalls
+
+6. **Performance Best Practices**
+
+   **Topics to Cover:**
+   - When to use `listContainer` (100+ items → use listContainer)
+   - Transform/opacity vs layout properties
+   - Event delegation considerations
+   - Memory implications of many interactions
+   - RequestAnimationFrame usage in handlers
+
+### **Documentation Quality Improvements Needed**
+
+1. **Add Troubleshooting Sections to Each Guide:**
+   - Common error messages and solutions
+   - Debug checklist with specific steps
+   - Browser DevTools integration tips
+   - Performance profiling guidance
+
+2. **Enhance All Code Examples:**
+
+   ```typescript
+   // ✅ GOOD: Complete, typed, copy-paste ready
+   import { Interact, type InteractConfig } from '@wix/interact';
+
+   const config: InteractConfig = {
+     interactions: [
+       {
+         key: 'my-button',
+         trigger: 'hover',
+         effects: [
+           /* ... */
+         ],
+       },
+     ],
+   };
+
+   // Initialize in useEffect for React
+   useEffect(() => {
+     const instance = Interact.create(config);
+     return () => {
+       // Cleanup if needed
+     };
+   }, []);
+   ```
+
+   **Every example should include:**
+   - TypeScript types
+   - Framework context (vanilla/React/Vue)
+   - Before/after HTML structure
+   - Common gotchas as comments
+
+3. **Add Migration Guides:**
+
+   | From                   | To @wix/interact      | Difficulty |
+   | ---------------------- | --------------------- | ---------- |
+   | GSAP Timeline          | Chained interactions  | Medium     |
+   | Framer Motion variants | Effect configurations | Easy       |
+   | CSS animations only    | Time effects          | Easy       |
+   | IntersectionObserver   | viewEnter trigger     | Easy       |
+   | ScrollTrigger          | viewProgress trigger  | Medium     |
+
+### **Quick Reference Additions Needed**
+
+1. **Decision Trees/Flowcharts:**
+   - When to use which trigger type
+   - Element selection priority flowchart
+   - listContainer vs multiple elements decision tree
+   - Effect type selection guide
+
+2. **Comparison Tables:**
+   - Trigger types feature comparison
+   - Effect types capabilities matrix
+   - Browser support matrix
+   - Framework integration approaches
+
+3. **Cheat Sheets:**
+   - Common patterns quick reference
+   - Selector syntax examples
+   - Configuration templates
+   - TypeScript type helpers
+
+---
+
+## **Next Steps to Execute Plan**
+
+**Phase 1: High Priority Documentation (Week 1-2)**
+
+1. Create "Lists and Dynamic Content" guide
+2. Document list management APIs
+3. Create element selection flowchart
+4. Write SSR integration guide
+5. Create 10+ list animation examples
+
+**Phase 2: Medium Priority Completion (Week 3-4)** 6. Complete "Understanding Triggers" guide 7. Expand selector pattern examples 8. Add troubleshooting sections 9. Create migration guides 10. Framework integration examples
+
+**Phase 3: Quality & Polish (Week 5-6)** 11. Validate all examples in strict TypeScript 12. Test with external developers 13. Add performance profiling guides 14. Create quick reference cards 15. Final review and team feedback
+
+---
+
+**Ready to begin? Start with High Priority Item #1: Lists and Dynamic Content guide.**
diff --git a/packages/interact/dev/LIST_PLAN.md b/packages/interact/dev/LIST_PLAN.md
new file mode 100644
index 00000000..1b0cbb53
--- /dev/null
+++ b/packages/interact/dev/LIST_PLAN.md
@@ -0,0 +1,212 @@
+# General Context
+
+## Available Named Effects for List Animations
+
+**Entrance Effects (Time-based):**
+
+- `FadeIn`, `SlideIn`, `BounceIn`, `ExpandIn`, `RevealIn`, `BlurIn` - basic entrance animations
+- `ShuttersIn` - specifically supports `staggered: boolean` property for built-in staggering
+- `FlipIn`, `SpinIn`, `GlideIn`, `TurnIn` - dynamic entrance effects
+- `ShapeIn` - shape-based reveals with direction control
+
+**Scroll Effects (Progress-based):**
+
+- `FadeScroll`, `BlurScroll`, `SlideScroll`, `RevealScroll`, `ShuttersScroll`, `ShapeScroll` - revealing scroll-driven animations
+- `ParallaxScroll`, `MoveScroll`, `GrowScroll`, `ShrinkScroll`, `PanScroll`, `TurnScroll` - movement-based scroll effects
+- `SpinScroll`, `TiltScroll`, `ArcScroll`, `Spin3dScroll`, `TiltScroll` - visual transformation effects
+
+**Background Effects:**
+
+- `BgParallax`, `BgFade`, `BgPan`, `BgZoom` - container-level background animations
+
+## Current Architecture Patterns
+
+**ViewProgress ranges**: `entry`, `cover`, `exit`, `contain` for different scroll phases
+**Effect types**: `namedEffect`, `keyframeEffect`, `customEffect` for different complexity levels
+
+## Common List-based Scroll Animation Patters
+
+**Sticky Container List Animations** where the container is sticky inside a longer wrapper element, and animated using translation transforms while it's sticky inside the `contain` range
+**Sticky Container List Item Animations** where the container is sticky inside a longer wrapper element, and its individual items, or their content, are animated while it's sticky inside the `contain` range using different offsets per item
+**Sticky Item List Animations** where the items are sticky inside the container, and are animated into view, or in and out of view, using various effects like transforms, clip-path, or opacity, while using either the container as the timeline with different ranges, or each item uses itself as the timeline with any range, depending on the effect
+**Sticky Item List Items' Contents Animations** where either the container or the items are sticky, and content inside the items use their containing item as the timeline for animations applied to them
+**Animating while content is stuck in view** uses the `contain` range
+**Animating while content enters view** uses the `entry` range
+**Animating while content exits view** uses the `exit` range
+
+---
+
+# **LIST SCROLL ANIMATION RULES GENERATION PLAN**
+
+## **Stage 1: Core List Animation Rule Categories (Foundation)**
+
+### **1.1 Sticky Container List Animations**
+
+- **Objective**: Create rules for animations applied to list containers that are sticky-positioned within their wrapper
+- **Scope**: Container-level effects during sticky scroll phases
+- **Key Patterns**:
+  - Container horizontal sliding during sticky phase
+  - Container parallax effects during sticky phase
+  - Container reveal transitions
+  - Background transformations synchronized with scroll
+
+### **1.2 Sticky Item List Animations**
+
+- **Objective**: Generate rules for animations on individual list items that are sticky-positioned within the container
+- **Scope**: Item-level effects as items enter/exit sticky positioning
+- **Key Patterns**:
+  - Item entrance/exit animations
+  - Progressive item reveals
+  - Item transformation during sticky phases
+
+### **1.3 Sticky Item List Content Animations**
+
+- **Objective**: Generate rules for animations on content of individual list items that are sticky-positioned within the container
+- **Scope**: Coordinated animations with calculated delays
+- **Key Patterns**:
+  - Entry staggering (sequential reveals)
+  - Exit staggering (sequential dismissals)
+  - Wave-like animation propagation
+
+## **Stage 2: Named Effect Rule Patterns (20 Rules)**
+
+### **2.1 Container-Level Named Effects (5 Rules)**
+
+- **Container Parallax Rule**: `BgParallax`, `BgReveal` for sticky container backgrounds
+- **Container Transform Rule**: `PanScroll` for container-level horizontal transformation
+- **Container Background Rule**: `BgPan`, `BgSkew` for dynamic backgrounds
+
+### **2.2 List Item Named Effects (10 Rules)**
+
+- **Item Entrance/Exit Rules**: `FadeScroll`, `SlideScroll`, `ShapeScroll`, `RevealScroll`, `MoveScroll`, `ShuttersScroll` for item reveals
+- **Item Transformation Rules**: `GrowScroll`, `ShrinkScroll`, `SpinScroll`, `ArcScroll` for item scaling/rotation
+
+### **2.3 Content-Level Named Effects (5 Rules)**
+
+- **Content Reveal Rules**: `RevealScroll`, `FadeScroll` for text/image reveals within items
+- **Content Motion Rules**: `TiltScroll`, `FlipScroll` for content dynamics
+- **Content Progressive Rules**: Using entrance effects (`GrowScroll`, `FadeScroll`) triggered by scroll progress
+- **Content Interactive Rules**: Combined hover + scroll effects for rich interactions
+
+## **Stage 3: Keyframe Effect Rule Patterns (15 Rules)**
+
+### **3.1 Custom Container Keyframes (5 Rules)**
+
+- **Multi-Property Container**: Combined transform, opacity, filter effects
+- **Responsive Container**: Different keyframes for mobile vs. desktop
+- **Timed Container**: Sequential keyframe phases during sticky periods
+- **Background Container**: Complex background position/filter combinations
+- **Layout Container**: Subtle spacing/padding adjustments during scroll
+
+### **3.2 Custom Item Keyframes (7 Rules)**
+
+- **Complex Item Entrance**: Multi-property entrance with unique timing
+- **Item Position Flow**: Advanced positioning with perspective effects
+- **Item Content Coordination**: Synchronizing item wrapper with content animations
+- **Item Responsive**: Adaptive keyframes based on screen size
+- **Item Interaction**: Hover-enhanced scroll effects
+- **Item Exit Sequence**: Complex multi-stage exit animations
+- **Item State Transition**: Animations between different list states
+
+### **3.3 Custom Content Keyframes (3 Rules)**
+
+- **Text Progressive**: Letter-by-letter or word-by-word reveals
+- **Image Complex**: Multi-layer image animations with masks/filters
+- **Media Synchronized**: Video/audio content synchronized with scroll
+
+## **Stage 4: Custom Effect Rule Patterns (12 Rules)**
+
+### **4.1 Stagger Calculation Rules (4 Rules)**
+
+- **Linear Stagger**: Even delays across all items `(index / total) * maxDelay`
+- **Exponential Stagger**: Accelerating delays `Math.pow(index / total, 2) * maxDelay`
+- **Wave Stagger**: Sine wave-based delays for organic feeling
+- **Reverse Stagger**: Reverse-order animations for exit effects
+
+### **4.2 Dynamic Content Rules (4 Rules)**
+
+- **Counter Animation**: Scroll-driven number counting within items
+- **Progress Tracking**: Visual progress indicators within list context
+- **Interactive Data**: Data visualization updates during scroll
+- **Dynamic Text**: Text content that changes based on scroll position
+
+### **4.3 Complex Coordination Rules (4 Rules)**
+
+- **Multi-Layer Lists**: Coordinating background, item, and content layers
+- **Cross-Item Effects**: Items affecting neighboring items during animation
+- **Conditional Staggering**: Different stagger patterns based on conditions
+- **Adaptive Performance**: Reducing complexity based on list length/performance
+
+## **Stage 5: Configuration Factory Patterns (8 Factories)**
+
+### **5.1 List Type Factories (4 Factories)**
+
+- **`createStickyListConfig`**: For sticky-positioned list containers
+- **`createStickyItemConfig`**: For lists with sticky-positioned items
+- **`createScrollListConfig`**: For standard scroll-through lists
+- **`createInfiniteListConfig`**: For infinite scroll list patterns
+
+### **5.2 Animation Style Factories (4 Factories)**
+
+- **`createStaggeredListConfig`**: Parameterized stagger generation
+- **`createParallaxListConfig`**: Multi-layer parallax list effects
+- **`createProgressiveListConfig`**: Progressive reveal/hide patterns
+- **`createInteractiveListConfig`**: Combined hover/scroll list interactions
+
+## **Stage 6: Integration & Responsive Patterns (5 Rules)**
+
+### **6.1 Responsive Adaptation (3 Rules)**
+
+- **Mobile-First Lists**: Simplified animations for touch devices
+- **Desktop Enhancement**: Complex effects for desktop hover/scroll
+- **Performance Scaling**: Adaptive complexity based on device capabilities
+
+### **6.2 Accessibility & Performance (2 Rules)**
+
+- **Reduced Motion Support**: Alternative patterns for `prefers-reduced-motion`
+- **Performance Optimization**: Hardware acceleration and efficient property usage
+
+## **Stage 7: Documentation & Examples (Final)**
+
+### **7.1 Comprehensive Documentation**
+
+- Complete rule documentation with examples
+- Use case guides for different list scenarios
+- Performance and accessibility guidelines
+
+### **7.2 Real-World Example Configurations**
+
+- E-commerce product lists
+- Content feed animations
+- Navigation menu dynamics
+- Dashboard widget lists
+
+---
+
+# **Success Criteria**
+
+1. **Comprehensive Coverage**: Rules address all major list animation scenarios (container, items, content)
+2. **Performance Optimized**: All rules use hardware-accelerated properties and efficient patterns
+3. **Responsive Ready**: Rules include mobile/desktop variations and adaptive complexity
+4. **Developer Friendly**: Configuration factories reduce boilerplate and enable quick implementation
+5. **Accessibility Compliant**: All rules respect motion preferences and performance constraints
+
+---
+
+# **Implementation Approach**
+
+The plan follows a layered approach:
+
+- **Foundation** (Stage 1): Core categories and architectural patterns
+- **Named Effects** (Stage 2): Leveraging existing @wix/motion effects with list-specific patterns
+- **Custom Keyframes** (Stage 3): Precise control for unique list behaviors
+- **Advanced Custom** (Stage 4): JavaScript-powered complex interactions
+- **Factories** (Stage 5): Reusable configuration generators
+- **Integration** (Stage 6): Responsive and accessibility considerations
+- **Documentation** (Stage 7): Complete implementation guidance
+
+Each stage builds upon previous stages, ensuring comprehensive coverage while maintaining practical usability for developers implementing list scroll animations.
+
+---
+
+**Switch to agent mode and type execute (or execute stage 1) to begin.**
diff --git a/packages/interact/dev/RULES_PLAN.md b/packages/interact/dev/RULES_PLAN.md
new file mode 100644
index 00000000..4f51c477
--- /dev/null
+++ b/packages/interact/dev/RULES_PLAN.md
@@ -0,0 +1,288 @@
+## Phase 1: Context Summary
+
+**Tools Utilized & Key Discoveries:**
+
+- Used `read_file` on core files (`interact.ts`, `types.ts`, `InteractElement.ts`, `utils.ts`) to understand the main API structure and configuration patterns
+- Used `list_dir` to explore package structure and handlers organization, discovering modular trigger system
+- Used `file_search` to find examples documentation with common usage patterns
+- Used `read_file` on motion types and handler implementations to understand effect integration patterns
+
+**Key Files, Functions, Types & Structures Involved:**
+
+1. **Core API**: `Interact` class with static `create()` method, `InteractConfig` as main configuration object
+2. **Core Types**:
+   - `InteractConfig` structure: `{effects, conditions?, interactions}`
+   - `Interaction`: `{key, selector? listContainer?, trigger, params?, conditions?, effects}`
+   - Effect types: `TimeEffect`, `ScrubEffect`, `TransitionEffect` with union `Effect`
+   - `TriggerType`: 7 types (`hover`, `click`, `viewEnter`, `pageVisible`, `animationEnd`, `viewProgress`, `pointerMove`)
+3. **Custom Element**: `<interact-element>` with required `data-interact-key` attribute
+4. **Handler System**: Modular trigger handlers in `/src/handlers/` with consistent `add/remove` pattern
+5. **Motion Integration**: Named effects from `@wix/motion` (FadeIn, SlideIn, etc.) and custom keyframe effects
+
+**Current Data Flow & Observed Patterns:**
+
+- Configuration flows through: `InteractConfig` → `parseConfig()` → `InteractCache` → Element registration → Handler binding
+- Two effect definition patterns: inline effects vs reusable effects with `effectId` references
+- Conditions system enables responsive/conditional interactions using media queries
+- Custom element wrapper manages DOM lifecycle and state via CSS custom states
+- Template patterns evident in documentation for common use cases
+
+**Reference Implementations/Utilities Found:**
+
+- Rich examples in `/docs/examples/README.md` showing entrance animations, hover effects, scroll animations
+- Template structures demonstrating configuration patterns
+- Modular handler architecture with shared utilities (`generateId`, `createTransitionCSS`)
+- Type-safe configuration patterns with comprehensive TypeScript definitions
+
+**Potential Challenges, Risks & Considerations:**
+
+- Complex discriminated union types require careful rule generation to maintain type safety
+- Multiple effect types (Time/Scrub/Transition) need different generation strategies
+- Handler registration lifecycle and cleanup patterns must be preserved
+- Integration with motion library's NamedEffect types needs consideration for effect selection
+- Custom element key matching requirements between configuration and DOM
+- **List-based interactions**: `listContainer` with dynamic mutation observer behavior needs specialized rules
+- **Element targeting complexity**: Priority order (listContainer → selector → firstElementChild) and inheritance patterns
+- **Selector non-inheritance**: Unlike `key`, `selector` and `listContainer` are NOT inherited from Interaction to Effect level
+- **Pointer-driven animations**: hitArea, centeredToTarget, symmetric/anti-symmetric patterns need careful handling
+
+---
+
+## Phase 2: Formulate a Plan
+
+Based on the comprehensive exploration, here's a detailed plan for creating rules to generate Interact library code:
+
+### Stage 1: Core Configuration Generation Rules
+
+**What**: Rules for generating basic `InteractConfig` objects and `Interaction` structures per trigger type
+**Where**: Focus on all 7 trigger types with their most common patterns and use cases
+**Why**: Each trigger type has distinct patterns, parameters, and typical effects that warrant specialized rules
+**How**: Create templates for interactions of specific types with placeholders, without actual effect content
+
+**Sub-stages (each in separate files):**
+
+#### Stage 1.1: Hover Trigger Rules (`hover-rules.md`)
+
+- Rule for hover effect configuration with state management pattern
+- Rule for hover enter/leave animations pattern
+- Rule for pointer-based hover interactions with alternate pattern
+- Rule for pointer-based hover interactions with repeat pattern
+- RUle for pointer-based hover interactions with play/pause pattern
+
+#### Stage 1.2: Click Trigger Rules (`click-rules.md`)
+
+- Rule for click effect configuration with TimeEffects and alternate pattern
+- Rule for click effect configuration with TimeEffects and state pattern
+- Rule for click effect configuration with TimeEffects and repeat pattern
+- Rule for click effect configuration with state toggles and TransitionEffects pattern
+
+#### Stage 1.3: ViewEnter Trigger Rules (`viewenter-rules.md`)
+
+- Rule for entrance animation configuration with once type pattern
+- Rule for entrance animation configuration with repeat type and separate source and target pattern
+- Rule for entrance animation configuration with alternate type and separate source and target pattern
+- Rule for loop animation configuration with state type pattern
+- Rule for threshold and viewport intersection parameters pattern
+- Rule for staggered entrance animations pattern
+
+#### Stage 1.4: ViewProgress Trigger Rules (`viewprogress-rules.md`)
+
+- Rule for range-based parallax/continuous animation control with namedEffects pattern
+- Rule for range-based entry animation control with namedEffects pattern
+- Rule for range-based exit animation control with namedEffects pattern
+- Rule for range-based parallax/continuous animation control with keyframeEffects pattern
+- Rule for range-based entry animation control with keyframeEffects pattern
+- Rule for range-based exit animation control with keyframeEffects pattern
+- Rule for range-based parallax/continuous animation control with customEffects pattern
+- Rule for range-based entry animation control with customEffects pattern
+- Rule for range-based exit animation control with customEffects pattern
+
+#### Stage 1.5: PointerMove Trigger Rules (`pointermove-rules.md`)
+
+- Rule for hit area configuration (`root` vs `self`) with appropriate use cases
+- Rule for centering range to animation target using `centeredToTarget` configuration
+- Rule for symmetric pointer effects (same animation in both directions)
+- Rule for anti-symmetric pointer effects (inverted animation based on direction)
+- Rules for pointer-based effects of single elements with namedEffect
+- Rules for pointer-based parallax effects of a group of elements with namedEffect
+
+#### Stage 1.6: AnimationEnd Trigger Rules (`animationend-rules.md`)
+
+- Rule for configuration of entrance and loop animations chaining pattern
+- Rule for configuration of entrance animations chaining of different elements pattern
+
+#### Stage 1.7: PageVisible Trigger Rules (`pagevisible-rules.md`)
+
+- Rule for page load animations
+- Rule for global state management
+- Rule for one-time initialization effects
+
+#### Stage 1.8: List-Based Interaction Rules (`scroll-list-rules.md`)
+
+- Rule for `listContainer` with automatic child detection (targets all immediate children)
+- Rule for `listContainer` + `selector` for targeting specific elements within list items
+- Rule for gallery/grid interaction patterns
+- Rule for performance optimization with large lists
+
+**Common Deliverables:**
+
+- Template for base `InteractConfig` structure validation
+- Shared utilities for key generation and validation
+- Common effect pattern templates
+
+### Stage 2: Element Targeting and Selector Rules
+
+**What**: Rules for element targeting using `key`, `selector`, and `listContainer`
+**Where**: Both Interaction and Effect levels with proper inheritance/non-inheritance patterns
+**Why**: Element targeting is complex with priority order and non-obvious inheritance behavior
+
+**Deliverables:**
+
+- Rule for element targeting priority: listContainer → selector → firstElementChild
+- Rule for when `key` defaults from Interaction to Effect (when Effect.key is omitted)
+- Rule for selector non-inheritance: Effect.selector must be explicit (not inherited from Interaction.selector)
+- Rule for listContainer non-inheritance: Effect.listContainer must be explicit
+- Rule for cross-element targeting (source ≠ target) patterns
+- Rule for self-targeting patterns (source = target or Effect.key omitted)
+- Rule for nested selector patterns within custom elements
+- Rule for combining listContainer + selector for list item children
+
+### Stage 3: Effect Generation Rules
+
+**What**: Rules for generating the three effect types with appropriate defaults
+**Where**: Time effects (most common), transition effects, scrub effects
+**Why**: Effects are the core value-add and have clear patterns from documentation
+
+**Deliverables:**
+
+- Rule for TimeEffect with named effects (FadeIn, SlideIn, etc.)
+- Rule for TimeEffect with custom keyframes
+- Rule for TransitionEffect with CSS properties
+- Rule for ScrubEffect with scroll/pointer triggers
+- Effect selection helper based on trigger type
+- Rule for inline effects vs reusable effects with `effectId` references
+
+### Stage 4: Custom Element and DOM Integration Rules
+
+**What**: Rules for generating proper `<interact-element>` markup and key management
+**Where**: HTML/JSX generation with proper `data-interact-key` attributes
+**Why**: Required for library function and common source of integration errors
+
+**Deliverables:**
+
+- Rule for custom element wrapper generation
+- Rule for element key generation and validation (matching data-interact-key to config key)
+- Rule for React/JSX integration patterns
+- Rule for Vue/Angular custom element usage
+- Rule for ensuring at least one child element exists
+
+### Stage 5: Advanced Configuration Rules
+
+**What**: Rules for conditions, effect references, and complex patterns
+**Where**: Responsive interactions, reusable effects, multistep animations
+**Why**: Enables scaling beyond basic use cases
+
+**Deliverables:**
+
+- Rule for media query conditions (device size, orientation, reduced motion, dark mode)
+- Rule for container query conditions
+- Rule for reusable effect patterns with `effectId`
+- Rule for animation sequences and chaining (using animationEnd trigger)
+- Rule for responsive/conditional interactions with cascading effects
+- Rule for combining multiple conditions with AND logic
+
+### Stage 6: Type Safety and Validation Rules
+
+**What**: Rules ensuring generated code maintains TypeScript safety
+**Where**: Configuration validation, effect property validation, trigger parameter validation
+**Why**: Critical for developer experience and catching errors early
+
+**Deliverables:**
+
+- Type validation rules for each configuration pattern
+- Runtime validation helpers
+- Error message generation for common mistakes
+- IDE integration patterns
+- Discriminated union handling for Effect types
+- Parameter validation based on trigger type
+
+### Stage 7: Integration and Testing Rules
+
+**What**: Rules for testing generated interactions and integration patterns
+**Where**: Unit test generation, E2E test patterns, performance validation
+**Why**: Ensures generated code works correctly and performs well
+
+**Deliverables:**
+
+- Test case generation for interactions
+- Performance validation rules
+- Integration pattern validation
+- Documentation generation for generated code
+- Browser compatibility testing patterns
+- Accessibility testing for animations (reduced motion)
+
+---
+
+**Check-in Points:**
+
+- After Stage 1: Validate all 7 trigger types generate correct configuration patterns
+- After Stage 2: Verify element targeting rules handle all selector/listContainer combinations
+- After Stage 3: Ensure effect generation covers all three types (Time/Scrub/Transition)
+- After Stage 4: Verify DOM integration works correctly with proper key matching
+- After Stage 5: Test condition cascading and responsive patterns
+- After Stage 6: Ensure type safety is maintained throughout all generated code
+- Final: Comprehensive testing of all rule combinations and edge cases
+
+**Success Criteria:**
+
+- ✅ Generated code passes TypeScript compilation with no errors
+- ✅ Generated interactions work as expected in browser
+- ✅ Rules cover 100% of documented example patterns
+- ✅ All 7 trigger types have comprehensive rule coverage
+- ✅ Element targeting rules correctly handle priority order (listContainer → selector → firstElementChild)
+- ✅ Selector and listContainer non-inheritance is properly enforced
+- ✅ List-based interactions with mutation observers work correctly
+- ✅ Pointer-driven animations support both symmetric and anti-symmetric patterns
+- ✅ Conditions system supports media queries, container queries, and cascading
+- ✅ AnimationEnd trigger enables proper animation chaining
+- ✅ Integration with existing tooling (IDE, linting, testing)
+- ✅ Generated code respects accessibility (reduced motion) preferences
+- ✅ Performance patterns for large lists and frequent updates are included
+
+---
+
+## Priority Implementation Order
+
+Based on current progress and critical gaps identified:
+
+### **Phase 1: Foundation (Completed ✅)**
+
+- Stage 1.1-1.3: Basic triggers (hover, click, viewEnter) ✅
+- Stage 1.4: ViewProgress rules ✅
+- Stage 1.5: PointerMove rules ✅
+
+### **Phase 2: Critical Gaps (HIGH PRIORITY)**
+
+- **Stage 1.8**: List-Based Interaction Rules - Essential for galleries and grids
+- **Stage 2**: Element Targeting Rules - Critical for understanding selector behavior
+- **Stage 1.6-1.7**: AnimationEnd and PageVisible triggers
+
+### **Phase 3: Effect Completeness (MEDIUM PRIORITY)**
+
+- **Stage 3**: Complete effect generation rules with all three types
+- Inline vs reusable effect patterns
+- Effect cascading with conditions
+
+### **Phase 4: Integration & Advanced (LOWER PRIORITY)**
+
+- **Stage 4**: Custom element and DOM integration
+- **Stage 5**: Advanced configuration with conditions
+- **Stage 6-7**: Type safety, validation, and testing
+
+### **Next Immediate Actions:**
+
+1. Create `scroll-list-rules.md` with listContainer patterns
+2. Create element targeting guide explaining selector inheritance/non-inheritance
+3. Enhance pointer-move rules with symmetric/anti-symmetric patterns
+4. Add animationEnd chaining patterns
+5. Document performance optimization for large lists
diff --git a/packages/interact/dev/VIEW_ENTER_SPEC.md b/packages/interact/dev/VIEW_ENTER_SPEC.md
new file mode 100644
index 00000000..ac3243c0
--- /dev/null
+++ b/packages/interact/dev/VIEW_ENTER_SPEC.md
@@ -0,0 +1,28 @@
+# `viewEnter` Beyond `type: 'once'`
+
+This is specification document for implementing the rest of the values for `type` property of `params` for `trigger: 'viewEnter'`.
+
+- Currently only `type: once` is implemented for the `viewEnter` trigger
+- Other types that should also be implemented are: `alternate`, `repeat`, and `state`
+- The initial flow for Interactions with these types are the same as for `once`
+- These types should also track when the element exits the range \- `isIntersecting: false`
+- We’ll start by using a default exit observer for each type \- without providing an API to specify its options
+- We need to make sure we [persist](https://developer.mozilla.org/en-US/docs/Web/API/Animation/persist) the animation on these types.
+
+# `alternate`
+
+- When exiting the range the animation should be reversed.
+- On subsequent re-entry the animation should be reversed (not play, since it was reversed on last exit)
+- By default we can use the same observer as the one for entry.
+
+# `repeat`
+
+- By default we can use a separate observer that watches when the element is completely out of view
+- When exiting the range the animation should be paused and set its progress to 0 (like “stop”).
+- On subsequent re-entry the animation should be played from 0
+
+# `state`
+
+- By default we can use a separate observer that watches when the element is completely out of view
+- When exiting the range the animation should be paused.
+- On subsequent re-entry the animation should be resumed (calling `.play()` should resume it)

From f241242fb4b895202155a6471547014ef47ecf93 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Tue, 3 Feb 2026 10:49:54 +0200
Subject: [PATCH 17/29] yarn format

---
 ...ce_feature_implementation_84c01c97.plan.md |  4 ++--
 apps/demo/src/styles.css                      | 14 +++++++++---
 apps/demo/src/web/components/SequenceDemo.tsx | 22 ++++++++++++++-----
 packages/interact/src/core/Interact.ts        |  7 +++++-
 packages/interact/src/core/add.ts             |  6 ++++-
 packages/interact/src/types.ts                |  2 +-
 packages/motion/src/AnimationGroup.ts         |  2 +-
 packages/motion/src/Sequence.ts               | 17 ++++++++++----
 packages/motion/src/motion.ts                 |  7 +++++-
 packages/motion/src/utils.ts                  | 11 ++++++++--
 packages/motion/test/Sequence.spec.ts         |  8 ++++++-
 11 files changed, 77 insertions(+), 23 deletions(-)

diff --git a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
index ef334875..6a5fe513 100644
--- a/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
+++ b/.cursor/plans/sequence_feature_implementation_84c01c97.plan.md
@@ -44,6 +44,7 @@ Create new file `packages/motion/src/Sequence.ts`:
 - Store `animationGroups: AnimationGroup[]` instead of `animations: Animation[]`
 - Add properties: `delay`, `offset`, `offsetEasing`
 - Implement `calculateOffsets()` method using the formula from spec:
+
 ```typescript
 const last = indices.at(-1);
 indices.map((n) => (easing(n / last) * last * offset) | 0);
@@ -123,7 +124,6 @@ Modify `packages/interact/src/core/Interact.ts`:
 
 1. Parse `config.sequences` into cache (similar to `config.effects`)
 2. Process `interaction.sequences` array:
-
    - Resolve `sequenceId` references from `config.sequences`
    - Process each effect within the sequence
    - Generate unique IDs for sequence effects
@@ -178,4 +178,4 @@ The calculated offsets are added to each effect's existing `delay` property.
 1. Unit tests for `Sequence` class offset calculations
 2. Unit tests for easing function integration
 3. Integration tests for sequence parsing in Interact
-4. E2E tests for staggered animations with various easing functions
\ No newline at end of file
+4. E2E tests for staggered animations with various easing functions
diff --git a/apps/demo/src/styles.css b/apps/demo/src/styles.css
index cb23523e..8f5e7f53 100644
--- a/apps/demo/src/styles.css
+++ b/apps/demo/src/styles.css
@@ -698,7 +698,9 @@ body {
   font-weight: 600;
   font-size: 0.9rem;
   cursor: pointer;
-  transition: transform 0.2s ease, box-shadow 0.2s ease;
+  transition:
+    transform 0.2s ease,
+    box-shadow 0.2s ease;
 }
 
 .sequence-reset-button {
@@ -728,7 +730,9 @@ body {
   border-radius: 1rem;
   padding: 1.5rem;
   cursor: pointer;
-  transition: border-color 0.2s ease, background 0.2s ease;
+  transition:
+    border-color 0.2s ease,
+    background 0.2s ease;
 }
 
 .sequence-trigger-area:hover {
@@ -760,7 +764,11 @@ body {
 .sequence-item {
   aspect-ratio: 1;
   min-width: 80px;
-  background: linear-gradient(135deg, var(--item-color) 0%, color-mix(in srgb, var(--item-color) 70%, white) 100%);
+  background: linear-gradient(
+    135deg,
+    var(--item-color) 0%,
+    color-mix(in srgb, var(--item-color) 70%, white) 100%
+  );
   border-radius: 12px;
   display: flex;
   align-items: center;
diff --git a/apps/demo/src/web/components/SequenceDemo.tsx b/apps/demo/src/web/components/SequenceDemo.tsx
index 484bd44c..8dbb92cc 100644
--- a/apps/demo/src/web/components/SequenceDemo.tsx
+++ b/apps/demo/src/web/components/SequenceDemo.tsx
@@ -116,8 +116,16 @@ const easingPresets = [
   { name: 'expoIn', value: 'expoIn', description: 'Named easing' },
   { name: 'ease-out', value: 'cubic-bezier(0.4, 0, 0.2, 1)', description: 'CSS cubic-bezier' },
   { name: 'ease-in', value: 'cubic-bezier(0.4, 0, 1, 1)', description: 'CSS cubic-bezier' },
-  { name: 'overshoot', value: 'cubic-bezier(0.34, 1.56, 0.64, 1)', description: 'CSS cubic-bezier (y > 1)' },
-  { name: 'back-in', value: 'cubic-bezier(0.6, -0.28, 0.735, 0.045)', description: 'CSS cubic-bezier (y < 0)' },
+  {
+    name: 'overshoot',
+    value: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+    description: 'CSS cubic-bezier (y > 1)',
+  },
+  {
+    name: 'back-in',
+    value: 'cubic-bezier(0.6, -0.28, 0.735, 0.045)',
+    description: 'CSS cubic-bezier (y < 0)',
+  },
   { name: 'linear ramp', value: 'linear(0, 0.5, 1)', description: 'CSS linear()' },
   { name: 'fast-then-slow', value: 'linear(0, 0.3 50%, 1)', description: 'CSS linear()' },
 ];
@@ -133,7 +141,9 @@ const sequenceItems = [
 
 export const SequenceDemo = () => {
   const [triggerKey, setTriggerKey] = useState(0);
-  const [configText, setConfigText] = useState(() => JSON.stringify(createConfig('quadOut'), null, 2));
+  const [configText, setConfigText] = useState(() =>
+    JSON.stringify(createConfig('quadOut'), null, 2),
+  );
   const [parseError, setParseError] = useState<string | null>(null);
   const [activePreset, setActivePreset] = useState('quadOut');
 
@@ -160,7 +170,7 @@ export const SequenceDemo = () => {
     setTriggerKey((prev) => prev + 1);
   };
 
-  const handlePresetClick = useCallback((preset: typeof easingPresets[0]) => {
+  const handlePresetClick = useCallback((preset: (typeof easingPresets)[0]) => {
     setConfigText(JSON.stringify(createConfig(preset.value), null, 2));
     setActivePreset(preset.value);
     setTriggerKey((prev) => prev + 1);
@@ -172,8 +182,8 @@ export const SequenceDemo = () => {
         <p className="scroll-label">Sequence Feature</p>
         <h3>Staggered Animations</h3>
         <p className="sequence-demo-description">
-          Use <code>offsetEasing</code> to control stagger timing. Supports named easings, 
-          CSS <code>cubic-bezier()</code>, CSS <code>linear()</code>, and custom functions.
+          Use <code>offsetEasing</code> to control stagger timing. Supports named easings, CSS{' '}
+          <code>cubic-bezier()</code>, CSS <code>linear()</code>, and custom functions.
         </p>
       </div>
 
diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index 040025f0..d1e0b812 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -21,7 +21,12 @@ function _convertToKeyTemplate(key: string) {
 }
 
 /** Keys that indicate an effect has its own definition (not just a reference) */
-const EFFECT_DEFINITION_KEYS = ['duration', 'namedEffect', 'keyframeEffect', 'customEffect'] as const;
+const EFFECT_DEFINITION_KEYS = [
+  'duration',
+  'namedEffect',
+  'keyframeEffect',
+  'customEffect',
+] as const;
 
 /** Check if an effect is just a reference to another effect (has effectId but no definition) */
 function isEffectReference(effect: Effect | EffectRef): effect is EffectRef {
diff --git a/packages/interact/src/core/add.ts b/packages/interact/src/core/add.ts
index 695ade6b..3a225efa 100644
--- a/packages/interact/src/core/add.ts
+++ b/packages/interact/src/core/add.ts
@@ -246,7 +246,11 @@ function _addInteraction(
       _sequenceId?: string;
       _sequenceIndex?: number;
       _sequenceTotal?: number;
-      _sequenceOptions?: { delay?: number; offset?: number; offsetEasing?: string | ((t: number) => number) };
+      _sequenceOptions?: {
+        delay?: number;
+        offset?: number;
+        offsetEasing?: string | ((t: number) => number);
+      };
     };
     if (sequenceEffect._sequenceId && 'duration' in effect) {
       const targets = Array.isArray(targetElements) ? targetElements : [targetElements];
diff --git a/packages/interact/src/types.ts b/packages/interact/src/types.ts
index 0dad3f37..6d96eebf 100644
--- a/packages/interact/src/types.ts
+++ b/packages/interact/src/types.ts
@@ -158,7 +158,7 @@ export type Sequence = {
 export type SequenceRef = {
   sequenceId: string;
   delay?: number;
-  offset?: number
+  offset?: number;
   offsetEasing?: string | ((t: number) => number);
 };
 
diff --git a/packages/motion/src/AnimationGroup.ts b/packages/motion/src/AnimationGroup.ts
index 0228ba36..b56901c0 100644
--- a/packages/motion/src/AnimationGroup.ts
+++ b/packages/motion/src/AnimationGroup.ts
@@ -27,7 +27,7 @@ export class AnimationGroup {
       const timing = animation.effect?.getTiming();
       if (timing) {
         const existingDelay = (timing.delay as number) || 0;
-        animation.effect?.updateTiming({ delay: existingDelay + delay, endDelay});
+        animation.effect?.updateTiming({ delay: existingDelay + delay, endDelay });
       }
     }
   }
diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index 5fef7713..af933a51 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -17,7 +17,11 @@ export class Sequence extends AnimationGroup {
     this.sequenceDelay = options?.delay ?? 0;
     this.offset = options?.offset ?? 100;
     this.offsetEasing = resolveEasingFunction(options?.offsetEasing);
-    this._calculatedOffsets = calculateOffsets(animationGroups.length, this.offset, this.offsetEasing);
+    this._calculatedOffsets = calculateOffsets(
+      animationGroups.length,
+      this.offset,
+      this.offsetEasing,
+    );
     this._applyDelays();
   }
 
@@ -25,10 +29,11 @@ export class Sequence extends AnimationGroup {
     const minOffset = Math.min(...this._calculatedOffsets);
     const maxOffset = Math.max(...this._calculatedOffsets);
     const totalSpan = maxOffset - minOffset;
-  
+
     this.animationGroups.forEach((group, index) => {
       // Normalize offset to be non-negative
-      const normalizedOffset = minOffset < 0 ? this._calculatedOffsets[index] - minOffset : this._calculatedOffsets[index];
+      const normalizedOffset =
+        minOffset < 0 ? this._calculatedOffsets[index] - minOffset : this._calculatedOffsets[index];
       const groupDelay = this.sequenceDelay + normalizedOffset;
       const endDelay = totalSpan - normalizedOffset;
       group.applyGroupDelay(groupDelay, endDelay);
@@ -44,7 +49,11 @@ export class Sequence extends AnimationGroup {
   }
 
   recalculateOffsets(): void {
-    this._calculatedOffsets = calculateOffsets(this.animationGroups.length, this.offset, this.offsetEasing);
+    this._calculatedOffsets = calculateOffsets(
+      this.animationGroups.length,
+      this.offset,
+      this.offsetEasing,
+    );
   }
 
   // Note: play(), pause(), reverse(), cancel(), setPlaybackRate(), onFinish(),
diff --git a/packages/motion/src/motion.ts b/packages/motion/src/motion.ts
index 2e0fa1fb..f35edd37 100644
--- a/packages/motion/src/motion.ts
+++ b/packages/motion/src/motion.ts
@@ -216,7 +216,12 @@ function _createAnimation(
 
 // Set up registry with animation creation function
 SequenceRegistry.setGetAnimationFn((target, options, trigger, reducedMotion) => {
-  return _createAnimation(target, options as AnimationOptions, trigger, reducedMotion) as AnimationGroup | null;
+  return _createAnimation(
+    target,
+    options as AnimationOptions,
+    trigger,
+    reducedMotion,
+  ) as AnimationGroup | null;
 });
 
 function getAnimation(
diff --git a/packages/motion/src/utils.ts b/packages/motion/src/utils.ts
index 71e327e7..6dfa19cd 100644
--- a/packages/motion/src/utils.ts
+++ b/packages/motion/src/utils.ts
@@ -14,7 +14,12 @@ export function getJsEasing(
   return easing ? jsEasings[easing as keyof typeof jsEasings] : undefined;
 }
 
-export function createCubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
+export function createCubicBezier(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+): (t: number) => number {
   const cx = 3 * x1;
   const bx = 3 * (x2 - x1) - cx;
   const ax = 1 - cx - bx;
@@ -61,7 +66,9 @@ export function createCubicBezier(x1: number, y1: number, x2: number, y2: number
 }
 
 export function parseCubicBezier(str: string): ((t: number) => number) | null {
-  const match = str.match(/cubic-bezier\s*\(\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^)]+)\s*\)/i);
+  const match = str.match(
+    /cubic-bezier\s*\(\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^,]+)\s*,\s*([^)]+)\s*\)/i,
+  );
   if (!match) return null;
 
   const [, x1, y1, x2, y2] = match.map((v, i) => (i === 0 ? v : parseFloat(v)));
diff --git a/packages/motion/test/Sequence.spec.ts b/packages/motion/test/Sequence.spec.ts
index 38114cdc..ab18c54c 100644
--- a/packages/motion/test/Sequence.spec.ts
+++ b/packages/motion/test/Sequence.spec.ts
@@ -1,6 +1,12 @@
 import { describe, expect, test, vi, beforeEach, beforeAll } from 'vitest';
 import { Sequence } from '../src/Sequence';
-import { calculateOffsets, parseCubicBezier, createCubicBezier, parseLinear, createLinear } from '../src/utils';
+import {
+  calculateOffsets,
+  parseCubicBezier,
+  createCubicBezier,
+  parseLinear,
+  createLinear,
+} from '../src/utils';
 import { AnimationGroup } from '../src/AnimationGroup';
 import { linear, quadIn, sineOut, cubicIn, expoIn, quadOut, cubicOut } from '../src/easings';
 

From 02718f7d2cc81df78ae9756637f85de71f9a947b Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Tue, 3 Feb 2026 15:20:51 +0200
Subject: [PATCH 18/29] fix test

---
 packages/motion/test/Sequence.spec.ts | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/packages/motion/test/Sequence.spec.ts b/packages/motion/test/Sequence.spec.ts
index ab18c54c..ea7055c0 100644
--- a/packages/motion/test/Sequence.spec.ts
+++ b/packages/motion/test/Sequence.spec.ts
@@ -219,16 +219,17 @@ describe('Sequence', () => {
 
     test('should apply delays to animation groups', () => {
       // Creating the sequence applies delays to the animation groups
+      // 3 groups with offset 100: offsets = [0, 100, 200], totalSpan = 200
       new Sequence(mockAnimationGroups, { delay: 50, offset: 100 });
 
-      // First group: delay = 50 + 0 = 50, existing delay = 0 → total = 50
-      expect(mockAnimations[0].effect.updateTiming).toHaveBeenCalledWith({ delay: 50 });
+      // First group: delay = 50 + 0 = 50, existing delay = 0 → total = 50, endDelay = 200 - 0 = 200
+      expect(mockAnimations[0].effect.updateTiming).toHaveBeenCalledWith({ delay: 50, endDelay: 200 });
 
-      // Second group: delay = 50 + 100 = 150, existing delay = 100 → total = 250
-      expect(mockAnimations[1].effect.updateTiming).toHaveBeenCalledWith({ delay: 250 });
+      // Second group: delay = 50 + 100 = 150, existing delay = 100 → total = 250, endDelay = 200 - 100 = 100
+      expect(mockAnimations[1].effect.updateTiming).toHaveBeenCalledWith({ delay: 250, endDelay: 100 });
 
-      // Third group: delay = 50 + 200 = 250, existing delay = 50 → total = 300
-      expect(mockAnimations[2].effect.updateTiming).toHaveBeenCalledWith({ delay: 300 });
+      // Third group: delay = 50 + 200 = 250, existing delay = 50 → total = 300, endDelay = 200 - 200 = 0
+      expect(mockAnimations[2].effect.updateTiming).toHaveBeenCalledWith({ delay: 300, endDelay: 0 });
     });
 
     test('getOffsetAt should return offset for specific index', () => {

From ddd9eccddc780683402492b5e9340f9ffebdcb25 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Tue, 3 Feb 2026 15:25:40 +0200
Subject: [PATCH 19/29] revert hook changes

---
 apps/demo/src/web/components/SequenceDemo.tsx  | 5 +++--
 apps/demo/src/web/hooks/useInteractInstance.ts | 9 ++-------
 2 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/apps/demo/src/web/components/SequenceDemo.tsx b/apps/demo/src/web/components/SequenceDemo.tsx
index 8dbb92cc..f6213dda 100644
--- a/apps/demo/src/web/components/SequenceDemo.tsx
+++ b/apps/demo/src/web/components/SequenceDemo.tsx
@@ -156,9 +156,10 @@ export const SequenceDemo = () => {
       setParseError((e as Error).message);
       return createConfig('quadOut');
     }
-  }, [configText]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [configText, triggerKey]); // triggerKey forces re-creation of Interact instance
 
-  useInteractInstance(config, triggerKey);
+  useInteractInstance(config);
 
   const handleApply = () => {
     setTriggerKey((prev) => prev + 1);
diff --git a/apps/demo/src/web/hooks/useInteractInstance.ts b/apps/demo/src/web/hooks/useInteractInstance.ts
index f149b36d..f8fa2332 100644
--- a/apps/demo/src/web/hooks/useInteractInstance.ts
+++ b/apps/demo/src/web/hooks/useInteractInstance.ts
@@ -3,18 +3,13 @@ import { Interact, type InteractConfig } from '@wix/interact/web';
 
 export const useInteractInstance = (
   config: InteractConfig,
-  keyOrOptions?: number | { useCutsomElement?: boolean },
   options?: { useCutsomElement?: boolean },
 ) => {
-  // Support both (config, options) and (config, key, options) signatures
-  const key = typeof keyOrOptions === 'number' ? keyOrOptions : undefined;
-  const opts = typeof keyOrOptions === 'object' ? keyOrOptions : options;
-
   useEffect(() => {
-    const instance = Interact.create(config, opts);
+    const instance = Interact.create(config, options);
 
     return () => {
       instance.destroy();
     };
-  }, [config, opts, key]);
+  }, [config, options]);
 };

From 9891a043e4cbd16161efddebb48f34fbd7f4a469 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Tue, 3 Feb 2026 15:26:12 +0200
Subject: [PATCH 20/29] fix format

---
 packages/motion/test/Sequence.spec.ts | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/packages/motion/test/Sequence.spec.ts b/packages/motion/test/Sequence.spec.ts
index ea7055c0..8ede4e8a 100644
--- a/packages/motion/test/Sequence.spec.ts
+++ b/packages/motion/test/Sequence.spec.ts
@@ -223,13 +223,22 @@ describe('Sequence', () => {
       new Sequence(mockAnimationGroups, { delay: 50, offset: 100 });
 
       // First group: delay = 50 + 0 = 50, existing delay = 0 → total = 50, endDelay = 200 - 0 = 200
-      expect(mockAnimations[0].effect.updateTiming).toHaveBeenCalledWith({ delay: 50, endDelay: 200 });
+      expect(mockAnimations[0].effect.updateTiming).toHaveBeenCalledWith({
+        delay: 50,
+        endDelay: 200,
+      });
 
       // Second group: delay = 50 + 100 = 150, existing delay = 100 → total = 250, endDelay = 200 - 100 = 100
-      expect(mockAnimations[1].effect.updateTiming).toHaveBeenCalledWith({ delay: 250, endDelay: 100 });
+      expect(mockAnimations[1].effect.updateTiming).toHaveBeenCalledWith({
+        delay: 250,
+        endDelay: 100,
+      });
 
       // Third group: delay = 50 + 200 = 250, existing delay = 50 → total = 300, endDelay = 200 - 200 = 0
-      expect(mockAnimations[2].effect.updateTiming).toHaveBeenCalledWith({ delay: 300, endDelay: 0 });
+      expect(mockAnimations[2].effect.updateTiming).toHaveBeenCalledWith({
+        delay: 300,
+        endDelay: 0,
+      });
     });
 
     test('getOffsetAt should return offset for specific index', () => {

From 72b607300e6c19e901c3bd4425661c6716517de8 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Tue, 3 Feb 2026 15:30:50 +0200
Subject: [PATCH 21/29] remove unused exports

---
 packages/motion/src/index.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/packages/motion/src/index.ts b/packages/motion/src/index.ts
index febe9b3c..8cb11bba 100644
--- a/packages/motion/src/index.ts
+++ b/packages/motion/src/index.ts
@@ -5,5 +5,3 @@ export { SequenceRegistry } from './api/sequenceRegistry';
 export type { SequenceEffectConfig } from './api/sequenceRegistry';
 export * from './utils';
 export * from './easings';
-export { AnimationGroup } from './AnimationGroup';
-export { Sequence } from './Sequence';

From e36e7a24bfaf03012181b813b1568a737abe1814 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Tue, 3 Feb 2026 15:40:58 +0200
Subject: [PATCH 22/29] no need to resolve effect in parse stage

---
 packages/interact/src/core/Interact.ts | 25 +------------------------
 1 file changed, 1 insertion(+), 24 deletions(-)

diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index d1e0b812..6a979020 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -20,19 +20,6 @@ function _convertToKeyTemplate(key: string) {
   return key.replace(/\[([-\w]+)]/g, '[]');
 }
 
-/** Keys that indicate an effect has its own definition (not just a reference) */
-const EFFECT_DEFINITION_KEYS = [
-  'duration',
-  'namedEffect',
-  'keyframeEffect',
-  'customEffect',
-] as const;
-
-/** Check if an effect is just a reference to another effect (has effectId but no definition) */
-function isEffectReference(effect: Effect | EffectRef): effect is EffectRef {
-  return 'effectId' in effect && !EFFECT_DEFINITION_KEYS.some((key) => key in effect);
-}
-
 export class Interact {
   static defineInteractElement?: () => boolean;
   dataCache: InteractCache;
@@ -271,7 +258,6 @@ function resolveSequence(
 function expandSequenceEffects(
   interaction: Interaction,
   configSequences: Record<string, Sequence>,
-  configEffects: Record<string, Effect>,
 ): (Effect | EffectRef)[] {
   const expandedEffects: (Effect | EffectRef)[] = [];
 
@@ -289,17 +275,9 @@ function expandSequenceEffects(
 
       const totalEffects = sequence.effects.length;
       sequence.effects.forEach((effect, index) => {
-        let resolvedEffect: Effect;
-        if (isEffectReference(effect)) {
-          const referencedEffect = configEffects[effect.effectId];
-          resolvedEffect = referencedEffect ? { ...referencedEffect, ...effect } : effect;
-        } else {
-          resolvedEffect = effect;
-        }
-
         // Mark effect with sequence metadata (delay calculation deferred to Sequence class)
         const effectWithMetadata: Effect | EffectRef = {
-          ...resolvedEffect,
+          ...effect,
           _sequenceId: sequence.sequenceId,
           _sequenceIndex: index,
           _sequenceTotal: totalEffects,
@@ -371,7 +349,6 @@ function parseConfig(config: InteractConfig, useCutsomElement: boolean = false):
     const sequenceEffects = expandSequenceEffects(
       { ...interaction_, sequences: sequences_ } as Interaction,
       sequences,
-      config.effects || {},
     );
 
     /*

From e9fdba43decc215926a026bfea805b8eb788f183 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Sun, 8 Feb 2026 10:54:19 +0200
Subject: [PATCH 23/29] move sequenceCache logic to motion.ts

---
 packages/interact/src/core/Interact.ts      |  6 +-
 packages/interact/src/core/add.ts           |  4 +-
 packages/interact/test/mini.spec.ts         | 10 +--
 packages/interact/test/react.spec.tsx       | 10 +--
 packages/interact/test/viewEnter.spec.ts    | 10 +--
 packages/interact/test/web.spec.ts          | 10 +--
 packages/motion/src/api/sequenceRegistry.ts | 85 ---------------------
 packages/motion/src/index.ts                |  2 -
 packages/motion/src/motion.ts               | 79 +++++++++++++++----
 9 files changed, 77 insertions(+), 139 deletions(-)
 delete mode 100644 packages/motion/src/api/sequenceRegistry.ts

diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index 6a979020..f41b5933 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -14,7 +14,7 @@ import {
 import { getInterpolatedKey } from './utilities';
 import { generateId } from '../utils';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
-import { registerEffects, SequenceRegistry } from '@wix/motion';
+import { registerEffects, clearSequenceCache } from '@wix/motion';
 
 function _convertToKeyTemplate(key: string) {
   return key.replace(/\[([-\w]+)]/g, '[]');
@@ -93,7 +93,7 @@ export class Interact {
     this.listInteractionsCache = {};
     this.controllers.clear();
     this.dataCache = { effects: {}, sequences: {}, conditions: {}, interactions: {} };
-    SequenceRegistry.clear();
+    clearSequenceCache();
     Interact.instances.splice(Interact.instances.indexOf(this), 1);
   }
 
@@ -171,7 +171,7 @@ export class Interact {
     });
     Interact.instances.length = 0;
     Interact.controllerCache.clear();
-    SequenceRegistry.clear();
+    clearSequenceCache();
   }
 
   static setup(options: {
diff --git a/packages/interact/src/core/add.ts b/packages/interact/src/core/add.ts
index 3a225efa..0e058d21 100644
--- a/packages/interact/src/core/add.ts
+++ b/packages/interact/src/core/add.ts
@@ -14,7 +14,7 @@ import { createTransitionCSS, getMediaQuery, getSelectorCondition } from '../uti
 import { getInterpolatedKey } from './utilities';
 import { Interact, getSelector } from './Interact';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
-import { SequenceRegistry } from '@wix/motion';
+import { registerSequenceEffect } from '@wix/motion';
 import { effectToAnimationOptions } from '../handlers/utilities';
 
 type InteractionsToApply = Array<
@@ -255,7 +255,7 @@ function _addInteraction(
     if (sequenceEffect._sequenceId && 'duration' in effect) {
       const targets = Array.isArray(targetElements) ? targetElements : [targetElements];
       targets.forEach((target) => {
-        SequenceRegistry.registerEffect(sequenceEffect._sequenceId!, {
+        registerSequenceEffect(sequenceEffect._sequenceId!, {
           target,
           effectOptions: effectToAnimationOptions(effect as TimeEffect),
           sequenceOptions: sequenceEffect._sequenceOptions || {},
diff --git a/packages/interact/test/mini.spec.ts b/packages/interact/test/mini.spec.ts
index f1d7587b..c9492630 100644
--- a/packages/interact/test/mini.spec.ts
+++ b/packages/interact/test/mini.spec.ts
@@ -30,14 +30,8 @@ vi.mock('@wix/motion', () => {
       });
     }),
     registerEffects: vi.fn(),
-    SequenceRegistry: {
-      configs: new Map(),
-      sequences: new Map(),
-      registerEffect: vi.fn(),
-      getOrCreateSequence: vi.fn(),
-      clear: vi.fn(),
-      clearSequence: vi.fn(),
-    },
+    registerSequenceEffect: vi.fn(),
+    clearSequenceCache: vi.fn(),
   };
 
   return mock;
diff --git a/packages/interact/test/react.spec.tsx b/packages/interact/test/react.spec.tsx
index f995b037..6fe22d68 100644
--- a/packages/interact/test/react.spec.tsx
+++ b/packages/interact/test/react.spec.tsx
@@ -29,14 +29,8 @@ vi.mock('@wix/motion', () => {
       });
     }),
     registerEffects: vi.fn(),
-    SequenceRegistry: {
-      configs: new Map(),
-      sequences: new Map(),
-      registerEffect: vi.fn(),
-      getOrCreateSequence: vi.fn(),
-      clear: vi.fn(),
-      clearSequence: vi.fn(),
-    },
+    registerSequenceEffect: vi.fn(),
+    clearSequenceCache: vi.fn(),
   };
 
   return mock;
diff --git a/packages/interact/test/viewEnter.spec.ts b/packages/interact/test/viewEnter.spec.ts
index d896a9d9..574472b0 100644
--- a/packages/interact/test/viewEnter.spec.ts
+++ b/packages/interact/test/viewEnter.spec.ts
@@ -14,14 +14,8 @@ vi.mock('@wix/motion', () => ({
     ready: Promise.resolve(),
   }),
   registerEffects: vi.fn(),
-  SequenceRegistry: {
-    configs: new Map(),
-    sequences: new Map(),
-    registerEffect: vi.fn(),
-    getOrCreateSequence: vi.fn(),
-    clear: vi.fn(),
-    clearSequence: vi.fn(),
-  },
+  registerSequenceEffect: vi.fn(),
+  clearSequenceCache: vi.fn(),
 }));
 
 vi.mock('fastdom', () => ({
diff --git a/packages/interact/test/web.spec.ts b/packages/interact/test/web.spec.ts
index a0b5bf4a..41d33064 100644
--- a/packages/interact/test/web.spec.ts
+++ b/packages/interact/test/web.spec.ts
@@ -30,14 +30,8 @@ vi.mock('@wix/motion', () => {
       });
     }),
     registerEffects: vi.fn(),
-    SequenceRegistry: {
-      configs: new Map(),
-      sequences: new Map(),
-      registerEffect: vi.fn(),
-      getOrCreateSequence: vi.fn(),
-      clear: vi.fn(),
-      clearSequence: vi.fn(),
-    },
+    registerSequenceEffect: vi.fn(),
+    clearSequenceCache: vi.fn(),
   };
 
   return mock;
diff --git a/packages/motion/src/api/sequenceRegistry.ts b/packages/motion/src/api/sequenceRegistry.ts
deleted file mode 100644
index b08fb6fc..00000000
--- a/packages/motion/src/api/sequenceRegistry.ts
+++ /dev/null
@@ -1,85 +0,0 @@
-import type { AnimationGroup } from '../AnimationGroup';
-import type { SequenceOptions } from '../types';
-import { Sequence } from '../Sequence';
-
-export type SequenceEffectConfig = {
-  target: HTMLElement;
-  effectOptions: Record<string, unknown>;
-  sequenceOptions: SequenceOptions;
-  index: number;
-  total: number;
-};
-
-type GetAnimationFn = (
-  target: HTMLElement,
-  options: Record<string, unknown>,
-  trigger?: undefined,
-  reducedMotion?: boolean,
-) => AnimationGroup | null;
-
-let getAnimationFn: GetAnimationFn | null = null;
-
-export const SequenceRegistry = {
-  configs: new Map<string, SequenceEffectConfig[]>(),
-  sequences: new Map<string, Sequence>(),
-
-  setGetAnimationFn(fn: GetAnimationFn) {
-    getAnimationFn = fn;
-  },
-
-  registerEffect(sequenceId: string, config: SequenceEffectConfig) {
-    // Clear cached sequence if re-registering (replay scenario)
-    if (this.sequences.has(sequenceId)) {
-      this.sequences.delete(sequenceId);
-      this.configs.delete(sequenceId);
-    }
-
-    const list = this.configs.get(sequenceId) || [];
-    list.push(config);
-    this.configs.set(sequenceId, list);
-  },
-
-  getOrCreateSequence(sequenceId: string, reducedMotion?: boolean): Sequence | null {
-    if (this.sequences.has(sequenceId)) {
-      return this.sequences.get(sequenceId)!;
-    }
-
-    const configs = this.configs.get(sequenceId);
-    if (!configs?.length || !getAnimationFn) return null;
-
-    // Check if all effects have been registered
-    const expectedTotal = configs[0].total;
-    if (configs.length < expectedTotal) {
-      return null; // Not all effects registered yet
-    }
-
-    // Sort by index to ensure correct order
-    configs.sort((a, b) => a.index - b.index);
-
-    // Create all AnimationGroups
-    const groups: AnimationGroup[] = [];
-    for (const cfg of configs) {
-      const animation = getAnimationFn(cfg.target, cfg.effectOptions, undefined, reducedMotion);
-      if (animation) {
-        groups.push(animation);
-      }
-    }
-
-    if (!groups.length) return null;
-
-    // Create Sequence (applies delays internally)
-    const sequence = new Sequence(groups, configs[0].sequenceOptions);
-    this.sequences.set(sequenceId, sequence);
-    return sequence;
-  },
-
-  clear() {
-    this.configs.clear();
-    this.sequences.clear();
-  },
-
-  clearSequence(sequenceId: string) {
-    this.configs.delete(sequenceId);
-    this.sequences.delete(sequenceId);
-  },
-};
diff --git a/packages/motion/src/index.ts b/packages/motion/src/index.ts
index 8cb11bba..29ac5116 100644
--- a/packages/motion/src/index.ts
+++ b/packages/motion/src/index.ts
@@ -1,7 +1,5 @@
 export * from './motion';
 export * from './types';
 export { registerEffects } from './api/registry';
-export { SequenceRegistry } from './api/sequenceRegistry';
-export type { SequenceEffectConfig } from './api/sequenceRegistry';
 export * from './utils';
 export * from './easings';
diff --git a/packages/motion/src/motion.ts b/packages/motion/src/motion.ts
index f35edd37..f92275fc 100644
--- a/packages/motion/src/motion.ts
+++ b/packages/motion/src/motion.ts
@@ -8,14 +8,51 @@ import type {
   ScrubScrollScene,
   ScrubPointerScene,
   PointerMoveAxis,
+  SequenceOptions,
 } from './types';
 import { AnimationGroup } from './AnimationGroup';
+import { Sequence } from './Sequence';
 import { getEasing, getJsEasing } from './utils';
 import { getWebAnimation } from './api/webAnimations';
 import { getCSSAnimation } from './api/cssAnimations';
 import { prepareAnimation } from './api/prepare';
 import { getElement, getNamedEffect } from './api/common';
 
+// Sequence config and cache
+export type SequenceEffectConfig = {
+  target: HTMLElement;
+  effectOptions: Record<string, unknown>;
+  sequenceOptions: SequenceOptions;
+  index: number;
+  total: number;
+};
+
+const sequenceConfigs = new Map<string, SequenceEffectConfig[]>();
+const sequenceCache = new Map<string, Sequence>();
+
+export function registerSequenceEffect(
+  sequenceId: string,
+  config: SequenceEffectConfig,
+): void {
+  if (sequenceCache.has(sequenceId)) {
+    sequenceCache.delete(sequenceId);
+    sequenceConfigs.delete(sequenceId);
+  }
+  const list = sequenceConfigs.get(sequenceId) || [];
+  list.push(config);
+  sequenceConfigs.set(sequenceId, list);
+}
+
+export function clearSequenceCache(sequenceId?: string): void {
+  if (sequenceId) {
+    sequenceConfigs.delete(sequenceId);
+    sequenceCache.delete(sequenceId);
+  } else {
+    sequenceConfigs.clear();
+    sequenceCache.clear();
+  }
+}
+
 function getElementCSSAnimation(
   target: HTMLElement | string | null,
   animationOptions: AnimationOptions,
@@ -192,9 +229,7 @@ function getScrubScene(
   } as ScrubPointerScene;
 }
 
-import { SequenceRegistry } from './api/sequenceRegistry';
-
-// Internal function for creating individual animations (used by registry)
+// Internal function for creating individual animations
 function _createAnimation(
   target: HTMLElement | string | null,
   animationOptions: AnimationOptions,
@@ -214,15 +249,31 @@ function _createAnimation(
   return getWebAnimation(target, animationOptions, trigger, { reducedMotion });
 }
 
-// Set up registry with animation creation function
-SequenceRegistry.setGetAnimationFn((target, options, trigger, reducedMotion) => {
-  return _createAnimation(
-    target,
-    options as AnimationOptions,
-    trigger,
-    reducedMotion,
-  ) as AnimationGroup | null;
-});
+function _getOrCreateSequence(sequenceId: string, reducedMotion: boolean): Sequence | null {
+  if (sequenceCache.has(sequenceId)) return sequenceCache.get(sequenceId)!;
+
+  const configs = sequenceConfigs.get(sequenceId);
+  if (!configs?.length || configs.length < configs[0].total) return null;
+
+  configs.sort((a, b) => a.index - b.index);
+
+  const groups = configs
+    .map((cfg) =>
+      _createAnimation(
+        cfg.target,
+        cfg.effectOptions as AnimationOptions,
+        undefined,
+        reducedMotion,
+      ),
+    )
+    .filter((a): a is AnimationGroup => a instanceof AnimationGroup);
+
+  if (!groups.length) return null;
+
+  const sequence = new Sequence(groups, configs[0].sequenceOptions);
+  sequenceCache.set(sequenceId, sequence);
+  return sequence;
+}
 
 function getAnimation(
   target: HTMLElement | string | null,
@@ -230,12 +281,10 @@ function getAnimation(
   trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
   reducedMotion: boolean = false,
 ): AnimationGroup | MouseAnimationInstance | null {
-  // Check if this is a sequence effect
   const sequenceId = (animationOptions as AnimationOptions & { _sequenceId?: string })._sequenceId;
   if (sequenceId) {
-    return SequenceRegistry.getOrCreateSequence(sequenceId, reducedMotion);
+    return _getOrCreateSequence(sequenceId, reducedMotion);
   }
-
   return _createAnimation(target, animationOptions, trigger, reducedMotion);
 }
 

From 521a1533ef4c3fd064dac94112a8ba566fdc722b Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Sun, 8 Feb 2026 11:14:00 +0200
Subject: [PATCH 24/29] format

---
 packages/motion/src/motion.ts | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/packages/motion/src/motion.ts b/packages/motion/src/motion.ts
index f92275fc..c83f2520 100644
--- a/packages/motion/src/motion.ts
+++ b/packages/motion/src/motion.ts
@@ -30,10 +30,7 @@ export type SequenceEffectConfig = {
 const sequenceConfigs = new Map<string, SequenceEffectConfig[]>();
 const sequenceCache = new Map<string, Sequence>();
 
-export function registerSequenceEffect(
-  sequenceId: string,
-  config: SequenceEffectConfig,
-): void {
+export function registerSequenceEffect(sequenceId: string, config: SequenceEffectConfig): void {
   if (sequenceCache.has(sequenceId)) {
     sequenceCache.delete(sequenceId);
     sequenceConfigs.delete(sequenceId);
@@ -259,12 +256,7 @@ function _getOrCreateSequence(sequenceId: string, reducedMotion: boolean): Seque
 
   const groups = configs
     .map((cfg) =>
-      _createAnimation(
-        cfg.target,
-        cfg.effectOptions as AnimationOptions,
-        undefined,
-        reducedMotion,
-      ),
+      _createAnimation(cfg.target, cfg.effectOptions as AnimationOptions, undefined, reducedMotion),
     )
     .filter((a): a is AnimationGroup => a instanceof AnimationGroup);
 

From d4e65722b89b1c9167544911137d70bd6e66c727 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Sun, 8 Feb 2026 11:23:11 +0200
Subject: [PATCH 25/29] rename group delay function

---
 packages/motion/src/AnimationGroup.ts | 2 +-
 packages/motion/src/Sequence.ts       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/motion/src/AnimationGroup.ts b/packages/motion/src/AnimationGroup.ts
index b56901c0..8ddd7888 100644
--- a/packages/motion/src/AnimationGroup.ts
+++ b/packages/motion/src/AnimationGroup.ts
@@ -22,7 +22,7 @@ export class AnimationGroup {
     this.isCSS = animations[0] instanceof CSSAnimation;
   }
 
-  applyGroupDelay(delay: number, endDelay?: number) {
+  addGroupDelay(delay: number, endDelay?: number) {
     for (const animation of this.animations) {
       const timing = animation.effect?.getTiming();
       if (timing) {
diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index af933a51..a799ea46 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -36,7 +36,7 @@ export class Sequence extends AnimationGroup {
         minOffset < 0 ? this._calculatedOffsets[index] - minOffset : this._calculatedOffsets[index];
       const groupDelay = this.sequenceDelay + normalizedOffset;
       const endDelay = totalSpan - normalizedOffset;
-      group.applyGroupDelay(groupDelay, endDelay);
+      group.addGroupDelay(groupDelay, endDelay);
     });
   }
 

From 3d6b99204462a4a5d5359f83300a7c11a4106e1a Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Mon, 9 Feb 2026 04:41:45 +0200
Subject: [PATCH 26/29] move sequence state to interact

---
 packages/interact/src/core/Interact.ts        |   8 +-
 packages/interact/src/core/add.ts             | 120 +++++++++++++-----
 .../interact/src/handlers/animationEnd.ts     |   5 +-
 packages/interact/src/handlers/click.ts       |  18 ++-
 packages/interact/src/handlers/hover.ts       |  18 ++-
 packages/interact/src/handlers/viewEnter.ts   |  10 +-
 packages/interact/src/types.ts                |  24 ++++
 packages/interact/test/mini.spec.ts           |   3 +-
 packages/interact/test/react.spec.tsx         |   3 +-
 packages/interact/test/viewEnter.spec.ts      | 120 ++++++------------
 packages/interact/test/web.spec.ts            |   3 +-
 packages/motion/src/index.ts                  |   2 +
 packages/motion/src/motion.ts                 |  71 +----------
 13 files changed, 197 insertions(+), 208 deletions(-)

diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index f41b5933..5c842a0b 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -14,7 +14,8 @@ import {
 import { getInterpolatedKey } from './utilities';
 import { generateId } from '../utils';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
-import { registerEffects, clearSequenceCache } from '@wix/motion';
+import type { Sequence as MotionSequence } from '@wix/motion';
+import { registerEffects } from '@wix/motion';
 
 function _convertToKeyTemplate(key: string) {
   return key.replace(/\[([-\w]+)]/g, '[]');
@@ -36,6 +37,7 @@ export class Interact {
     [listContainer: string]: { [interactionId: string]: boolean };
   };
   controllers: Set<IInteractionController>;
+  sequenceCache: Map<string, MotionSequence> = new Map();
   static forceReducedMotion: boolean = false;
   static allowA11yTriggers: boolean = true;
   static instances: Interact[] = [];
@@ -92,8 +94,8 @@ export class Interact {
     this.addedInteractions = {};
     this.listInteractionsCache = {};
     this.controllers.clear();
+    this.sequenceCache.clear();
     this.dataCache = { effects: {}, sequences: {}, conditions: {}, interactions: {} };
-    clearSequenceCache();
     Interact.instances.splice(Interact.instances.indexOf(this), 1);
   }
 
@@ -169,9 +171,9 @@ export class Interact {
     Interact.controllerCache.forEach((controller: IInteractionController) => {
       controller.disconnect();
     });
+    Interact.instances.forEach((instance) => instance.sequenceCache.clear());
     Interact.instances.length = 0;
     Interact.controllerCache.clear();
-    clearSequenceCache();
   }
 
   static setup(options: {
diff --git a/packages/interact/src/core/add.ts b/packages/interact/src/core/add.ts
index 0e058d21..369fec65 100644
--- a/packages/interact/src/core/add.ts
+++ b/packages/interact/src/core/add.ts
@@ -8,15 +8,88 @@ import type {
   InteractionTrigger,
   CreateTransitionCSSParams,
   IInteractionController,
-  TimeEffect,
+  GetAnimationFn,
 } from '../types';
+import { isSequenceEffect } from '../types';
 import { createTransitionCSS, getMediaQuery, getSelectorCondition } from '../utils';
 import { getInterpolatedKey } from './utilities';
 import { Interact, getSelector } from './Interact';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
-import { registerSequenceEffect } from '@wix/motion';
+import { getAnimation, Sequence as MotionSequence, AnimationGroup } from '@wix/motion';
+import type { AnimationOptions, TriggerVariant } from '@wix/motion';
 import { effectToAnimationOptions } from '../handlers/utilities';
 
+export function createGetAnimation(sequenceCache: Map<string, MotionSequence>) {
+  return (
+    target: HTMLElement | string | null,
+    animationOptions: AnimationOptions & { _sequenceId?: string },
+    trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
+    reducedMotion: boolean = false,
+  ) => {
+    const sequenceId = animationOptions._sequenceId;
+    if (sequenceId) {
+      return sequenceCache.get(sequenceId) ?? null;
+    }
+    return getAnimation(target, animationOptions, trigger, reducedMotion);
+  };
+}
+
+function buildSequences(
+  interactionsToApply: InteractionsToApply,
+  sequenceCache: Map<string, MotionSequence>,
+  reducedMotion: boolean,
+) {
+  const sequenceGroups = new Map<
+    string,
+    {
+      configs: Array<{
+        target: HTMLElement;
+        effectOptions: Record<string, unknown>;
+        index: number;
+      }>;
+      sequenceOptions: {
+        delay?: number;
+        offset?: number;
+        offsetEasing?: string | ((t: number) => number);
+      };
+    }
+  >();
+
+  for (const [, , effect, , targetElements] of interactionsToApply) {
+    if (!isSequenceEffect(effect)) continue;
+
+    const sequenceId = effect._sequenceId;
+    if (!sequenceGroups.has(sequenceId)) {
+      sequenceGroups.set(sequenceId, {
+        configs: [],
+        sequenceOptions: effect._sequenceOptions || {},
+      });
+    }
+    const group = sequenceGroups.get(sequenceId)!;
+    const targets = Array.isArray(targetElements) ? targetElements : [targetElements];
+    for (const target of targets) {
+      group.configs.push({
+        target,
+        effectOptions: effectToAnimationOptions(effect),
+        index: effect._sequenceIndex,
+      });
+    }
+  }
+
+  for (const [sequenceId, { configs, sequenceOptions }] of sequenceGroups) {
+    sequenceCache.delete(sequenceId);
+    configs.sort((a, b) => a.index - b.index);
+    const groups = configs
+      .map((cfg) =>
+        getAnimation(cfg.target, cfg.effectOptions as AnimationOptions, undefined, reducedMotion),
+      )
+      .filter((a): a is AnimationGroup => a instanceof AnimationGroup);
+    if (groups.length) {
+      sequenceCache.set(sequenceId, new MotionSequence(groups, sequenceOptions));
+    }
+  }
+}
+
 type InteractionsToApply = Array<
   [
     string,
@@ -99,8 +172,9 @@ function _applyInteraction(
   effect: Effect,
   sourceElements: HTMLElement | HTMLElement[],
   targetElements: HTMLElement | HTMLElement[],
-  selectorCondition?: string,
-  useFirstChild?: boolean,
+  selectorCondition: string | undefined,
+  useFirstChild: boolean,
+  getAnimationFn: GetAnimationFn,
 ) {
   const isSourceArray = Array.isArray(sourceElements);
   const isTargetArray = Array.isArray(targetElements);
@@ -117,6 +191,7 @@ function _applyInteraction(
           targetEl,
           effect as Effect,
           interaction.params!,
+          getAnimationFn,
           selectorCondition,
           useFirstChild,
         );
@@ -132,6 +207,7 @@ function _applyInteraction(
         targetEl,
         effect as Effect,
         interaction.params!,
+        getAnimationFn,
         selectorCondition,
         useFirstChild,
       );
@@ -239,36 +315,12 @@ function _addInteraction(
   // apply the effects in reverse to return to the order specified by the user to ensure order of composition is as defined
   interactionsToApply.reverse();
 
-  // First pass: Register all sequence effects before calling handlers
-  // This ensures the full Sequence can be created when handlers request it
-  interactionsToApply.forEach(([, , effect, , targetElements]) => {
-    const sequenceEffect = effect as Effect & {
-      _sequenceId?: string;
-      _sequenceIndex?: number;
-      _sequenceTotal?: number;
-      _sequenceOptions?: {
-        delay?: number;
-        offset?: number;
-        offsetEasing?: string | ((t: number) => number);
-      };
-    };
-    if (sequenceEffect._sequenceId && 'duration' in effect) {
-      const targets = Array.isArray(targetElements) ? targetElements : [targetElements];
-      targets.forEach((target) => {
-        registerSequenceEffect(sequenceEffect._sequenceId!, {
-          target,
-          effectOptions: effectToAnimationOptions(effect as TimeEffect),
-          sequenceOptions: sequenceEffect._sequenceOptions || {},
-          index: sequenceEffect._sequenceIndex ?? 0,
-          total: sequenceEffect._sequenceTotal ?? 1,
-        });
-      });
-    }
-  });
+  // Build MotionSequences eagerly before calling handlers
+  buildSequences(interactionsToApply, instance.sequenceCache, Interact.forceReducedMotion);
 
-  // Second pass: Apply all interactions (handlers will now get fully-created Sequences)
+  const getAnimationFn = createGetAnimation(instance.sequenceCache) as GetAnimationFn;
   interactionsToApply.forEach((interaction) => {
-    _applyInteraction(...interaction);
+    _applyInteraction(...interaction, getAnimationFn);
   });
 }
 
@@ -373,7 +425,7 @@ function addEffectsForTarget(
 
   // apply the effects in reverse to return to the order specified by the user to ensure order of composition is as defined
   interactionsToApply.reverse().forEach((interaction) => {
-    _applyInteraction(...interaction);
+    _applyInteraction(...interaction, getAnimation as GetAnimationFn);
   });
 
   return interactionIds.length > 0;
@@ -389,6 +441,7 @@ function addInteraction<T extends TriggerType>(
   target: HTMLElement,
   effect: Effect,
   options: InteractionParamsTypes[T],
+  getAnimation: GetAnimationFn,
   selectorCondition?: string,
   useFirstChild?: boolean,
 ): void {
@@ -424,6 +477,7 @@ function addInteraction<T extends TriggerType>(
     targetController,
     selectorCondition,
     allowA11yTriggers: Interact.allowA11yTriggers,
+    getAnimation,
   });
 }
 
diff --git a/packages/interact/src/handlers/animationEnd.ts b/packages/interact/src/handlers/animationEnd.ts
index 9d50d2d7..97bc4997 100644
--- a/packages/interact/src/handlers/animationEnd.ts
+++ b/packages/interact/src/handlers/animationEnd.ts
@@ -1,5 +1,4 @@
 import type { AnimationGroup } from '@wix/motion';
-import { getAnimation } from '@wix/motion';
 import type { AnimationEndParams, TimeEffect, HandlerObjectMap, InteractOptions } from '../types';
 import {
   effectToAnimationOptions,
@@ -14,8 +13,10 @@ function addAnimationEndHandler(
   target: HTMLElement,
   effect: TimeEffect,
   __: AnimationEndParams,
-  { reducedMotion, selectorCondition }: InteractOptions,
+  { reducedMotion, selectorCondition, getAnimation }: InteractOptions,
 ): void {
+  if (!getAnimation) return;
+
   const animation = getAnimation(
     target,
     effectToAnimationOptions(effect),
diff --git a/packages/interact/src/handlers/click.ts b/packages/interact/src/handlers/click.ts
index 997aef90..e04e2e49 100644
--- a/packages/interact/src/handlers/click.ts
+++ b/packages/interact/src/handlers/click.ts
@@ -1,4 +1,3 @@
-import { getAnimation } from '@wix/motion';
 import type { AnimationGroup } from '@wix/motion';
 import type {
   TimeEffect,
@@ -9,7 +8,9 @@ import type {
   EffectBase,
   IInteractionController,
   InteractOptions,
+  GetAnimationFn,
 } from '../types';
+import { isSequenceEffect } from '../types';
 import {
   effectToAnimationOptions,
   addHandlerToMap,
@@ -22,13 +23,12 @@ function createTimeEffectHandler(
   element: HTMLElement,
   effect: TimeEffect & EffectBase,
   options: PointerTriggerParams,
+  getAnimation: GetAnimationFn,
   reducedMotion: boolean = false,
   selectorCondition?: string,
 ) {
   // For sequence effects, only the first effect (index 0) controls playback
-  const sequenceIndex = (effect as any)._sequenceIndex;
-  const isSequenceEffect = sequenceIndex !== undefined;
-  if (isSequenceEffect && sequenceIndex !== 0) {
+  if (isSequenceEffect(effect) && effect._sequenceIndex !== 0) {
     // Non-leader sequence effects don't need handlers - the leader controls the Sequence
     return () => {};
   }
@@ -116,7 +116,13 @@ function addClickHandler(
   target: HTMLElement,
   effect: (TimeEffect | TransitionEffect) & EffectBase,
   options: StateParams | PointerTriggerParams = {} as StateParams,
-  { reducedMotion, targetController, selectorCondition, allowA11yTriggers }: InteractOptions,
+  {
+    reducedMotion,
+    targetController,
+    selectorCondition,
+    allowA11yTriggers,
+    getAnimation,
+  }: InteractOptions,
 ) {
   let handler: ((event: MouseEvent | KeyboardEvent) => void) | null;
   let once = false;
@@ -133,10 +139,12 @@ function addClickHandler(
       selectorCondition,
     );
   } else {
+    if (!getAnimation) return;
     handler = createTimeEffectHandler(
       target,
       effect as TimeEffect & EffectBase,
       options as PointerTriggerParams,
+      getAnimation,
       reducedMotion,
       selectorCondition,
     );
diff --git a/packages/interact/src/handlers/hover.ts b/packages/interact/src/handlers/hover.ts
index b9e9a997..b0aaf0e2 100644
--- a/packages/interact/src/handlers/hover.ts
+++ b/packages/interact/src/handlers/hover.ts
@@ -1,5 +1,4 @@
 import type { AnimationGroup } from '@wix/motion';
-import { getAnimation } from '@wix/motion';
 import type {
   TimeEffect,
   TransitionEffect,
@@ -9,7 +8,9 @@ import type {
   EffectBase,
   IInteractionController,
   InteractOptions,
+  GetAnimationFn,
 } from '../types';
+import { isSequenceEffect } from '../types';
 import {
   effectToAnimationOptions,
   addHandlerToMap,
@@ -22,13 +23,12 @@ function createTimeEffectHandler(
   element: HTMLElement,
   effect: TimeEffect & EffectBase,
   options: PointerTriggerParams,
+  getAnimation: GetAnimationFn,
   reducedMotion: boolean = false,
   selectorCondition?: string,
 ) {
   // For sequence effects, only the first effect (index 0) controls playback
-  const sequenceIndex = (effect as any)._sequenceIndex;
-  const isSequenceEffect = sequenceIndex !== undefined;
-  if (isSequenceEffect && sequenceIndex !== 0) {
+  if (isSequenceEffect(effect) && effect._sequenceIndex !== 0) {
     // Non-leader sequence effects don't need handlers - the leader controls the Sequence
     return () => {};
   }
@@ -129,7 +129,13 @@ function addHoverHandler(
   target: HTMLElement,
   effect: (TransitionEffect | TimeEffect) & EffectBase,
   options: StateParams | PointerTriggerParams = {},
-  { reducedMotion, targetController, selectorCondition, allowA11yTriggers }: InteractOptions,
+  {
+    reducedMotion,
+    targetController,
+    selectorCondition,
+    allowA11yTriggers,
+    getAnimation,
+  }: InteractOptions,
 ) {
   let handler: ((event: MouseEvent | FocusEvent) => void) | null;
   let isStateTrigger = false;
@@ -148,10 +154,12 @@ function addHoverHandler(
     );
     isStateTrigger = true;
   } else {
+    if (!getAnimation) return;
     handler = createTimeEffectHandler(
       target,
       effect as TimeEffect & EffectBase,
       options as PointerTriggerParams,
+      getAnimation,
       reducedMotion,
       selectorCondition,
     );
diff --git a/packages/interact/src/handlers/viewEnter.ts b/packages/interact/src/handlers/viewEnter.ts
index d946bb6b..76c87d41 100644
--- a/packages/interact/src/handlers/viewEnter.ts
+++ b/packages/interact/src/handlers/viewEnter.ts
@@ -1,6 +1,6 @@
 import type { AnimationGroup } from '@wix/motion';
-import { getAnimation } from '@wix/motion';
 import type { TimeEffect, HandlerObjectMap, ViewEnterParams, InteractOptions } from '../types';
+import { isSequenceEffect } from '../types';
 import {
   effectToAnimationOptions,
   addHandlerToMap,
@@ -137,16 +137,16 @@ function addViewEnterHandler(
   target: HTMLElement,
   effect: TimeEffect,
   options: ViewEnterParams = {},
-  { reducedMotion, selectorCondition }: InteractOptions = {},
+  { reducedMotion, selectorCondition, getAnimation }: InteractOptions = {},
 ) {
   // For sequence effects, only the first effect (index 0) controls playback
-  const sequenceIndex = (effect as any)._sequenceIndex;
-  const isSequenceEffect = sequenceIndex !== undefined;
-  if (isSequenceEffect && sequenceIndex !== 0) {
+  if (isSequenceEffect(effect) && effect._sequenceIndex !== 0) {
     // Non-leader sequence effects don't need handlers - the leader controls the Sequence
     return;
   }
 
+  if (!getAnimation) return;
+
   const mergedOptions = { ...viewEnterOptions, ...options };
   const type = mergedOptions.type || 'once';
   const animation = getAnimation(
diff --git a/packages/interact/src/types.ts b/packages/interact/src/types.ts
index 6d96eebf..31199196 100644
--- a/packages/interact/src/types.ts
+++ b/packages/interact/src/types.ts
@@ -241,11 +241,35 @@ export type InteractionParamsTypes = {
   interest: StateParams | PointerTriggerParams;
 };
 
+export type SequenceEffect = TimeEffect &
+  EffectBase & {
+    _sequenceId: string;
+    _sequenceIndex: number;
+    _sequenceTotal: number;
+    _sequenceOptions?: {
+      delay?: number;
+      offset?: number;
+      offsetEasing?: string | ((t: number) => number);
+    };
+  };
+
+export function isSequenceEffect(effect: Effect): effect is SequenceEffect {
+  return '_sequenceId' in effect && 'duration' in effect;
+}
+
+export type GetAnimationFn = (
+  target: HTMLElement | string | null,
+  animationOptions: Record<string, unknown>,
+  trigger?: unknown,
+  reducedMotion?: boolean,
+) => unknown;
+
 export type InteractOptions = {
   reducedMotion?: boolean;
   targetController?: IInteractionController;
   selectorCondition?: string;
   allowA11yTriggers?: boolean;
+  getAnimation?: GetAnimationFn;
 };
 
 export type InteractionHandlerModule<T extends TriggerType> = {
diff --git a/packages/interact/test/mini.spec.ts b/packages/interact/test/mini.spec.ts
index c9492630..462580d2 100644
--- a/packages/interact/test/mini.spec.ts
+++ b/packages/interact/test/mini.spec.ts
@@ -29,9 +29,8 @@ vi.mock('@wix/motion', () => {
         reducedMotion,
       });
     }),
+    Sequence: vi.fn(),
     registerEffects: vi.fn(),
-    registerSequenceEffect: vi.fn(),
-    clearSequenceCache: vi.fn(),
   };
 
   return mock;
diff --git a/packages/interact/test/react.spec.tsx b/packages/interact/test/react.spec.tsx
index 6fe22d68..e416f63f 100644
--- a/packages/interact/test/react.spec.tsx
+++ b/packages/interact/test/react.spec.tsx
@@ -28,9 +28,8 @@ vi.mock('@wix/motion', () => {
         reducedMotion,
       });
     }),
+    Sequence: vi.fn(),
     registerEffects: vi.fn(),
-    registerSequenceEffect: vi.fn(),
-    clearSequenceCache: vi.fn(),
   };
 
   return mock;
diff --git a/packages/interact/test/viewEnter.spec.ts b/packages/interact/test/viewEnter.spec.ts
index 574472b0..59bb69dd 100644
--- a/packages/interact/test/viewEnter.spec.ts
+++ b/packages/interact/test/viewEnter.spec.ts
@@ -1,21 +1,24 @@
 import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest';
 
+const mockAnimation = {
+  play: vi.fn(),
+  cancel: vi.fn(),
+  onFinish: vi.fn(),
+  pause: vi.fn(),
+  reverse: vi.fn(),
+  progress: vi.fn(),
+  persist: vi.fn(),
+  isCSS: false,
+  playState: 'idle',
+  ready: Promise.resolve(),
+};
+
+const mockGetAnimation = vi.fn().mockReturnValue(mockAnimation);
+
 vi.mock('@wix/motion', () => ({
-  getAnimation: vi.fn().mockReturnValue({
-    play: vi.fn(),
-    cancel: vi.fn(),
-    onFinish: vi.fn(),
-    pause: vi.fn(),
-    reverse: vi.fn(),
-    progress: vi.fn(),
-    persist: vi.fn(),
-    isCSS: false,
-    playState: 'idle',
-    ready: Promise.resolve(),
-  }),
+  getAnimation: vi.fn(),
+  Sequence: vi.fn(),
   registerEffects: vi.fn(),
-  registerSequenceEffect: vi.fn(),
-  clearSequenceCache: vi.fn(),
 }));
 
 vi.mock('fastdom', () => ({
@@ -54,6 +57,7 @@ describe('viewEnter handler', () => {
     document.body.appendChild(target);
 
     vi.clearAllMocks();
+    mockGetAnimation.mockReturnValue(mockAnimation);
 
     observeSpy = vi.fn();
     unobserveSpy = vi.fn();
@@ -108,7 +112,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         {},
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       expect(IntersectionObserverMock).toHaveBeenCalled();
@@ -121,7 +125,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'once' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry();
@@ -138,7 +142,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: true, threshold: 0.5 },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({
@@ -161,7 +165,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: true, threshold },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({
@@ -192,7 +196,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: true, threshold },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({
@@ -219,7 +223,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: false, threshold },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({
@@ -236,15 +240,12 @@ describe('viewEnter handler', () => {
 
   describe('Alternate type', () => {
     it('should play animation on first entry', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -254,15 +255,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should reverse animation on exit', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       // First entry
@@ -279,15 +277,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should reverse animation on subsequent re-entry', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       // First entry
@@ -312,7 +307,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -322,15 +317,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should persist the animation', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       expect(mockAnimation.persist).toHaveBeenCalled();
@@ -339,15 +331,12 @@ describe('viewEnter handler', () => {
 
   describe('Repeat type', () => {
     it('should play animation from 0 on entry', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -358,15 +347,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should pause and reset progress to 0 on exit', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       // First entry
@@ -385,15 +371,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should play from 0 on subsequent re-entry', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       // First entry
@@ -420,7 +403,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -430,15 +413,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should persist the animation', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       expect(mockAnimation.persist).toHaveBeenCalled();
@@ -447,15 +427,12 @@ describe('viewEnter handler', () => {
 
   describe('State type', () => {
     it('should play animation on first entry', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -465,15 +442,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should pause animation on exit', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       // First entry
@@ -490,15 +464,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should resume animation on subsequent re-entry', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       // First entry
@@ -518,15 +489,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should NOT reset progress on re-entry', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       // First entry
@@ -552,7 +520,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -562,15 +530,12 @@ describe('viewEnter handler', () => {
     });
 
     it('should persist the animation', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      const mockAnimation = (getAnimation as any)();
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        {},
+        { getAnimation: mockGetAnimation },
       );
 
       expect(mockAnimation.persist).toHaveBeenCalled();
@@ -579,15 +544,12 @@ describe('viewEnter handler', () => {
 
   describe('Null animation handling', () => {
     it('should not create IntersectionObserver when animation is null', async () => {
-      const { getAnimation } = await import('@wix/motion');
-      (getAnimation as any).mockReturnValueOnce(null);
-
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'NonExistentEffect' } },
         {},
-        {},
+        { getAnimation: () => null },
       );
 
       // IntersectionObserver should not be created when animation is null
diff --git a/packages/interact/test/web.spec.ts b/packages/interact/test/web.spec.ts
index 41d33064..c37e73ce 100644
--- a/packages/interact/test/web.spec.ts
+++ b/packages/interact/test/web.spec.ts
@@ -29,9 +29,8 @@ vi.mock('@wix/motion', () => {
         reducedMotion,
       });
     }),
+    Sequence: vi.fn(),
     registerEffects: vi.fn(),
-    registerSequenceEffect: vi.fn(),
-    clearSequenceCache: vi.fn(),
   };
 
   return mock;
diff --git a/packages/motion/src/index.ts b/packages/motion/src/index.ts
index 29ac5116..26de44a9 100644
--- a/packages/motion/src/index.ts
+++ b/packages/motion/src/index.ts
@@ -3,3 +3,5 @@ export * from './types';
 export { registerEffects } from './api/registry';
 export * from './utils';
 export * from './easings';
+export { AnimationGroup } from './AnimationGroup';
+export { Sequence } from './Sequence';
diff --git a/packages/motion/src/motion.ts b/packages/motion/src/motion.ts
index c83f2520..be14ef08 100644
--- a/packages/motion/src/motion.ts
+++ b/packages/motion/src/motion.ts
@@ -8,48 +8,14 @@ import type {
   ScrubScrollScene,
   ScrubPointerScene,
   PointerMoveAxis,
-  SequenceOptions,
 } from './types';
 import { AnimationGroup } from './AnimationGroup';
-import { Sequence } from './Sequence';
 import { getEasing, getJsEasing } from './utils';
 import { getWebAnimation } from './api/webAnimations';
 import { getCSSAnimation } from './api/cssAnimations';
 import { prepareAnimation } from './api/prepare';
 import { getElement, getNamedEffect } from './api/common';
 
-// Sequence config and cache
-export type SequenceEffectConfig = {
-  target: HTMLElement;
-  effectOptions: Record<string, unknown>;
-  sequenceOptions: SequenceOptions;
-  index: number;
-  total: number;
-};
-
-const sequenceConfigs = new Map<string, SequenceEffectConfig[]>();
-const sequenceCache = new Map<string, Sequence>();
-
-export function registerSequenceEffect(sequenceId: string, config: SequenceEffectConfig): void {
-  if (sequenceCache.has(sequenceId)) {
-    sequenceCache.delete(sequenceId);
-    sequenceConfigs.delete(sequenceId);
-  }
-  const list = sequenceConfigs.get(sequenceId) || [];
-  list.push(config);
-  sequenceConfigs.set(sequenceId, list);
-}
-
-export function clearSequenceCache(sequenceId?: string): void {
-  if (sequenceId) {
-    sequenceConfigs.delete(sequenceId);
-    sequenceCache.delete(sequenceId);
-  } else {
-    sequenceConfigs.clear();
-    sequenceCache.clear();
-  }
-}
-
 function getElementCSSAnimation(
   target: HTMLElement | string | null,
   animationOptions: AnimationOptions,
@@ -226,8 +192,7 @@ function getScrubScene(
   } as ScrubPointerScene;
 }
 
-// Internal function for creating individual animations
-function _createAnimation(
+function getAnimation(
   target: HTMLElement | string | null,
   animationOptions: AnimationOptions,
   trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
@@ -246,40 +211,6 @@ function _createAnimation(
   return getWebAnimation(target, animationOptions, trigger, { reducedMotion });
 }
 
-function _getOrCreateSequence(sequenceId: string, reducedMotion: boolean): Sequence | null {
-  if (sequenceCache.has(sequenceId)) return sequenceCache.get(sequenceId)!;
-
-  const configs = sequenceConfigs.get(sequenceId);
-  if (!configs?.length || configs.length < configs[0].total) return null;
-
-  configs.sort((a, b) => a.index - b.index);
-
-  const groups = configs
-    .map((cfg) =>
-      _createAnimation(cfg.target, cfg.effectOptions as AnimationOptions, undefined, reducedMotion),
-    )
-    .filter((a): a is AnimationGroup => a instanceof AnimationGroup);
-
-  if (!groups.length) return null;
-
-  const sequence = new Sequence(groups, configs[0].sequenceOptions);
-  sequenceCache.set(sequenceId, sequence);
-  return sequence;
-}
-
-function getAnimation(
-  target: HTMLElement | string | null,
-  animationOptions: AnimationOptions,
-  trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
-  reducedMotion: boolean = false,
-): AnimationGroup | MouseAnimationInstance | null {
-  const sequenceId = (animationOptions as AnimationOptions & { _sequenceId?: string })._sequenceId;
-  if (sequenceId) {
-    return _getOrCreateSequence(sequenceId, reducedMotion);
-  }
-  return _createAnimation(target, animationOptions, trigger, reducedMotion);
-}
-
 export {
   getCSSAnimation,
   getWebAnimation,

From 5e4736aac7da8e16e0c91fe55853cee9071d74f2 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Wed, 11 Feb 2026 11:21:12 +0200
Subject: [PATCH 27/29] move animation creation into sequence class

---
 packages/interact/src/core/Interact.ts        |  6 +--
 packages/interact/src/core/add.ts             | 54 +++++++------------
 .../interact/src/handlers/animationEnd.ts     |  5 +-
 packages/interact/src/handlers/click.ts       |  6 +--
 packages/interact/src/handlers/hover.ts       |  6 +--
 packages/interact/src/handlers/viewEnter.ts   |  5 +-
 packages/interact/src/types.ts                |  8 ---
 packages/interact/test/viewEnter.spec.ts      | 51 ++++++++++--------
 packages/motion/src/Sequence.ts               | 14 ++++-
 9 files changed, 70 insertions(+), 85 deletions(-)

diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index 5c842a0b..6ac6d87c 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -37,7 +37,7 @@ export class Interact {
     [listContainer: string]: { [interactionId: string]: boolean };
   };
   controllers: Set<IInteractionController>;
-  sequenceCache: Map<string, MotionSequence> = new Map();
+  static sequenceCache: Map<string, MotionSequence> = new Map();
   static forceReducedMotion: boolean = false;
   static allowA11yTriggers: boolean = true;
   static instances: Interact[] = [];
@@ -94,7 +94,7 @@ export class Interact {
     this.addedInteractions = {};
     this.listInteractionsCache = {};
     this.controllers.clear();
-    this.sequenceCache.clear();
+    Interact.sequenceCache.clear();
     this.dataCache = { effects: {}, sequences: {}, conditions: {}, interactions: {} };
     Interact.instances.splice(Interact.instances.indexOf(this), 1);
   }
@@ -171,7 +171,7 @@ export class Interact {
     Interact.controllerCache.forEach((controller: IInteractionController) => {
       controller.disconnect();
     });
-    Interact.instances.forEach((instance) => instance.sequenceCache.clear());
+    Interact.sequenceCache.clear();
     Interact.instances.length = 0;
     Interact.controllerCache.clear();
   }
diff --git a/packages/interact/src/core/add.ts b/packages/interact/src/core/add.ts
index 369fec65..803acc04 100644
--- a/packages/interact/src/core/add.ts
+++ b/packages/interact/src/core/add.ts
@@ -8,30 +8,27 @@ import type {
   InteractionTrigger,
   CreateTransitionCSSParams,
   IInteractionController,
-  GetAnimationFn,
 } from '../types';
 import { isSequenceEffect } from '../types';
 import { createTransitionCSS, getMediaQuery, getSelectorCondition } from '../utils';
 import { getInterpolatedKey } from './utilities';
 import { Interact, getSelector } from './Interact';
 import TRIGGER_TO_HANDLER_MODULE_MAP from '../handlers';
-import { getAnimation, Sequence as MotionSequence, AnimationGroup } from '@wix/motion';
+import { getAnimation as motionGetAnimation, Sequence as MotionSequence } from '@wix/motion';
 import type { AnimationOptions, TriggerVariant } from '@wix/motion';
 import { effectToAnimationOptions } from '../handlers/utilities';
 
-export function createGetAnimation(sequenceCache: Map<string, MotionSequence>) {
-  return (
-    target: HTMLElement | string | null,
-    animationOptions: AnimationOptions & { _sequenceId?: string },
-    trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
-    reducedMotion: boolean = false,
-  ) => {
-    const sequenceId = animationOptions._sequenceId;
-    if (sequenceId) {
-      return sequenceCache.get(sequenceId) ?? null;
-    }
-    return getAnimation(target, animationOptions, trigger, reducedMotion);
-  };
+export function getAnimation(
+  target: HTMLElement | string | null,
+  animationOptions: AnimationOptions & { _sequenceId?: string },
+  trigger?: Partial<TriggerVariant> & { element?: HTMLElement },
+  reducedMotion: boolean = false,
+) {
+  const sequenceId = animationOptions._sequenceId;
+  if (sequenceId) {
+    return Interact.sequenceCache.get(sequenceId) ?? null;
+  }
+  return motionGetAnimation(target, animationOptions, trigger , reducedMotion);
 }
 
 function buildSequences(
@@ -44,7 +41,7 @@ function buildSequences(
     {
       configs: Array<{
         target: HTMLElement;
-        effectOptions: Record<string, unknown>;
+        animationOptions: AnimationOptions;
         index: number;
       }>;
       sequenceOptions: {
@@ -70,22 +67,17 @@ function buildSequences(
     for (const target of targets) {
       group.configs.push({
         target,
-        effectOptions: effectToAnimationOptions(effect),
+        animationOptions: effectToAnimationOptions(effect) as AnimationOptions,
         index: effect._sequenceIndex,
       });
     }
   }
 
   for (const [sequenceId, { configs, sequenceOptions }] of sequenceGroups) {
-    sequenceCache.delete(sequenceId);
     configs.sort((a, b) => a.index - b.index);
-    const groups = configs
-      .map((cfg) =>
-        getAnimation(cfg.target, cfg.effectOptions as AnimationOptions, undefined, reducedMotion),
-      )
-      .filter((a): a is AnimationGroup => a instanceof AnimationGroup);
-    if (groups.length) {
-      sequenceCache.set(sequenceId, new MotionSequence(groups, sequenceOptions));
+    const sequence = MotionSequence.build(configs, sequenceOptions, reducedMotion);
+    if (sequence) {
+      sequenceCache.set(sequenceId, sequence);
     }
   }
 }
@@ -174,7 +166,6 @@ function _applyInteraction(
   targetElements: HTMLElement | HTMLElement[],
   selectorCondition: string | undefined,
   useFirstChild: boolean,
-  getAnimationFn: GetAnimationFn,
 ) {
   const isSourceArray = Array.isArray(sourceElements);
   const isTargetArray = Array.isArray(targetElements);
@@ -191,7 +182,6 @@ function _applyInteraction(
           targetEl,
           effect as Effect,
           interaction.params!,
-          getAnimationFn,
           selectorCondition,
           useFirstChild,
         );
@@ -207,7 +197,6 @@ function _applyInteraction(
         targetEl,
         effect as Effect,
         interaction.params!,
-        getAnimationFn,
         selectorCondition,
         useFirstChild,
       );
@@ -316,11 +305,10 @@ function _addInteraction(
   interactionsToApply.reverse();
 
   // Build MotionSequences eagerly before calling handlers
-  buildSequences(interactionsToApply, instance.sequenceCache, Interact.forceReducedMotion);
+  buildSequences(interactionsToApply, Interact.sequenceCache, Interact.forceReducedMotion);
 
-  const getAnimationFn = createGetAnimation(instance.sequenceCache) as GetAnimationFn;
   interactionsToApply.forEach((interaction) => {
-    _applyInteraction(...interaction, getAnimationFn);
+    _applyInteraction(...interaction);
   });
 }
 
@@ -425,7 +413,7 @@ function addEffectsForTarget(
 
   // apply the effects in reverse to return to the order specified by the user to ensure order of composition is as defined
   interactionsToApply.reverse().forEach((interaction) => {
-    _applyInteraction(...interaction, getAnimation as GetAnimationFn);
+    _applyInteraction(...interaction);
   });
 
   return interactionIds.length > 0;
@@ -441,7 +429,6 @@ function addInteraction<T extends TriggerType>(
   target: HTMLElement,
   effect: Effect,
   options: InteractionParamsTypes[T],
-  getAnimation: GetAnimationFn,
   selectorCondition?: string,
   useFirstChild?: boolean,
 ): void {
@@ -477,7 +464,6 @@ function addInteraction<T extends TriggerType>(
     targetController,
     selectorCondition,
     allowA11yTriggers: Interact.allowA11yTriggers,
-    getAnimation,
   });
 }
 
diff --git a/packages/interact/src/handlers/animationEnd.ts b/packages/interact/src/handlers/animationEnd.ts
index 97bc4997..cd477ed7 100644
--- a/packages/interact/src/handlers/animationEnd.ts
+++ b/packages/interact/src/handlers/animationEnd.ts
@@ -5,6 +5,7 @@ import {
   addHandlerToMap,
   removeElementFromHandlerMap,
 } from './utilities';
+import { getAnimation } from '../core/add';
 
 const handlerMap = new WeakMap() as HandlerObjectMap;
 
@@ -13,10 +14,8 @@ function addAnimationEndHandler(
   target: HTMLElement,
   effect: TimeEffect,
   __: AnimationEndParams,
-  { reducedMotion, selectorCondition, getAnimation }: InteractOptions,
+  { reducedMotion, selectorCondition }: InteractOptions,
 ): void {
-  if (!getAnimation) return;
-
   const animation = getAnimation(
     target,
     effectToAnimationOptions(effect),
diff --git a/packages/interact/src/handlers/click.ts b/packages/interact/src/handlers/click.ts
index e04e2e49..46aa333b 100644
--- a/packages/interact/src/handlers/click.ts
+++ b/packages/interact/src/handlers/click.ts
@@ -8,7 +8,6 @@ import type {
   EffectBase,
   IInteractionController,
   InteractOptions,
-  GetAnimationFn,
 } from '../types';
 import { isSequenceEffect } from '../types';
 import {
@@ -16,6 +15,7 @@ import {
   addHandlerToMap,
   removeElementFromHandlerMap,
 } from './utilities';
+import { getAnimation } from '../core/add';
 
 const handlerMap = new WeakMap() as HandlerObjectMap;
 
@@ -23,7 +23,6 @@ function createTimeEffectHandler(
   element: HTMLElement,
   effect: TimeEffect & EffectBase,
   options: PointerTriggerParams,
-  getAnimation: GetAnimationFn,
   reducedMotion: boolean = false,
   selectorCondition?: string,
 ) {
@@ -121,7 +120,6 @@ function addClickHandler(
     targetController,
     selectorCondition,
     allowA11yTriggers,
-    getAnimation,
   }: InteractOptions,
 ) {
   let handler: ((event: MouseEvent | KeyboardEvent) => void) | null;
@@ -139,12 +137,10 @@ function addClickHandler(
       selectorCondition,
     );
   } else {
-    if (!getAnimation) return;
     handler = createTimeEffectHandler(
       target,
       effect as TimeEffect & EffectBase,
       options as PointerTriggerParams,
-      getAnimation,
       reducedMotion,
       selectorCondition,
     );
diff --git a/packages/interact/src/handlers/hover.ts b/packages/interact/src/handlers/hover.ts
index b0aaf0e2..0d9c314d 100644
--- a/packages/interact/src/handlers/hover.ts
+++ b/packages/interact/src/handlers/hover.ts
@@ -8,7 +8,6 @@ import type {
   EffectBase,
   IInteractionController,
   InteractOptions,
-  GetAnimationFn,
 } from '../types';
 import { isSequenceEffect } from '../types';
 import {
@@ -16,6 +15,7 @@ import {
   addHandlerToMap,
   removeElementFromHandlerMap,
 } from './utilities';
+import { getAnimation } from '../core/add';
 
 const handlerMap = new WeakMap() as HandlerObjectMap;
 
@@ -23,7 +23,6 @@ function createTimeEffectHandler(
   element: HTMLElement,
   effect: TimeEffect & EffectBase,
   options: PointerTriggerParams,
-  getAnimation: GetAnimationFn,
   reducedMotion: boolean = false,
   selectorCondition?: string,
 ) {
@@ -134,7 +133,6 @@ function addHoverHandler(
     targetController,
     selectorCondition,
     allowA11yTriggers,
-    getAnimation,
   }: InteractOptions,
 ) {
   let handler: ((event: MouseEvent | FocusEvent) => void) | null;
@@ -154,12 +152,10 @@ function addHoverHandler(
     );
     isStateTrigger = true;
   } else {
-    if (!getAnimation) return;
     handler = createTimeEffectHandler(
       target,
       effect as TimeEffect & EffectBase,
       options as PointerTriggerParams,
-      getAnimation,
       reducedMotion,
       selectorCondition,
     );
diff --git a/packages/interact/src/handlers/viewEnter.ts b/packages/interact/src/handlers/viewEnter.ts
index 76c87d41..0fe8d9c7 100644
--- a/packages/interact/src/handlers/viewEnter.ts
+++ b/packages/interact/src/handlers/viewEnter.ts
@@ -6,6 +6,7 @@ import {
   addHandlerToMap,
   removeElementFromHandlerMap,
 } from './utilities';
+import { getAnimation } from '../core/add';
 import fastdom from 'fastdom';
 
 const SAFE_OBSERVER_CONFIG: IntersectionObserverInit = {
@@ -137,7 +138,7 @@ function addViewEnterHandler(
   target: HTMLElement,
   effect: TimeEffect,
   options: ViewEnterParams = {},
-  { reducedMotion, selectorCondition, getAnimation }: InteractOptions = {},
+  { reducedMotion, selectorCondition }: InteractOptions = {},
 ) {
   // For sequence effects, only the first effect (index 0) controls playback
   if (isSequenceEffect(effect) && effect._sequenceIndex !== 0) {
@@ -145,8 +146,6 @@ function addViewEnterHandler(
     return;
   }
 
-  if (!getAnimation) return;
-
   const mergedOptions = { ...viewEnterOptions, ...options };
   const type = mergedOptions.type || 'once';
   const animation = getAnimation(
diff --git a/packages/interact/src/types.ts b/packages/interact/src/types.ts
index 31199196..3cfc91bf 100644
--- a/packages/interact/src/types.ts
+++ b/packages/interact/src/types.ts
@@ -257,19 +257,11 @@ export function isSequenceEffect(effect: Effect): effect is SequenceEffect {
   return '_sequenceId' in effect && 'duration' in effect;
 }
 
-export type GetAnimationFn = (
-  target: HTMLElement | string | null,
-  animationOptions: Record<string, unknown>,
-  trigger?: unknown,
-  reducedMotion?: boolean,
-) => unknown;
-
 export type InteractOptions = {
   reducedMotion?: boolean;
   targetController?: IInteractionController;
   selectorCondition?: string;
   allowA11yTriggers?: boolean;
-  getAnimation?: GetAnimationFn;
 };
 
 export type InteractionHandlerModule<T extends TriggerType> = {
diff --git a/packages/interact/test/viewEnter.spec.ts b/packages/interact/test/viewEnter.spec.ts
index 59bb69dd..886600c4 100644
--- a/packages/interact/test/viewEnter.spec.ts
+++ b/packages/interact/test/viewEnter.spec.ts
@@ -21,6 +21,10 @@ vi.mock('@wix/motion', () => ({
   registerEffects: vi.fn(),
 }));
 
+vi.mock('../src/core/add', () => ({
+  getAnimation: (...args: any[]) => mockGetAnimation(...args),
+}));
+
 vi.mock('fastdom', () => ({
   default: {
     measure: vi.fn((cb) => cb()),
@@ -112,7 +116,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         {},
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       expect(IntersectionObserverMock).toHaveBeenCalled();
@@ -125,7 +129,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'once' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry();
@@ -142,7 +146,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: true, threshold: 0.5 },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({
@@ -165,7 +169,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: true, threshold },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({
@@ -196,7 +200,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: true, threshold },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({
@@ -223,7 +227,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { useSafeViewEnter: false, threshold },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({
@@ -245,7 +249,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -260,7 +264,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       // First entry
@@ -282,7 +286,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       // First entry
@@ -307,7 +311,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -322,7 +326,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'alternate' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       expect(mockAnimation.persist).toHaveBeenCalled();
@@ -336,7 +340,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -352,7 +356,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       // First entry
@@ -376,7 +380,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       // First entry
@@ -403,7 +407,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -418,7 +422,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'repeat' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       expect(mockAnimation.persist).toHaveBeenCalled();
@@ -432,7 +436,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -447,7 +451,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       // First entry
@@ -469,7 +473,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       // First entry
@@ -494,7 +498,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       // First entry
@@ -520,7 +524,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       const entry = createEntry({ isIntersecting: true });
@@ -535,7 +539,7 @@ describe('viewEnter handler', () => {
         target,
         { duration: 1000, namedEffect: { type: 'FadeIn' } },
         { type: 'state' },
-        { getAnimation: mockGetAnimation },
+        {},
       );
 
       expect(mockAnimation.persist).toHaveBeenCalled();
@@ -544,12 +548,13 @@ describe('viewEnter handler', () => {
 
   describe('Null animation handling', () => {
     it('should not create IntersectionObserver when animation is null', async () => {
+      mockGetAnimation.mockReturnValueOnce(null);
       viewEnterHandler.add(
         element,
         target,
         { duration: 1000, namedEffect: { type: 'NonExistentEffect' } },
         {},
-        { getAnimation: () => null },
+        {},
       );
 
       // IntersectionObserver should not be created when animation is null
diff --git a/packages/motion/src/Sequence.ts b/packages/motion/src/Sequence.ts
index a799ea46..e992577b 100644
--- a/packages/motion/src/Sequence.ts
+++ b/packages/motion/src/Sequence.ts
@@ -1,6 +1,7 @@
 import { AnimationGroup } from './AnimationGroup';
-import { SequenceOptions } from './types';
+import type { AnimationOptions, SequenceOptions } from './types';
 import { calculateOffsets, resolveEasingFunction } from './utils';
+import { getAnimation } from './motion';
 
 export class Sequence extends AnimationGroup {
   animationGroups: AnimationGroup[];
@@ -56,6 +57,17 @@ export class Sequence extends AnimationGroup {
     );
   }
 
+  static build(
+    configs: Array<{ target: HTMLElement | string | null; animationOptions: AnimationOptions }>,
+    sequenceOptions?: SequenceOptions,
+    reducedMotion: boolean = false,
+  ): Sequence | null {
+    const groups = configs
+      .map((cfg) => getAnimation(cfg.target, cfg.animationOptions, undefined, reducedMotion))
+      .filter((a): a is AnimationGroup => a instanceof AnimationGroup);
+    return groups.length ? new Sequence(groups, sequenceOptions) : null;
+  }
+
   // Note: play(), pause(), reverse(), cancel(), setPlaybackRate(), onFinish(),
   // finished, and playState are inherited from AnimationGroup.
   // Since we pass all flattened animations to super(), the parent's

From eba223e45a5e0ecb02288f563f4565cceb426c6e Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Wed, 11 Feb 2026 11:45:15 +0200
Subject: [PATCH 28/29] remove any casr

---
 packages/interact/src/core/Interact.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/interact/src/core/Interact.ts b/packages/interact/src/core/Interact.ts
index 6ac6d87c..6e5004bb 100644
--- a/packages/interact/src/core/Interact.ts
+++ b/packages/interact/src/core/Interact.ts
@@ -367,7 +367,7 @@ function parseConfig(config: InteractConfig, useCutsomElement: boolean = false):
 
     const listContainer = interaction.listContainer;
 
-    effects.forEach((effect) => {
+    effects.forEach((effect: (Effect | EffectRef) & { interactionId?: string }) => {
       /*
        * Target cascade order is the first of:
        *  -> Config.interactions.effects.effect.key
@@ -401,7 +401,7 @@ function parseConfig(config: InteractConfig, useCutsomElement: boolean = false):
       }
 
       const interactionId = `${target}::${effectId}::${interactionIdx}`;
-      (effect as any).interactionId = interactionId;
+      effect.interactionId = interactionId;
       interactions[source].interactionIds.add(interactionId);
 
       if (target === source) {

From a58179838c62555f0086b61ea30697af79bd2a75 Mon Sep 17 00:00:00 2001
From: bar-goldenberg <bargol@wix.com>
Date: Wed, 11 Feb 2026 18:30:49 +0200
Subject: [PATCH 29/29] yarn format

---
 packages/interact/src/core/add.ts       | 2 +-
 packages/interact/src/handlers/click.ts | 7 +------
 packages/interact/src/handlers/hover.ts | 7 +------
 3 files changed, 3 insertions(+), 13 deletions(-)

diff --git a/packages/interact/src/core/add.ts b/packages/interact/src/core/add.ts
index 5737cb65..db575f8b 100644
--- a/packages/interact/src/core/add.ts
+++ b/packages/interact/src/core/add.ts
@@ -28,7 +28,7 @@ export function getAnimation(
   if (sequenceId) {
     return Interact.sequenceCache.get(sequenceId) ?? null;
   }
-  return motionGetAnimation(target, animationOptions, trigger , reducedMotion);
+  return motionGetAnimation(target, animationOptions, trigger, reducedMotion);
 }
 
 function buildSequences(
diff --git a/packages/interact/src/handlers/click.ts b/packages/interact/src/handlers/click.ts
index f25f91c9..41e35611 100644
--- a/packages/interact/src/handlers/click.ts
+++ b/packages/interact/src/handlers/click.ts
@@ -119,12 +119,7 @@ function addClickHandler(
   target: HTMLElement,
   effect: (TimeEffect | TransitionEffect) & EffectBase,
   options: StateParams | PointerTriggerParams = {} as StateParams,
-  {
-    reducedMotion,
-    targetController,
-    selectorCondition,
-    allowA11yTriggers,
-  }: InteractOptions,
+  { reducedMotion, targetController, selectorCondition, allowA11yTriggers }: InteractOptions,
 ) {
   let handler: ((event: MouseEvent | KeyboardEvent) => void) | null;
   let once = false;
diff --git a/packages/interact/src/handlers/hover.ts b/packages/interact/src/handlers/hover.ts
index 3a7a4afa..f1bda379 100644
--- a/packages/interact/src/handlers/hover.ts
+++ b/packages/interact/src/handlers/hover.ts
@@ -134,12 +134,7 @@ function addHoverHandler(
   target: HTMLElement,
   effect: (TransitionEffect | TimeEffect) & EffectBase,
   options: StateParams | PointerTriggerParams = {},
-  {
-    reducedMotion,
-    targetController,
-    selectorCondition,
-    allowA11yTriggers,
-  }: InteractOptions,
+  { reducedMotion, targetController, selectorCondition, allowA11yTriggers }: InteractOptions,
 ) {
   let handler: ((event: MouseEvent | FocusEvent) => void) | null;
   let isStateTrigger = false;