rune-scroller 2.2.2 → 3.0.1

package/README.md

@@ -4,7 +4,9 @@
 	<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**
@@ -20,191 +22,263 @@
 
 ---
 
-## ✨ Features
-
-- **5.7KB gzipped** (JS+CSS) - Minimal overhead
-- **Zero dependencies** - Pure Svelte 5 + IntersectionObserver
-- **14 animations** - Fade, Zoom, Flip, Slide, Bounce
-- **TypeScript support** - Full type definitions
-- **SSR-ready** - SvelteKit compatible
-- **GPU-accelerated** - Pure CSS transforms
-- **Accessible** - Respects `prefers-reduced-motion`
-
----
+## 🚀 Quick Start
 
-## 📦 Installation
+### Any framework — Svelte, React, Vue, Angular, Vanilla JS
 
 ```bash
 npm install rune-scroller
 ```
 
----
+```js
+import AOS from "rune-scroller/aos";
+AOS.init();
+```
 
-## 🚀 Quick Start
+```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.
+
+### 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>
+<div use:rs={{ animation: 'fade-up' }}>Animates on scroll</div>
+```
 
-<!-- With custom duration -->
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1500 }}>
-	<div class="card">Smooth fade and slide</div>
-</div>
+### React
 
-<!-- Repeat on every scroll -->
-<div use:runeScroller={{ animation: 'bounce-in', repeat: true }}>
-	<button>Bounces on every scroll</button>
-</div>
-```
+````jsx
+import { useEffect } from "react";
+### React (not tested — should work)
 
----
+```jsx
+import { useEffect } from 'react';
+import AOS from 'rune-scroller/aos';
 
-## 🎨 Available Animations
+function App() {
+	useEffect(() => { AOS.init(); }, []);
+	return (
+		<>
+			<h1 data-aos="fade-down">Welcome</h1>
+			<p data-aos="fade-up" data-aos-delay="200">Subtitle</p>
+		</>
+	);
+}
+````
 
-### Fade (5)
+### Vue (not tested — should work)
 
-- `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
+```vue
+<script setup>
+import { onMounted } from "vue";
+import AOS from "rune-scroller/aos";
+onMounted(() => AOS.init());
+</script>
 
-### Zoom (5)
+<template>
+  <div data-aos="fade-up">Animated</div>
+</template>
+```
 
-- `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
+### Angular (not tested — should work)
 
-### Others (4)
+```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();
+  }
+}
+```
 
-- `flip` - 3D flip on Y-axis
-- `flip-x` - 3D flip on X-axis
-- `slide-rotate` - Slide + rotate 10°
-- `bounce-in` - Bouncy entrance (spring effect)
+```html
+<!-- app.component.html -->
+<div data-aos="fade-up">Animated</div>
+```
 
----
+### CDN (not tested — should work)
 
-## ⚙️ Options
+```html
+<script type="module">
+  import AOS from "https://esm.sh/rune-scroller/aos";
+  AOS.init();
+</script>
 
-```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 = earlier)
-  onVisible?: (element: HTMLElement) => void // Callback when visible
-  sentinelColor?: string // Debug sentinel color (e.g. '#ff6b6b')
-  sentinelId?: string // Custom sentinel ID
-}
+<div data-aos="fade-up">Works without any build step</div>
 ```
 
-### Examples
+---
 
-```svelte
-<!-- Basic -->
-<div use:runeScroller={{ animation: 'zoom-in' }}>Content</div>
+## ✨ Features
 
-<!-- Custom duration -->
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1000 }}>Fast</div>
+- **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
 
-<!-- Repeat mode -->
-<div use:runeScroller={{ animation: 'bounce-in', repeat: true }}>Repeats</div>
+---
 
-<!-- Debug mode -->
-<div use:runeScroller={{ animation: 'fade-in', debug: true }}>Debug</div>
+### AOS vs rune-scroller
 
-<!-- Trigger earlier with negative offset -->
-<div use:runeScroller={{ animation: 'fade-in-up', offset: -200 }}>
-	Triggers 200px before element bottom
-</div>
+|                           | 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                            |
 
-<!-- onVisible callback for analytics -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	onVisible: (el) => {
-		window.gtag?.('event', 'section_viewed', { id: el.id });
-	}
-}}>
-	Tracked section
-</div>
-```
+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.
 
 ---
 
-## 🎯 How It Works
+## 🎨 Available Animations (30)
 
-**Sentinel-based triggering:**
+### Fade (10)
 
-1. Invisible 1px sentinel created below your element
-2. When sentinel enters viewport, animation triggers
-3. Uses native IntersectionObserver for performance
-4. Pure CSS animations (GPU-accelerated)
-5. ResizeObserver auto-repositions sentinel
+- `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
 
