rune-scroller 2.2.1 → 3.0.0

package/README.md

@@ -1,14 +1,12 @@
-# ⚡ Rune Scroller - Full Reference
-
-**📚 Complete API Reference** — Detailed documentation for all features and options.
-
----
+# ⚡ Rune Scroller
 
 <div align="center">
 	<img src="./logo.png" alt="Rune Scroller Logo" width="200" />
 </div>
 
-**Lightweight scroll animations for Svelte 5** — Built with Svelte 5 Runes and IntersectionObserver API.
+**Lightweight scroll animations. AOS replacement. Works everywhere.**
+
+Built with native IntersectionObserver — zero JS on scroll, GPU-accelerated, ~5.6KB gzipped.
 
 > 🚀 **Open Source** by [ludoloops](https://github.com/ludoloops) at [LeLab.dev](https://lelab.dev)
 > 📜 Licensed under **MIT**
@@ -24,517 +22,263 @@
 
 ---
 
-## ✨ Features
+## 🚀 Quick Start
 
-- **14KB gzipped** (47KB uncompressed) - Minimal overhead, optimized for production
-- **Zero dependencies** - Pure Svelte 5 + IntersectionObserver
-- **14 animations** - Fade, Zoom, Flip, Slide, Bounce variants
-- **Full TypeScript support** - Type definitions generated from JSDoc
-- **SSR-ready** - SvelteKit compatible
-- **GPU-accelerated** - Pure CSS transforms
-- **Accessible** - Respects `prefers-reduced-motion`
-- **v2.0.0 New** - `onVisible` callback, ResizeObserver support, animation validation, sentinel customization
-- **✨ Latest** - `useIntersection` migrated to Svelte 5 `$effect` rune for better lifecycle management
-- **🚀 Bundle optimized** - CSS with custom properties, production build minification
-- **🚀 v2.2.0** - Cache CSS check to eliminate 99% of reflows
+### Any framework — Svelte, React, Vue, Angular, Vanilla JS
 
----
- 
-## 🚀 Performance
-
-### Cache CSS Validation (v2.2.0)
-
-**Problem:**
-- `checkAndWarnIfCSSNotLoaded()` was called for EVERY element
-- Each call did:
-  - `document.createElement('div')`
-  - `document.body.appendChild(test)`
-  - `getComputedStyle(test)` ⚠️ **Expensive!** Forces full page reflow
-  - `test.remove()`
-- For 100 animated elements = **100 reflows + 100 DOM operations**
-
-**Solution:**
-```javascript
-// Cache to check only once per page load
-let cssCheckResult = null;
-
-export function checkAndWarnIfCSSNotLoaded() {
-  if (cssCheckResult !== null) return cssCheckResult;
-  // ... expensive check ...
-  cssCheckResult = hasAnimation;
-  return hasAnimation;
-}
+```bash
+npm install rune-scroller
 ```
 
-**Impact:**
-- Validation runs ONLY ONCE per page load
-- Eliminates layout thrashing from repeated `getComputedStyle()` calls
-- For 100 elements: **99 fewer reflows** (100 → 1)
-- Zero memory overhead (single boolean)
-
-### Current Performance Metrics
-
-| Metric | Value |
-|---------|--------|
-| **Bundle size** | 12.4KB (compressed), 40.3KB (unpacked) |
-| **Initialization** | ~1-2ms per element |
-| **Observer callback** | <0.5ms per frame |
-| **CSS validation** | ~0.1ms total (v2.2.0, with cache) |
-| **Memory per observer** | ~1.2KB |
-| **Animation performance** | 60fps maintained |
-| **Memory leaks** | 0 detected |
-
-### Why Performance Matters
-
-**Layout Thrashing:**
-- Synchronous reflows block the main thread
-- Each reflow can take 10-20ms
-- For 100 elements = **1-2 seconds blocked**
-- User sees stuttering/jank while scrolling
-
-**Solution:**
-- Cache = 1 reflow instead of N
-- 99% improvement on pages with many animations
-- Smoother scrolling, better UX
-
-### Optimized Code Patterns
-
-**IntersectionObserver:**
-- Native API (no scroll listeners)
-- Fast callback (<0.5ms per frame)
-- No debounce needed (browser handles this efficiently)
-
-**CSS Animations:**
-- Transforms only (GPU-accelerated)
-- No layout/repaint during animation
-- `will-change` on visible elements only
-
-**DOM Operations:**
-- `insertAdjacentElement('beforebegin')` instead of `insertBefore`
-- `offsetHeight` instead of `getBoundingClientRect()` (avoids transform issues)
-- Complete cleanup on destroy
-
-**Memory Management:**
-- All observers disconnected
-- Sentinel and wrapper removed
-- State prevents double-disconnects
-- 0 memory leaks detected (121/121 tests)
-
-### Future Considerations
-
-**1. `will-change` Timing**
-- Currently: `.is-visible { will-change: transform, opacity; }`
-- Trade-off: Stays active after animation (consumes GPU memory)
-- Consideration: Use `transitionend` event to remove `will-change`
-- Recommendation: Keep current (GPU memory is cheap)
-
-**2. Threshold Tuning**
-- Current: `threshold: 0` (triggers as soon as 1px is visible)
-- Alternative: `threshold: 0.1` or `threshold: 0.25`
-- Trade-off: Higher threshold = later trigger = smoother stagger
-- Recommendation: Keep `threshold: 0` for immediate feedback
-
-**3. requestIdleCallback**
-- Potential: Defer non-critical setup to browser idle time
-- Trade-off: Complex to implement, marginal benefit
-- Recommendation: Not needed (current performance is excellent)
-
-**4. Testing on Low-End Devices**
-- Test on mobile phones, older browsers
-- Use DevTools CPU throttling
-- Consider Lighthouse/Puppeteer for automated testing
-- Ensure 60fps maintained on real devices
-
-### What NOT to Optimize
-
-**Anti-patterns to avoid:**
-
-1. ❌ **Premature optimization**
-   - Don't optimize without measurements
-   - Profile first, optimize later
-   - "Premature optimization is the root of all evil"
-
-2. ❌ **Over-engineering**
-   - Complex solutions for small gains
-   - Keep it simple when possible
-   - Don't sacrifice readability for micro-optimizations
-
-3. ❌ **Breaking performance for size**
-   - Bundle size matters (12.4KB is excellent)
-   - Don't add huge dependencies for minor improvements
-
-4. ❌ **Optimizing unused paths**
-   - Focus on hot paths (element creation, scroll, intersection)
-   - Cold paths (initialization, destroy) less critical
-
-5. ❌ **Sacrificing maintainability**
-   - Don't sacrifice code clarity for micro-optimizations
-   - Comments should explain WHY, not just WHAT
-   - Keep code simple and understandable
-
-### Performance Testing
-
-**Recommended approach:**
-1. Create a benchmark with 100-1000 animated elements
-2. Measure: initialization, first animation, scroll performance, cleanup
-3. Profile with DevTools Performance tab
-4. Test on real pages (not just benchmarks)
-5. Verify 60fps is maintained during scroll
-
-**Tools:**
-- Chrome DevTools Performance tab
-- Firefox Performance Profiler
-- Web Inspector (Safari)
-- Lighthouse (PageSpeed, accessibility, best practices)
-
----
- 
-## 📦 Installation
+```js
+import AOS from "rune-scroller/aos";
+AOS.init();
+```
 
-```bash
-npm install rune-scroller
-# or
-pnpm add rune-scroller
-# or
-yarn add rune-scroller
+```html
+<div data-aos="fade-up" data-aos-duration="800">Animated</div>
+<div data-aos="zoom-in" data-aos-delay="200">Delayed zoom</div>
 ```
 
----
+That's it. Same API as AOS. Works everywhere.
 
-## 🚀 Quick Start
+### Svelte (native action)
 
 ```svelte
 <script>
-	import runeScroller from 'rune-scroller';
+	import rs from 'rune-scroller';
 </script>
 
-<!-- Simple animation -->
-<div use:runeScroller={{ animation: 'fade-in' }}>
-	<h2>Animated Heading</h2>
-</div>
-
-<!-- With custom duration -->
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1500 }}>
-	<div class="card">Smooth fade and slide</div>
-</div>
-
-<!-- Repeat on every scroll -->
-<div use:runeScroller={{ animation: 'bounce-in', repeat: true }}>
-	<button>Bounces on every scroll</button>
-</div>
+<div use:rs={{ animation: 'fade-up' }}>Animates on scroll</div>
 ```
 
-That's it! The CSS animations are included automatically when you import rune-scroller.
+### React
 
-### Option 2: Manual CSS Import
+````jsx
+import { useEffect } from "react";
+### React (not tested — should work)
 
-For fine-grained control, import CSS manually:
+```jsx
+import { useEffect } from 'react';
+import AOS from 'rune-scroller/aos';
 
-**Step 1: Import CSS in your root layout (recommended for SvelteKit):**
+function App() {
+	useEffect(() => { AOS.init(); }, []);
+	return (
+		<>
+			<h1 data-aos="fade-down">Welcome</h1>
+			<p data-aos="fade-up" data-aos-delay="200">Subtitle</p>
+		</>
+	);
+}
+````
 
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script>
-	import 'rune-scroller/animations.css';
-	let { children } = $props();
+### Vue (not tested — should work)
+
+```vue
+<script setup>
+import { onMounted } from "vue";
+import AOS from "rune-scroller/aos";
+onMounted(() => AOS.init());
 </script>
 
-{@render children()}
+<template>
+  <div data-aos="fade-up">Animated</div>
+</template>
 ```
 
-**Or import in each component:**
+### Angular (not tested — should work)
 
-```svelte
-<script>
-	import runeScroller from 'rune-scroller';
-	import 'rune-scroller/animations.css';
-</script>
+```typescript
+// app.component.ts
+import { Component, OnInit } from "@angular/core";
+import AOS from "rune-scroller/aos";
+
+@Component({ selector: "app-root", templateUrl: "./app.component.html" })
+export class AppComponent implements OnInit {
+  ngOnInit() {
+    AOS.init();
+  }
+}
 ```
 
-**Step 2: Use the animations**
+```html
+<!-- app.component.html -->
+<div data-aos="fade-up">Animated</div>
+```
 
-```svelte
-<script>
-	import runeScroller from 'rune-scroller';
-	// CSS already imported in layout or above
+### CDN (not tested — should work)
+
+```html
+<script type="module">
+  import AOS from "https://esm.sh/rune-scroller/aos";
+  AOS.init();
 </script>
 
-<div use:runeScroller={{ animation: 'fade-in' }}>
-	Animated content
-</div>
+<div data-aos="fade-up">Works without any build step</div>
 ```
 
 ---
 
-## 🎨 Available Animations
-
-### Fade (5)
-- `fade-in` - Simple opacity fade
-- `fade-in-up` - Fade + move up 300px
-- `fade-in-down` - Fade + move down 300px
-- `fade-in-left` - Fade + move from right 300px
-- `fade-in-right` - Fade + move from left 300px
-
-### Zoom (5)
-- `zoom-in` - Scale from 0.3 to 1
-- `zoom-out` - Scale from 2 to 1
-- `zoom-in-up` - Zoom (0.5→1) + move up 300px
-- `zoom-in-left` - Zoom (0.5→1) + move from right 300px
-- `zoom-in-right` - Zoom (0.5→1) + move from left 300px
+## ✨ Features
 
-### Others (4)
-- `flip` - 3D flip on Y-axis
-- `flip-x` - 3D flip on X-axis
-- `slide-rotate` - Slide + rotate 10°
-- `bounce-in` - Bouncy entrance (spring effect)
+- **Framework agnostic** — Svelte, React, Vue, Angular, Vanilla JS, CDN
+- **AOS drop-in** — Same `data-aos` attributes, same `init()` API
+- **Zero dependencies** — Pure JS + native IntersectionObserver
+- **~5.6KB gzipped** — Smaller than AOS (6.9KB)
+- **37 animations** — Fade, Zoom, Flip, Slide, Bounce
+- **Zero JS on scroll** — Browser handles detection natively
+- **TypeScript support** — Full type definitions
+- **SSR-ready** — SvelteKit, Next.js, Nuxt compatible
+- **GPU-accelerated** — CSS transforms via `translate3d`
+- **Accessible** — Respects `prefers-reduced-motion`
+- **No wrapper divs** — Your layouts stay intact
 
 ---
 
-## ⚙️ Options
+### AOS vs rune-scroller
 
-```typescript
-interface RuneScrollerOptions {
-	animation?: AnimationType;  // Animation name (default: 'fade-in')
-	duration?: number;          // Duration in ms (default: 800)
-	repeat?: boolean;           // Repeat on scroll (default: false)
-	debug?: boolean;            // Show sentinel as visible line (default: false)
-	offset?: number;            // Sentinel offset in px (default: 0, negative = above)
-	onVisible?: (element: HTMLElement) => void;  // Callback when animation triggers (v2.0.0+)
-	sentinelColor?: string;     // Sentinel debug color, e.g. '#ff6b6b' (v2.0.0+)
-	sentinelId?: string;        // Custom ID for sentinel identification (v2.0.0+)
-}
-```
+|                           | rune-scroller                                  | AOS                                        |
+| ------------------------- | ---------------------------------------------- | ------------------------------------------ |
+| **Bundle size (gzipped)** | **~5.6KB** JS+CSS                              | ~6.9KB JS+CSS                              |
+| **Dependencies**          | **0**                                          | lodash.throttle, lodash.debounce           |
+| **Scroll detection**      | **IntersectionObserver** (native, C++)         | Scroll event + throttle (JS)               |
+| **Per-scroll cost**       | **0** — browser handles it                     | Iterates ALL elements every 99ms           |
+| **Layout reads**          | **1 per element** (init only)                  | `offsetParent` loop per element per scroll |
+| **Resize handling**       | **ResizeObserver** (native)                    | debounced scroll recalc                    |
+| **100 animated elements** | **~0ms per scroll**                            | ~2-5ms per scroll (layout thrashing)       |
+| **Animations**            | 30                                             | 28                                         |
+| **Framework**             | **Any** (Svelte, React, Vue, Angular, Vanilla) | Vanilla JS only                            |
 
-### Option Details
+The key difference: **AOS runs JavaScript on every scroll event** for every element. rune-scroller delegates detection to the browser's native IntersectionObserver — zero JS execution until an element actually enters the viewport.
 
-- **`animation`** - Type of animation to play. Choose from 14 built-in animations listed above. Invalid animations automatically fallback to 'fade-in' with a console warning.
-- **`duration`** - How long the animation lasts in milliseconds (default: 800ms).
-- **`repeat`** - If `true`, animation plays every time sentinel enters viewport. If `false`, plays only once.
-- **`debug`** - If `true`, displays the sentinel element as a visible line below your element. Useful for seeing exactly when animations trigger. Default color is cyan (#00e0ff), customize with `sentinelColor`.
-- **`offset`** - Offset of the sentinel in pixels. Positive values move sentinel down (delays animation), negative values move it up (triggers earlier). Useful for large elements where you want animation to trigger before the entire element is visible.
-- **`onVisible`** *(v2.0.0+)* - Callback function triggered when the animation becomes visible. Receives the animated element as parameter. Useful for analytics, lazy loading, or triggering custom effects.
-- **`sentinelColor`** *(v2.0.0+)* - Customize the debug sentinel color (e.g., '#ff6b6b' for red). Only visible when `debug: true`. Useful for distinguishing multiple sentinels on the same page.
-- **`sentinelId`** *(v2.0.0+)* - Set a custom ID for the sentinel element. If not provided, an auto-ID is generated (`sentinel-1`, `sentinel-2`, etc.). Useful for identifying sentinels in DevTools and tracking which element owns which sentinel.
+---
 
-### Examples
+## 🎨 Available Animations (30)
 
-```svelte
-<!-- Basic -->
-<div use:runeScroller={{ animation: 'zoom-in' }}>
-	Content
-</div>
+### Fade (10)
 
-<!-- Custom duration -->
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1000 }}>
-	Fast animation
-</div>
+- `fade` — Simple opacity fade
+- `fade-up` / `fade-down` / `fade-left` / `fade-right` — Fade + translate
+- `fade-up-right` / `fade-up-left` / `fade-down-right` / `fade-down-left` — Diagonal fades
 
-<!-- Repeat mode -->
-<div use:runeScroller={{ animation: 'bounce-in', repeat: true }}>
-	Repeats every time you scroll
-</div>
+### Zoom (10)
 
-<!-- Debug mode - shows cyan line marking sentinel position -->
-<div use:runeScroller={{ animation: 'fade-in', debug: true }}>
-	The cyan line below this shows when animation will trigger
-</div>
+- `zoom-in` / `zoom-out` — Scale in/out
+- `zoom-in-up` / `zoom-in-down` / `zoom-in-left` / `zoom-in-right` — Zoom + translate
+- `zoom-out-up` / `zoom-out-down` / `zoom-out-left` / `zoom-out-right` — Zoom out + translate
 
-<!-- Multiple options -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	duration: 1200,
-	repeat: true,
-	debug: true
-}}>
-	Full featured example
-</div>
+### Slide (4)
 
-<!-- Large element - trigger animation earlier with negative offset -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	offset: -200  // Trigger 200px before element bottom
-}}>
-	Large content that needs early triggering
-</div>
+- `slide-up` / `slide-down` / `slide-left` / `slide-right` — Slide from off-screen
 
-<!-- Delay animation by moving sentinel down -->
-<div use:runeScroller={{
-	animation: 'zoom-in',
-	offset: 300  // Trigger 300px after element bottom
-}}>
-	Content with delayed animation
-</div>
+### Flip (4)
 