-**Why sentinels?**
+### Zoom (10)
 
-- Accurate timing across all screen sizes
-- No complex offset calculations
-- Works with animated elements (transforms don't affect observer)
+- `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
 
----
+### Slide (4)
 
-## 🌐 SSR Compatibility
+- `slide-up` / `slide-down` / `slide-left` / `slide-right` — Slide from off-screen
 
-Works seamlessly with SvelteKit:
+### Flip (4)
 
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script>
-	import runeScroller from 'rune-scroller';
-	let { children } = $props();
-</script>
+- `flip-left` / `flip-right` — 3D flip on Y-axis
+- `flip-up` / `flip-down` — 3D flip on X-axis
 
-{@render children()}
+### Special (2)
+
+- `slide-rotate` — Slide + rotate
+- `bounce-in` — Bouncy spring entrance
+
+### Customizable distance
+
+All animations use the `--rs-distance` CSS variable (default: `100px`):
+
+```html
+<div data-aos="fade-up" style="--rs-distance: 200px">Farther slide</div>
 ```
 
 ---
 
-## ♿ Accessibility
+## ⚙️ Options
 
-Respects `prefers-reduced-motion`:
+### 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",
+});
+```
 
-```css
-@media (prefers-reduced-motion: reduce) {
-  .scroll-animate {
-    animation: none !important;
-    opacity: 1 !important;
-    transform: none !important;
-  }
+### Svelte Action options
+
+```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;
 }
 ```
 
 ---
 
+## 🎯 How It Works
+
+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
+
+**No wrapper divs** — the element itself becomes the positioning context. Your flex/grid layouts stay intact.
+
+---
+
+## ♿ Accessibility
+
+Respects `prefers-reduced-motion` — animations are disabled automatically.
+
+---
+
 ## 📚 API Reference
 
 ```typescript
-// Default export
-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 } from "rune-scroller"
+import type { AnimationType, RuneScrollerOptions } from "rune-scroller";
 ```
 
 ---
@@ -215,16 +289,12 @@ import type { AnimationType, RuneScrollerOptions } from "rune-scroller"
 
 ```svelte
 <script>
-	import runeScroller from 'rune-scroller';
+	import rs from 'rune-scroller';
 	const items = ['Item 1', 'Item 2', 'Item 3'];
 </script>
 
 {#each items as item, i}
-	<div use:runeScroller={{
-		animation: 'fade-in-up',
-		duration: 800,
-		style: `--delay: ${i * 100}ms`
-	}}>
+	<div use:rs={{ animation: 'fade-up', duration: 800, delay: i * 100 }}>
 		{item}
 	</div>
 {/each}
@@ -232,19 +302,36 @@ import type { AnimationType, RuneScrollerOptions } from "rune-scroller"
 
 ### Hero Section
 
-```svelte
-<h1 use:runeScroller={{ animation: 'fade-in-down', duration: 1000 }}>Welcome</h1>
-<p use:runeScroller={{ animation: 'fade-in-up', duration: 1200 }}>Subtitle</p>
-<button use:runeScroller={{ animation: 'zoom-in', duration: 800 }}>Get Started</button>
+```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>
 ```
 
 ---
 
+## 🔄 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**: [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)
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rune-scroller",
-  "version": "2.2.2",
-  "description": "Lightweight, high-performance scroll animations for Svelte 5. 14KB gzipped, zero dependencies.",
+  "version": "3.0.1",
+  "description": "Lightweight scroll animations for Svelte 5. Drop-in AOS replacement. 30 animations, zero dependencies.",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -29,6 +29,9 @@
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./aos": {
+      "default": "./dist/aos.js"
+    },
     "./animations.css": "./dist/animations.css"
   },
   "files": [
@@ -59,7 +62,7 @@
     "@eslint/compat": "^1.4.0",
     "@eslint/js": "^9.36.0",
     "@sveltejs/kit": "^2.43.2",
-    "@sveltejs/package": "^2.5.4",
+    "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.0",
     "@types/node": "^22",
     "eslint": "^9.36.0",

package/dist/animations.css

@@ -1,83 +0,0 @@
-/**
- * Reusable scroll animation styles - Optimized with CSS custom properties
- * Reduces bundle size while maintaining all 14 animations
- */
-
-/* Base animation container with optimized transitions */
-.scroll-animate,
-.animated-element {
-	opacity: 0;
-	transition: opacity var(--duration, 2500ms) linear var(--delay, 0ms),
-		transform var(--duration, 2500ms) cubic-bezier(0.34, 1.56, 0.64, 1) var(--delay, 0ms);
-	transform: perspective(1000px) translate(var(--tx, 0), var(--ty, 0)) scale(var(--scale, 1)) rotateX(var(--rx, 0deg)) rotateY(var(--ry, 0deg)) rotate(var(--rotate, 0deg));
-}
-
-.scroll-animate.is-visible,
-.animated-element.is-visible {
-	opacity: 1 !important;
-	will-change: transform, opacity;
-	transform: perspective(1000px) translate(var(--tx, 0), var(--ty, 0)) scale(var(--scale, 1)) rotateX(var(--rx, 0deg)) rotateY(var(--ry, 0deg)) rotate(var(--rotate, 0deg));
-}
-
-/* Initial state - transform values before animation */
-[data-animation='fade-in'] { --tx: 0; --ty: 0; }
-[data-animation='fade-in-up'] { --ty: var(--translate-distance, 300px); }
-[data-animation='fade-in-down'] { --ty: calc(-1 * var(--translate-distance, 300px)); }
-[data-animation='fade-in-left'] { --tx: calc(-1 * var(--translate-distance, 300px)); }
-[data-animation='fade-in-right'] { --tx: var(--translate-distance, 300px); }
-
-[data-animation='zoom-in'] { --scale: 0.3; }
-[data-animation='zoom-out'] { --scale: 2; }
-[data-animation='zoom-in-up'] { --scale: 0.5; --ty: var(--translate-distance, 300px); }
-[data-animation='zoom-in-left'] { --scale: 0.5; --tx: calc(-1 * var(--translate-distance, 300px)); }
-[data-animation='zoom-in-right'] { --scale: 0.5; --tx: var(--translate-distance, 300px); }
-
-[data-animation='flip'] { --ry: 90deg; }
-[data-animation='flip-x'] { --rx: 90deg; }
-
-[data-animation='slide-rotate'] { --tx: calc(-1 * var(--translate-distance, 300px)); --rotate: -45deg; }
-[data-animation='bounce-in'] { --scale: 0; }
-
-/* Visible state - reset transform values to final position */
-[data-animation='fade-in-up'].is-visible { --ty: 0; }
-[data-animation='fade-in-down'].is-visible { --ty: 0; }
-[data-animation='fade-in-left'].is-visible { --tx: 0; }
-[data-animation='fade-in-right'].is-visible { --tx: 0; }
-
-[data-animation='zoom-in'].is-visible { --scale: 1; }
-[data-animation='zoom-out'].is-visible { --scale: 1; }
-[data-animation='zoom-in-up'].is-visible { --scale: 1; --ty: 0; }
-[data-animation='zoom-in-left'].is-visible { --scale: 1; --tx: 0; }
-[data-animation='zoom-in-right'].is-visible { --scale: 1; --tx: 0; }
-
-[data-animation='flip'].is-visible { --ry: 0deg; }
-[data-animation='flip-x'].is-visible { --rx: 0deg; }
-
-[data-animation='slide-rotate'].is-visible { --tx: 0; --rotate: 0deg; }
-
-@keyframes bounce {
-	0% { transform: scale(0); }
-	50% { transform: scale(1.1); }
-	100% { transform: scale(1); }
-}
-
-/* Bounce animation - special case with keyframes */
-[data-animation='bounce-in'].is-visible {
-	animation: bounce var(--duration, 1500ms) cubic-bezier(0.68, -0.55, 0.265, 1.55);
-	animation-delay: var(--delay, 0ms);
-}
-
-/* Accessibility: Respect user's motion preferences */
-@media (prefers-reduced-motion: reduce) {
-	.scroll-animate,
-	.animated-element {
-		transition: none;
-		animation: none !important;
-	}
-
-	.scroll-animate.is-visible,
-	.animated-element.is-visible {
-		opacity: 1;
-		transform: none !important;
-	}
-}

package/dist/animations.d.ts

@@ -1,18 +0,0 @@
-/**
- * Calculate rootMargin for IntersectionObserver from offset or custom rootMargin
- *
- * @param {number} [offset] - Viewport offset (0-100). 0 = bottom of viewport touches top of element, 100 = top of viewport touches top of element
- * @param {string} [rootMargin] - Custom rootMargin string (takes precedence over offset)
- * @returns {string} rootMargin string for IntersectionObserver
- */
-export function calculateRootMargin(offset?: number, rootMargin?: string): string;
-/**
- * Animation utilities
- * Type definitions have been moved to types.js for single source of truth
- */
-/**
- * All available animation types in the library
- * Useful for programmatic access and validation
- * @type {readonly string[]}
- */
-export const ANIMATION_TYPES: readonly string[];

package/dist/animations.js

@@ -1,38 +0,0 @@
-/**
- * Animation utilities
- * Type definitions have been moved to types.js for single source of truth
- */
-
-/**
- * All available animation types in the library
- * Useful for programmatic access and validation
- * @type {readonly string[]}
- */
-export const ANIMATION_TYPES = [
-	'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'
-];
-
-/**
- * Calculate rootMargin for IntersectionObserver from offset or custom rootMargin
- *
- * @param {number} [offset] - Viewport offset (0-100). 0 = bottom of viewport touches top of element, 100 = top of viewport touches top of element
- * @param {string} [rootMargin] - Custom rootMargin string (takes precedence over offset)
- * @returns {string} rootMargin string for IntersectionObserver
- */
-export function calculateRootMargin(offset, rootMargin) {
-	return rootMargin ??
-		(offset !== undefined ? `-${100 - offset}% 0px -${offset}% 0px` : '-10% 0px -10% 0px');
-}

package/dist/dom-utils.d.ts

@@ -1,30 +0,0 @@
-/**
- * @param {HTMLElement} element
- * @param {number} [duration]
- * @param {number} [delay=0]
- */
-export function setCSSVariables(element: HTMLElement, duration?: number, delay?: number): void;
-/**
- * @param {HTMLElement} element
- * @param {import('./types.js').AnimationType} animation
- */
-export function setupAnimationElement(element: HTMLElement, animation: import("./types.js").AnimationType): void;
-/**
- * @param {HTMLElement} element
- * @param {boolean} [debug=false]
- * @param {number} [offset=0]
- * @param {string} [sentinelColor='#00e0ff']
- * @param {string} [debugLabel]
- * @param {string} [sentinelId]
- * @returns {{ element: HTMLElement, id: string }}
- */
-export function createSentinel(element: HTMLElement, debug?: boolean, offset?: number, sentinelColor?: string, debugLabel?: string, sentinelId?: string): {
-    element: HTMLElement;
-    id: string;
-};
-/**
- * Check if CSS animations are loaded and warn if not (dev only)
- * Uses cache to avoid expensive getComputedStyle() on every element creation
- * @returns {boolean} True if CSS appears to be loaded
- */
-export function checkAndWarnIfCSSNotLoaded(): boolean;

package/dist/dom-utils.js

@@ -1,112 +0,0 @@
-/**
- * Global counter for auto-generating sentinel IDs
- * @type {number}
- */
-let sentinelCounter = 0;
-
-/**
- * Cache to check CSS only once per page load
- * Avoids expensive getComputedStyle() calls
- * @type {boolean | null}
- */
-let cssCheckResult = null;
-
-/**
- * @param {HTMLElement} element
- * @param {number} [duration]
- * @param {number} [delay=0]
- */
-export function setCSSVariables(element, duration, delay = 0) {
-	if (duration !== undefined) {
-		element.style.setProperty('--duration', `${duration}ms`);
-	}
-	element.style.setProperty('--delay', `${delay}ms`);
-}
-
-/**
- * @param {HTMLElement} element
- * @param {import('./types.js').AnimationType} animation
- */
-export function setupAnimationElement(element, animation) {
-	element.classList.add('scroll-animate');
-	element.setAttribute('data-animation', animation);
-}
-
-/**
- * @param {HTMLElement} element
- * @param {boolean} [debug=false]
- * @param {number} [offset=0]
- * @param {string} [sentinelColor='#00e0ff']
- * @param {string} [debugLabel]
- * @param {string} [sentinelId]
- * @returns {{ element: HTMLElement, id: string }}
- */
-export function createSentinel(element, debug = false, offset = 0, sentinelColor = '#00e0ff', debugLabel = '', sentinelId) {
-	const sentinel = document.createElement('div');
-	// Use offsetHeight instead of getBoundingClientRect for accurate dimensions
-	// getBoundingClientRect returns transformed dimensions (affected by scale, etc)
-	// offsetHeight returns actual element height independent of CSS transforms
-	const elementHeight = element.offsetHeight;
-	const sentinelTop = elementHeight + offset;
-
-	// Generate auto-ID if not provided
-	if (!sentinelId) {
-		sentinelCounter++;
-		sentinelId = `sentinel-${sentinelCounter}`;
-	}
-
-	// Always set to data-sentinel-id attribute
-	sentinel.setAttribute('data-sentinel-id', sentinelId);
-
-	if (debug) {
-		sentinel.style.cssText =
-			`position:absolute;top:${sentinelTop}px;left:0;width:100%;height:3px;background:${sentinelColor};margin:0;padding:2px 4px;box-sizing:border-box;z-index:999;pointer-events:none;display:flex;align-items:center;font-size:10px;color:#000;font-weight:bold;white-space:nowrap;overflow:hidden;text-overflow:ellipsis`;
-		sentinel.setAttribute('data-sentinel-debug', 'true');
-		// Show ID in debug mode (or debugLabel if provided)
-		if (debugLabel) {
-			sentinel.textContent = debugLabel;
-		} else {
-			sentinel.textContent = sentinelId;
-		}
-	} else {
-		sentinel.style.cssText =
-			`position:absolute;top:${sentinelTop}px;left:0;width:100%;height:1px;visibility:hidden;margin:0;padding:0;box-sizing:border-box;pointer-events:none`;
-	}
-
-	return { element: sentinel, id: sentinelId };
-}
-
-/**
- * Check if CSS animations are loaded and warn if not (dev only)
- * Uses cache to avoid expensive getComputedStyle() on every element creation
- * @returns {boolean} True if CSS appears to be loaded
- */
-export function checkAndWarnIfCSSNotLoaded() {
-	if (typeof document === 'undefined') return false;
-	if (process.env.NODE_ENV === 'production') return true;
-
-	// Return cached result if already checked (avoids expensive reflows)
-	if (cssCheckResult !== null) return cssCheckResult;
-
-	// Try to detect if animations.css is loaded by checking for animation classes
-	const test = document.createElement('div');
-	test.className = 'scroll-animate is-visible';
-	test.style.position = 'absolute';
-	test.style.opacity = '0';
-	document.body.appendChild(test);
-	const computed = getComputedStyle(test);
-	const hasAnimation = computed.animation !== 'none' && computed.animation !== '';
-	test.remove();
-
-	if (!hasAnimation) {
-		console.warn(
-			'[rune-scroller] CSS animations not found. Make sure to import the animations:\n' +
-			'  import "rune-scroller/animations.css";\n' +
-			'Documentation: https://github.com/lelabdev/rune-scroller#installation'
-		);
-	}
-
-	// Cache the result for future calls
-	cssCheckResult = hasAnimation;
-	return hasAnimation;
-}