-<!-- v2.0.0: onVisible callback for analytics tracking -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	onVisible: (el) => {
-		console.log('Animation visible!', el);
-		// Track analytics, load images, trigger API calls, etc.
-		window.gtag?.('event', 'animation_visible', { element: el.id });
-	}
-}}>
-	Tracked animation
-</div>
+- `flip-left` / `flip-right` — 3D flip on Y-axis
+- `flip-up` / `flip-down` — 3D flip on X-axis
 
-<!-- v2.0.0: Custom sentinel color for debugging -->
-<div use:runeScroller={{
-	animation: 'fade-in',
-	debug: true,
-	sentinelColor: '#ff6b6b'  // Red instead of default cyan
-}}>
-	Red debug sentinel
-</div>
+### Special (2)
 
-<!-- v2.0.0: Custom sentinel ID for identification -->
-<div use:runeScroller={{
-	animation: 'zoom-in',
-	sentinelId: 'hero-zoom',
-	debug: true
-}}>
-	Identified sentinel (shows "hero-zoom" in debug mode)
-</div>
+- `slide-rotate` — Slide + rotate
+- `bounce-in` — Bouncy spring entrance
 
-<!-- v2.0.0: Auto-ID (sentinel-1, sentinel-2, etc) -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	debug: true
-	// sentinelId omitted → auto generates "sentinel-1", "sentinel-2", etc
-}}>
-	Auto-identified sentinel
-</div>
-```
+### Customizable distance
 
----
+All animations use the `--rs-distance` CSS variable (default: `100px`):
 
-## 🎯 How It Works
-
-Rune Scroller uses **sentinel-based triggering**:
-
-1. An invisible 1px sentinel element is created below your element
-2. When the sentinel enters the viewport, animation triggers
-3. This ensures precise timing regardless of element size
-4. Uses native IntersectionObserver for performance
-5. Pure CSS animations (GPU-accelerated)
-6. *(v2.0.0)* Sentinel automatically repositions on element resize via ResizeObserver
-
-**Why sentinels?**
-- Accurate timing across all screen sizes
-- No complex offset calculations
-- Handles staggered animations naturally
-- Sentinel stays fixed while element animates (no observer confusion with transforms)
-
-**Automatic ResizeObserver** *(v2.0.0+)*
-- Sentinel repositions automatically when element resizes
-- Works with responsive layouts and dynamic content
-- No configuration needed—it just works
+```html
+<div data-aos="fade-up" style="--rs-distance: 200px">Farther slide</div>
+```
 
 ---
 
-## 🌐 SSR Compatibility
+## ⚙️ Options
 
-Works seamlessly with SvelteKit. Simply import rune-scroller in your root layout:
+### AOS Mode (data attributes)
+
+| Attribute           | Example         | Description                |
+| ------------------- | --------------- | -------------------------- |
+| `data-aos`          | `"fade-up"`     | Animation name             |
+| `data-aos-duration` | `"800"`         | Duration in ms             |
+| `data-aos-delay`    | `"200"`         | Delay in ms                |
+| `data-aos-easing`   | `"ease-in-out"` | CSS timing function        |
+| `data-aos-offset`   | `"120"`         | Trigger offset in px       |
+| `data-aos-once`     | `"true"`        | Animate only once          |
+| `data-aos-mirror`   | `"true"`        | Animate on scroll away too |
+
+### AOS init options
+
+```js
+AOS.init({
+  offset: 120,
+  duration: 400,
+  delay: 0,
+  easing: "ease",
+  once: false,
+  mirror: false,
+  startEvent: "DOMContentLoaded",
+});
+```
 
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script>
-	import runeScroller from 'rune-scroller';
-	let { children } = $props();
-</script>
+### Svelte Action options
 
-{@render children()}
+```typescript
+interface RuneScrollerOptions {
+  animation?: AnimationType; // default: 'fade-up'
+  duration?: number; // default: 400
+  delay?: number; // default: 0
+  easing?: string; // default: 'ease'
+  repeat?: boolean; // default: false
+  debug?: boolean;
+  offset?: number; // negative = earlier trigger
+  onVisible?: (el: HTMLElement) => void;
+  sentinelColor?: string;
+  sentinelId?: string;
+}
 ```
 
-Then use animations anywhere in your app:
+---
 
-```svelte
-<!-- src/routes/+page.svelte -->
-<script>
-	import runeScroller from 'rune-scroller';
-</script>
+## 🎯 How It Works
 