package/dist/index.d.ts

@@ -1,5 +0,0 @@
-export default runeScroller;
-export { runeScroller };
-export { calculateRootMargin } from "./animations.js";
-import { runeScroller } from './runeScroller.js';
-export { useIntersection, useIntersectionOnce } from "./useIntersection.svelte.js";

package/dist/index.js

@@ -1,23 +0,0 @@
-/**
- * Rune Scroller - Lightweight scroll animations for Svelte 5
- *
- * Main entry point exporting all public APIs
- *
- * @module rune-scroller
- */
-
-// Import CSS animations automatically
-import './animations.css';
-
-// Main action (default export - recommended)
-import { runeScroller } from './runeScroller.js';
-export default runeScroller;
-export { runeScroller };
-
-
-
-// Composables
-export { useIntersection, useIntersectionOnce } from './useIntersection.svelte.js';
-
-// Utilities
-export { calculateRootMargin } from './animations.js';

package/dist/observer-utils.d.ts

@@ -1,21 +0,0 @@
-/**
- * Shared IntersectionObserver utility functions
- * Reduces code duplication between action implementations
- */
-/**
- * @param {HTMLElement} target
- * @param {IntersectionObserverCallback} callback
- * @param {IntersectionObserverInit} options
- * @returns {{ observer: IntersectionObserver, isConnected: boolean }}
- */
-export function createManagedObserver(target: HTMLElement, callback: IntersectionObserverCallback, options: IntersectionObserverInit): {
-    observer: IntersectionObserver;
-    isConnected: boolean;
-};
-/**
- * @param {IntersectionObserver} observer
- * @param {{ isConnected: boolean }} state
- */
-export function disconnectObserver(observer: IntersectionObserver, state: {
-    isConnected: boolean;
-}): void;