-<!-- No special handling needed -->
-<div use:runeScroller={{ animation: 'fade-in-up' }}>
-	Works in SvelteKit SSR!
-</div>
-```
+1. Invisible 1px sentinel appended as child of the animated element
+2. When sentinel enters viewport, animation triggers via IntersectionObserver
+3. Pure CSS transitions (GPU-accelerated via `translate3d`)
+4. ResizeObserver auto-repositions sentinel
 
-The library checks for browser environment and gracefully handles server-side rendering.
+**No wrapper divs** — the element itself becomes the positioning context. Your flex/grid layouts stay intact.
 
 ---
 
 ## ♿ Accessibility
 
-Respects `prefers-reduced-motion`:
-
-```css
-/* In animations.css */
-@media (prefers-reduced-motion: reduce) {
-	.scroll-animate {
-		animation: none !important;
-		opacity: 1 !important;
-		transform: none !important;
-	}
-}
-```
-
-Users who prefer reduced motion will see content without animations.
+Respects `prefers-reduced-motion` — animations are disabled automatically.
 
 ---
 
 ## 📚 API Reference
-### Public API
-
-Rune Scroller exports a **single action-based API** (no components):
-
-1. **`runeScroller`** (default) - Sentinel-based, simple, powerful
-
-**Why actions instead of components?**
-- Actions are lightweight directives
-- No DOM wrapper overhead
-- Better performance
-- More flexible
-
-### Main Export
 
 ```typescript
-// CSS is automatically included
-import runeScroller from 'rune-scroller';
+// Framework agnostic (AOS mode)
+import AOS from "rune-scroller/aos";
+AOS.init();
+AOS.refresh();
+AOS.refreshHard();
+
+// Svelte action (default)
+import rs from "rune-scroller";
 
 // Named exports
 import {
-	useIntersection,            // Composable
-	useIntersectionOnce,        // Composable
-	calculateRootMargin         // Utility
-} from 'rune-scroller';
+  runeScroller,
+  useIntersection,
+  useIntersectionOnce,
+  calculateRootMargin,
+  ANIMATION_TYPES,
+} from "rune-scroller";
 
 // Types
-import type {
-	AnimationType,
-	RuneScrollerOptions,
-	IntersectionOptions,
-	UseIntersectionReturn
-} from 'rune-scroller';
-```
-
-### TypeScript Types
-
-```typescript
-type AnimationType =
-	| 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left' | 'fade-in-right'
-	| 'zoom-in' | 'zoom-out' | 'zoom-in-up' | 'zoom-in-left' | 'zoom-in-right'
-	| 'flip' | 'flip-x' | 'slide-rotate' | 'bounce-in';
-
-interface RuneScrollerOptions {
-	animation?: AnimationType;
-	duration?: number;
-	repeat?: boolean;
-	debug?: boolean;
-	offset?: number;
-	onVisible?: (element: HTMLElement) => void;      // v2.0.0+
-	sentinelColor?: string;                          // v2.0.0+
-	sentinelId?: string;                             // v2.0.0+
-}
+import type { AnimationType, RuneScrollerOptions } from "rune-scroller";
 ```
 
 ---
@@ -545,48 +289,49 @@ interface RuneScrollerOptions {
 
 ```svelte
 <script>