package/dist/observer-utils.js

@@ -1,31 +0,0 @@
-/**
- * Shared IntersectionObserver utility functions
- * Reduces code duplication between action implementations
- */
-
-/**
- * @param {HTMLElement} target
- * @param {IntersectionObserverCallback} callback
- * @param {IntersectionObserverInit} options
- * @returns {{ observer: IntersectionObserver, isConnected: boolean }}
- */
-export function createManagedObserver(target, callback, options) {
-	const observer = new IntersectionObserver(callback, options);
-	observer.observe(target);
-
-	return {
-		observer,
-		isConnected: true
-	};
-}
-
-/**
- * @param {IntersectionObserver} observer
- * @param {{ isConnected: boolean }} state
- */
-export function disconnectObserver(observer, state) {
-	if (state.isConnected && observer) {
-		observer.disconnect();
-		state.isConnected = false;
-	}
-}

package/dist/runeScroller.d.ts

@@ -1,9 +0,0 @@
-/**
- * @param {HTMLElement} element
- * @param {import('./types.js').RuneScrollerOptions} [options]
- * @returns {{ update: (newOptions?: import('./types.js').RuneScrollerOptions) => void, destroy: () => void }}
- */
-export function runeScroller(element: HTMLElement, options?: import("./types.js").RuneScrollerOptions): {
-    update: (newOptions?: import("./types.js").RuneScrollerOptions) => void;
-    destroy: () => void;
-};

package/dist/runeScroller.js

@@ -1,166 +0,0 @@
-import { setCSSVariables, setupAnimationElement, createSentinel, checkAndWarnIfCSSNotLoaded } from './dom-utils.js';
-import { createManagedObserver, disconnectObserver } from './observer-utils.js';
-import { ANIMATION_TYPES } from './animations.js';
-
-/**
- * @param {HTMLElement} element
- * @param {import('./types.js').RuneScrollerOptions} [options]
- * @returns {{ update: (newOptions?: import('./types.js').RuneScrollerOptions) => void, destroy: () => void }}
- */
-export function runeScroller(element, options) {
-	// SSR Guard: Return no-op action when running on server
-	if (typeof window === 'undefined') {
-		return {
-			update: () => {},
-			destroy: () => {}
-		};
-	}
-
-	// Warn if CSS is not loaded (first time only)
-	if (typeof document !== 'undefined') {
-		checkAndWarnIfCSSNotLoaded();
-	}
-
-	// Validate animation type
-	let animation = options?.animation ?? 'fade-in';
-	if (animation && !ANIMATION_TYPES.includes(animation)) {
-		if (process.env.NODE_ENV !== 'production') {
-			console.warn(
-				`[rune-scroller] Invalid animation "${animation}". Using "fade-in" instead. ` +
-				`Valid options: ${ANIMATION_TYPES.join(', ')}`
-			);
-		}
-		animation = 'fade-in';
-	}
-
-	// Initialize opacity: 0 BEFORE adding .scroll-animate class
-	// This ensures the transition applies correctly when .is-visible is added later
-	element.style.opacity = '0';
-
-	// Setup animation classes and CSS variables
-	if (animation) {
-		setupAnimationElement(element, animation);
-	}
-
-	// Set CSS variables for duration
-	if (options?.duration !== undefined) {
-		setCSSVariables(element, options.duration);
-	}
-
-	// Force reflow to ensure transitions are ready
-	void element.offsetHeight;
-
-	// Create a wrapper div around the element to position the sentinel
-	const wrapper = document.createElement('div');
-	wrapper.style.cssText = 'position:relative;display:block;width:100%;margin:0;padding:0;box-sizing:border-box';
-	element.insertAdjacentElement('beforebegin', wrapper);
-	wrapper.appendChild(element);
-
-	// Create the invisible sentinel (or visible if debug=true)
-	// Positioned absolutely relative to the wrapper
-	const sentinelResult = createSentinel(
-		element,
-		options?.debug,
-		options?.offset,
-		options?.sentinelColor,
-		options?.debugLabel,
-		options?.sentinelId
-	);
-	const sentinel = sentinelResult.element;
-	const sentinelId = sentinelResult.id;
-
-	// Add sentinel ID to element (either provided or auto-generated)
-	element.setAttribute('data-sentinel-id', sentinelId);
-
-	wrapper.appendChild(sentinel);
-
-	// Observe the sentinel with cleanup tracking
-	const state = { isConnected: true };
-	let currentSentinel = sentinel;
-	let resizeObserver;
-	let intersectionObserver;
-
-	const { observer } = createManagedObserver(
-		sentinel,
-		(entries) => {
-			const isIntersecting = entries[0].isIntersecting;
-			if (isIntersecting) {
-				// Add the is-visible class to trigger animation
-				element.classList.add('is-visible');
-				// Call onVisible callback if provided
-				options?.onVisible?.(element);
-				// Disconnect if not in repeat mode
-				if (!options?.repeat) {
-					disconnectObserver(intersectionObserver, state);
-				}
-			} else if (options?.repeat) {
-				// In repeat mode, remove the class when the sentinel exits
-				element.classList.remove('is-visible');
-			}
-		},
-		{ threshold: 0 }
-	);
-
-	intersectionObserver = observer;
-
-	// Function to recreate sentinel when element is resized
-	const recreateSentinel = () => {
-		const newSentinelResult = createSentinel(
-			element,
-			options?.debug,
-			options?.offset,
-			options?.sentinelColor,
-			options?.debugLabel,
-			sentinelId
-		);
-		const newSentinel = newSentinelResult.element;
-		currentSentinel.replaceWith(newSentinel);
-		currentSentinel = newSentinel;
-		// Update observer to watch the new sentinel
-		intersectionObserver.disconnect();
-		intersectionObserver.observe(newSentinel);
-	};
-
-	// Setup ResizeObserver to handle element resizing
-	if (typeof ResizeObserver !== 'undefined') {
-		resizeObserver = new ResizeObserver(() => {
-			recreateSentinel();
-		});
-		resizeObserver.observe(element);
-	}
-
-	return {
-		update(newOptions) {
-			if (newOptions?.animation) {
-				element.setAttribute('data-animation', newOptions.animation);
-			}
-			if (newOptions?.duration) {
-				setCSSVariables(element, newOptions.duration);
-			}
-			// Update repeat option
-			if (newOptions?.repeat !== undefined && newOptions.repeat !== options?.repeat) {
-				options = { ...options, repeat: newOptions.repeat };
-			}
-			// Update offset and debug if changed
-			if ((newOptions?.offset !== undefined && newOptions.offset !== options?.offset) ||
-				(newOptions?.debug !== undefined && newOptions.debug !== options?.debug)) {
-				options = { ...options, ...newOptions };
-				recreateSentinel();
-			}
-		},
-		destroy() {
-			disconnectObserver(intersectionObserver, state);
-			// Cleanup ResizeObserver
-			if (resizeObserver) {
-				resizeObserver.disconnect();
-			}
-			currentSentinel.remove();
-			// Unwrap element (move it out of wrapper)
-			const parent = wrapper.parentElement;
-			if (parent) {
-				wrapper.insertAdjacentElement('beforebegin', element);
-			}
-			wrapper.remove();
-		}
-	};
-}