-	import runeScroller from 'rune-scroller';
-
-	const items = [
-		{ title: 'Feature 1', description: 'Description 1' },
-		{ title: 'Feature 2', description: 'Description 2' },
-		{ title: 'Feature 3', description: 'Description 3' }
-	];
+	import rs from 'rune-scroller';
+	const items = ['Item 1', 'Item 2', 'Item 3'];
 </script>
 
-<div class="grid">
-	{#each items as item}
-		<div use:runeScroller={{ animation: 'fade-in-up', duration: 800 }}>
-			<h3>{item.title}</h3>
-			<p>{item.description}</p>
-		</div>
-	{/each}
-</div>
+{#each items as item, i}
+	<div use:rs={{ animation: 'fade-up', duration: 800, delay: i * 100 }}>
+		{item}
+	</div>
+{/each}
 ```
 
 ### Hero Section
 
-```svelte
-<div use:runeScroller={{ animation: 'fade-in-down', duration: 1000 }}>
-	<h1>Welcome</h1>
-</div>
+```html
+<h1 data-aos="fade-down" data-aos-duration="1000">Welcome</h1>
+<p data-aos="fade-up" data-aos-duration="1200">Subtitle</p>
+<button data-aos="zoom-in" data-aos-duration="800">Get Started</button>
+```
 
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1200 }}>
-	<p>Engaging content</p>
-</div>
+---
 