package/dist/types.d.ts

@@ -1,78 +0,0 @@
-/**
- * Animation type names available in Rune Scroller
- */
-export 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";
-/**
- * Options for the runeScroller action
- * Sentinel-based scroll animation triggering
- */
-export type RuneScrollerOptions = {
-    /**
-     * - Animation type to apply
-     */
-    animation?: AnimationType | undefined;
-    /**
-     * - Animation duration in milliseconds
-     */
-    duration?: number | undefined;
-    /**
-     * - Repeat animation on every scroll
-     */
-    repeat?: boolean | undefined;
-    /**
-     * - Show sentinel as visible line for debugging
-     */
-    debug?: boolean | undefined;
-    /**
-     * - Sentinel color for debug mode (hex or CSS color)
-     */
-    sentinelColor?: string | undefined;
-    /**
-     * - Unique identifier for sentinel (auto-generated if not provided)
-     */
-    sentinelId?: string | undefined;
-    /**
-     * - Debug label to show on sentinel (e.g., animation name)
-     */
-    debugLabel?: string | undefined;
-    /**
-     * - Offset of sentinel in pixels (negative = above element)
-     */
-    offset?: number | undefined;
-    /**
-     * - Callback fired when animation becomes visible
-     */
-    onVisible?: ((element: HTMLElement) => void) | undefined;
-};
-/**
- * Configuration options for IntersectionObserver
- * Used by useIntersection and useIntersectionOnce composables
- */
-export type IntersectionOptions = {
-    /**
-     * - IntersectionObserver threshold
-     */
-    threshold?: number | number[] | undefined;
-    /**
-     * - Custom margin around root element
-     */
-    rootMargin?: string | undefined;
-    /**
-     * - Root element for intersection observation
-     */
-    root?: Element | null | undefined;
-};
-/**
- * Return type for useIntersection and useIntersectionOnce composables
- * Provides reactive element reference and visibility state
- */
-export type UseIntersectionReturn = {
-    /**
-     * - Reference to the DOM element being observed
-     */
-    element: HTMLElement | null;
-    /**
-     * - Whether the element is currently visible in viewport
-     */
-    isVisible: boolean;
-};

package/dist/types.js

@@ -1,48 +0,0 @@
-/**
- * Centralized type definitions for Rune Scroller library
- * All types are defined here for consistency and ease of maintenance
- */
-
-/**
- * Animation type names available in Rune Scroller
- * @typedef {'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'} AnimationType
- */
-
-/**
- * Options for the runeScroller action
- * Sentinel-based scroll animation triggering
- *
- * @typedef {Object} RuneScrollerOptions
- * @property {AnimationType} [animation='fade-in'] - Animation type to apply
- * @property {number} [duration=2500] - Animation duration in milliseconds
- * @property {boolean} [repeat=false] - Repeat animation on every scroll
- * @property {boolean} [debug=false] - Show sentinel as visible line for debugging
- * @property {string} [sentinelColor='#00e0ff'] - Sentinel color for debug mode (hex or CSS color)
- * @property {string} [sentinelId] - Unique identifier for sentinel (auto-generated if not provided)
- * @property {string} [debugLabel] - Debug label to show on sentinel (e.g., animation name)
- * @property {number} [offset=0] - Offset of sentinel in pixels (negative = above element)
- * @property {(element: HTMLElement) => void} [onVisible] - Callback fired when animation becomes visible
- */
-
-
-
-/**
- * Configuration options for IntersectionObserver
- * Used by useIntersection and useIntersectionOnce composables
- *
- * @typedef {Object} IntersectionOptions
- * @property {number | number[]} [threshold] - IntersectionObserver threshold
- * @property {string} [rootMargin] - Custom margin around root element
- * @property {Element | null} [root] - Root element for intersection observation
- */
-
-/**
- * Return type for useIntersection and useIntersectionOnce composables
- * Provides reactive element reference and visibility state
- *
- * @typedef {Object} UseIntersectionReturn
- * @property {HTMLElement | null} element - Reference to the DOM element being observed
- * @property {boolean} isVisible - Whether the element is currently visible in viewport
- */
-
-export {};

package/dist/useIntersection.svelte.d.ts

@@ -1,11 +0,0 @@
-/**
- * @param {import('./types.js').IntersectionOptions} [options={}]
- * @param {(isVisible: boolean) => void} [onVisible]
- * @returns {import('./types.js').UseIntersectionReturn}
- */
-export function useIntersection(options?: import("./types.js").IntersectionOptions, onVisible?: (isVisible: boolean) => void): import("./types.js").UseIntersectionReturn;
-/**
- * @param {import('./types.js').IntersectionOptions} [options={}]
- * @returns {import('./types.js').UseIntersectionReturn}
- */
-export function useIntersectionOnce(options?: import("./types.js").IntersectionOptions): import("./types.js").UseIntersectionReturn;

package/dist/useIntersection.svelte.js

@@ -1,90 +0,0 @@
-/**
- * Composable for handling IntersectionObserver logic
- * Reduces duplication between animation components
- */
-
-/**
- * @param {import('./types.js').IntersectionOptions} [options={}]
- * @param {((entry: IntersectionObserverEntry, isVisible: boolean) => void) | undefined} onIntersect
- * @param {boolean} [once=false]
- * @returns {import('./types.js').UseIntersectionReturn}
- */
-function createIntersectionObserver(options = {}, onIntersect = undefined, once = false) {
-	const { threshold = 0.5, rootMargin = '-10% 0px -10% 0px', root = null } = options;
-
-	let element = $state(null);
-	let isVisible = $state(false);
-	let hasTriggeredOnce = false;
-	/** @type {IntersectionObserver | null} */
-	let observer = null;
-
-	$effect(() => {
-		if (!element) return;
-
-		observer = new IntersectionObserver(
-			(entries) => {
-				entries.forEach((entry) => {
-					// For once-only behavior, check if already triggered
-					if (once && hasTriggeredOnce) return;
-
-					isVisible = entry.isIntersecting;
-					if (onIntersect) {
-						onIntersect(entry, entry.isIntersecting);
-					}
-
-					// Unobserve after first trigger if once=true
-					if (once && entry.isIntersecting) {
-						hasTriggeredOnce = true;
-						observer?.unobserve(entry.target);
-					}
-				});
-			},
-			{
-				threshold,
-				rootMargin,
-				root
-			}
-		);
-
-		observer.observe(element);
-
-		return () => {
-			observer?.disconnect();
-		};
-	});
-
-	return {
-		get element() {
-			return element;
-		},
-		set element(value) {
-			element = value;
-		},
-		get isVisible() {
-			return isVisible;
-		}
-	};
-}
-
-/**
- * @param {import('./types.js').IntersectionOptions} [options={}]
- * @param {(isVisible: boolean) => void} [onVisible]
- * @returns {import('./types.js').UseIntersectionReturn}
- */
-export function useIntersection(options = {}, onVisible) {
-	return createIntersectionObserver(
-		options,
-		(_entry, isVisible) => {
-			onVisible?.(isVisible);
-		},
-		false
-	);
-}
-
-/**
- * @param {import('./types.js').IntersectionOptions} [options={}]
- * @returns {import('./types.js').UseIntersectionReturn}
- */
-export function useIntersectionOnce(options = {}) {
-	return createIntersectionObserver(options, () => {}, true);
-}