-<div use:runeScroller={{ animation: 'zoom-in', duration: 1000 }}>
-	<button>Get Started</button>
-</div>
+## 🔄 Replacing AOS
+
+```bash
+npm uninstall aos
+npm install rune-scroller
 ```
 
+```diff
+- import AOS from 'aos';
+- import 'aos/dist/aos.css';
++ import AOS from 'rune-scroller/aos';
+```
+
+Everything else stays the same. Same attributes, same options.
+
 ---
 
 ## 🔗 Links
 
-- **npm Package**: [rune-scroller](https://www.npmjs.com/package/rune-scroller)
+- **npm**: [rune-scroller](https://www.npmjs.com/package/rune-scroller)
 - **GitHub**: [lelabdev/rune-scroller](https://github.com/lelabdev/rune-scroller)
-- **Changelog**: [CHANGELOG.md](https://github.com/lelabdev/rune-scroller/blob/main/lib/CHANGELOG.md)
+- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
 
 ---
 
@@ -596,18 +341,4 @@ MIT © [ludoloops](https://github.com/ludoloops)
 
 ---
 
-## 🤝 Contributing
-
-Contributions welcome! Please open an issue or PR on GitHub.
-
-```bash
-# Development
-bun install
-bun run dev
-bun test
-bun run build
-```
-
----
-
 Made with ❤️ by [LeLab.dev](https://lelab.dev)