rune-scroller 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,9 @@
 # ⚡ Rune Scroller
 
+<div align="center">
+	<img src="./logo.png" alt="Rune Scroller Logo" width="200" />
+</div>
+
 **Native Scroll Animations for Svelte 5** — Built with **Svelte 5 Runes** and **IntersectionObserver API**. No external dependencies, pure performance.
 
 > 🚀 **Open Source Project** by **[ludoloops](https://github.com/ludoloops)** at **[LeLab.dev](https://lelab.dev)**
@@ -57,9 +61,7 @@ For a typical SvelteKit app:
 ```
 rune-scroller-lib/
 ├── src/lib/
-│   ├── Rs.svelte                      # Main animation component (one-time or repeat)
-│   ├── BaseAnimated.svelte            # Base animation implementation
-│   ├── runeScroller.svelte.ts         # Sentinel-based animation action (recommended)
+│   ├── runeScroller.svelte.ts         # Main animation action (sentinel-based)
 │   ├── useIntersection.svelte.ts      # IntersectionObserver composables
 │   ├── animate.svelte.ts              # Animation action for direct DOM control
 │   ├── animations.ts                  # Animation configuration & validation
@@ -92,115 +94,54 @@ pnpm add rune-scroller
 yarn add rune-scroller
 ```
 
-### Basic Usage with `Rs` Component
+### Basic Usage with `runeScroller` Action
 
-The `Rs` component is the main component for scroll animations. Use the `repeat` prop to control animation behavior:
+Use the `runeScroller` action with the `use:` directive for sentinel-based animation triggering:
 
 ```svelte
 <script>
-	import Rs from 'rune-scroller';
-	import 'rune-scroller/animations.css';
+	import runeScroller from 'rune-scroller';
 </script>
 
-<!-- Play animation once when element enters viewport (default) -->
-<Rs animation="fade-in">
-	<div class="card">
-		<h2>Hello World</h2>
-		<p>This element fades in once</p>
-	</div>
-</Rs>
-
-<!-- Repeat animation every time element enters viewport -->
-<Rs animation="zoom-in" repeat>
-	<div class="card">
-		<h2>Repeating Animation</h2>
-		<p>This triggers each time you scroll past it</p>
-	</div>
-</Rs>
-```
-
-### In SvelteKit/Local Development
+<!-- Simple fade in animation -->
+<div use:runeScroller={{ animation: 'fade-in' }}>
+	<h2>Animated Heading</h2>
+	<p>Animates when scrolled into view</p>
+</div>
 
-```svelte
-<script>
-	import Rs from '$lib/Rs.svelte';
-	import '$lib/animations.css';
-</script>
+<!-- With custom duration -->
+<div use:runeScroller={{ animation: 'fade-in-up', duration: 1500 }}>
+	<div class="card">Smooth fade and slide</div>
+</div>
 
-<Rs animation="fade-in-up" duration={1000} delay={200}>
-	<div class="card">
-		<h2>Animated Content</h2>
-	</div>
-</Rs>
+<!-- Repeat animation on every scroll -->
+<div use:runeScroller={{ animation: 'bounce-in', duration: 800, repeat: true }}>
+	<button>Bounces on every scroll</button>
+</div>
 ```
 
-### API Overview
+### How It Works
 
-The `Rs` component is the unified API for all scroll animations:
+The `runeScroller` action uses an invisible **sentinel element** for precise animation triggering:
 
-```svelte
-<!-- Animation plays once (default) -->
-<Rs animation="fade-in">Content</Rs>
-
-<!-- Animation repeats on every scroll -->
-<Rs animation="fade-in" repeat>Content</Rs>
-
-<!-- Customize timing -->
-<Rs animation="zoom-in" duration={1200} delay={300}>
-	Content
-</Rs>
-
-<!-- Use with any HTML attribute -->
-<Rs animation="bounce-in" class="my-class" data-test="value">
-	Content
-</Rs>
-```
+1. **Sentinel Creation** - An invisible sentinel is created and positioned **absolutely** at your element's bottom
+2. **Parent Context** - Parent element automatically gets `position: relative` if needed (no visual impact)
+3. **Viewport Detection** - When the sentinel enters the viewport, it triggers the animation
+4. **Fixed Positioning** - The sentinel stays fixed while your element animates, ensuring accurate timing
+5. **Invisible by Default** - The sentinel is 1px tall and invisible (`visibility:hidden`)
+6. **Debug Mode** - Add `debug: true` to see the sentinel as a visible cyan line (useful for development)
 
 ---
 
-## 🎯 Sentinel-Based Animation Triggering with `runeScroller`
-
-For more precise control over animation timing, use the `runeScroller` action. This approach uses an invisible **sentinel element** positioned below your content to trigger animations at exactly the right moment.
+## 🎯 Sentinel-Based Animation Triggering
 
 ### Why Sentinels?
 
-- **Accurate Timing** - Instead of triggering when the element enters, sentinel triggers slightly earlier
+- **Accurate Timing** - Triggers at the perfect moment for smooth animations
 - **Consistent Behavior** - Same timing across all screen sizes and content heights
 - **Simple API** - No complex offset calculations needed
 - **Performance** - Minimal overhead, pure CSS animations
-
-### How Sentinels Work
-
-1. An invisible 20px sentinel element is automatically placed **below** your animated element
-2. When the sentinel enters the viewport, it triggers the animation
-3. This ensures content animates in perfectly as it becomes visible
-
-```svelte
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1000 }}>
-  <!-- Your content here -->
-  <!-- Invisible sentinel is automatically placed below -->
-</div>
-```
-
-### Basic Usage
-
-```svelte
-<script>
-	import { runeScroller } from 'rune-scroller';
-	import 'rune-scroller/animations.css';
-</script>
-
-<!-- Simple fade in with sentinel triggering -->
-<div use:runeScroller={{ animation: 'fade-in' }}>
-	<h2>Animated Heading</h2>
-	<p>Animates when sentinel enters viewport</p>
-</div>
-
-<!-- With duration control -->
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1500 }}>
-	<div class="card">Smooth animation</div>
-</div>
-```
+- **Reliable** - Automatic sentinel placement handles edge cases
 
 ### Sentinel-Based Examples
 
@@ -208,7 +149,7 @@ For more precise control over animation timing, use the `runeScroller` action. T
 
 ```svelte
 <script>
-	import { runeScroller } from 'rune-scroller';
+	import runeScroller from 'rune-scroller';
 </script>
 
 <div class="grid">
@@ -247,95 +188,6 @@ interface RuneScrollerOptions {
 }
 ```
 
-### Comparing: `Rs` Component vs `runeScroller` Action
-
-| Feature | `Rs` Component | `runeScroller` Action |
-|---------|---|---|
-| **Usage** | `<Rs>` wrapper | `use:` directive |
-| **Triggering** | IntersectionObserver on element | IntersectionObserver on sentinel |
-| **Timing Control** | offset, threshold props | Automatic sentinel placement |
-| **Repeat Support** | Yes (via `repeat` prop) | Yes (via `repeat` option) |
-| **Best For** | Complex layouts, component isolation | Direct DOM control, simple/mixed elements |
-
----
-
-## ⚙️ Component Props
-
-### Rs Component
-
-```typescript
-interface RsProps {
-	animation?: string; // Animation type (default: 'fade-in')
-	threshold?: number; // Visibility threshold (default: 0.5)
-	offset?: number; // Trigger offset 0-100% (optional, uses default if not set)
-	rootMargin?: string; // Observer margin (overrides offset if set)
-	duration?: number; // Duration in ms (default: 800)
-	delay?: number; // Delay in ms (default: 0)
-	repeat?: boolean; // Repeat animation on every scroll (default: false)
-	children: Snippet; // Content to animate
-	[key: string]: any; // Accepts any HTML attributes (e.g., data-testid, class, etc.)
-}
-```
-
-#### `offset` Prop (Optional)
-
-Controls when the animation triggers as the element scrolls into view. If not specified, uses default behavior (`-10% 0px -10% 0px`).
-
-- `offset={0}` — Triggers when element touches bottom of screen
-- `offset={50}` — Triggers at middle of screen
-- `offset={100}` — Triggers when element reaches top of screen
-- **Not set** — Uses default behavior (triggers in middle ~80% band)
-
-**Examples:**
-
-```svelte
-<!-- Early trigger (bottom of screen) -->
-<Rs animation="fade-in-up" offset={0}>
-	<div class="card">Animates early</div>
-</Rs>
-
-<!-- Late trigger (top of screen) -->
-<Rs animation="fade-in-up" offset={100}>
-	<div class="card">Animates late</div>
-</Rs>
-
-<!-- Custom timing -->
-<Rs animation="fade-in-up" offset={75}>
-	<div class="card">Animates at 75%</div>
-</Rs>
-
-<!-- Repeat animation on every scroll -->
-<Rs animation="fade-in-up" offset={50} repeat>
-	<div class="card">Animates every time</div>
-</Rs>
-```
-
-**Full example with all props:**
-
-```svelte
-<Rs
-	animation="fade-in-up"
-	duration={1200}
-	delay={300}
-	threshold={0.8}
-	offset={25}
-	repeat={false}
-	data-testid="custom-animation"
->
-	<div class="card">
-		<h2>Custom Timing</h2>
-		<p>Duration: 1200ms, Delay: 300ms, Threshold: 80%, Offset: 25%</p>
-	</div>
-</Rs>
-```
-
-#### Repeat Behavior
-
-Use the `repeat` prop to control animation behavior:
-
-- `repeat={false}` (default) - Animation plays **once** when element enters viewport
-- `repeat={true}` - Animation **repeats** every time element enters viewport
-
 ---
 
 ## 🎨 All Animations with Examples
@@ -347,12 +199,14 @@ Use the `repeat` prop to control animation behavior:
 Simple opacity fade from transparent to visible.
 
 ```svelte
-<Rs animation="fade-in">
-	<div class="card">
-		<h2>Fade In</h2>
-		<p>Simple fade entrance</p>
-	</div>
-</Rs>
+<script>
+	import runeScroller from 'rune-scroller';
+</script>
+
+<div use:runeScroller={{ animation: 'fade-in' }}>
+	<h2>Fade In</h2>
+	<p>Simple fade entrance</p>
+</div>
 ```
 
 #### `fade-in-up`
@@ -360,12 +214,10 @@ Simple opacity fade from transparent to visible.
 Fades in while moving up 100px.
 
 ```svelte
-<Rs animation="fade-in-up">
-	<div class="card">
-		<h2>Fade In Up</h2>
-		<p>Rises from below</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'fade-in-up' }}>
+	<h2>Fade In Up</h2>
+	<p>Rises from below</p>
+</div>
 ```
 
 #### `fade-in-down`
@@ -373,12 +225,10 @@ Fades in while moving up 100px.
 Fades in while moving down 100px.
 
 ```svelte
-<Rs animation="fade-in-down">
-	<div class="card">
-		<h2>Fade In Down</h2>
-		<p>Descends from above</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'fade-in-down' }}>
+	<h2>Fade In Down</h2>
+	<p>Descends from above</p>
+</div>
 ```
 
 #### `fade-in-left`
@@ -386,12 +236,10 @@ Fades in while moving down 100px.
 Fades in while moving left 100px.
 
 ```svelte
-<Rs animation="fade-in-left">
-	<div class="card">
-		<h2>Fade In Left</h2>
-		<p>Comes from the right</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'fade-in-left' }}>
+	<h2>Fade In Left</h2>
+	<p>Comes from the right</p>
+</div>
 ```
 
 #### `fade-in-right`
@@ -399,12 +247,10 @@ Fades in while moving left 100px.
 Fades in while moving right 100px.
 
 ```svelte
-<Rs animation="fade-in-right">
-	<div class="card">
-		<h2>Fade In Right</h2>
-		<p>Comes from the left</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'fade-in-right' }}>
+	<h2>Fade In Right</h2>
+	<p>Comes from the left</p>
+</div>
 ```
 
 ---
@@ -416,12 +262,10 @@ Fades in while moving right 100px.
 Scales from 50% to 100% while fading in.
 
 ```svelte
-<Rs animation="zoom-in">
-	<div class="card">
-		<h2>Zoom In</h2>
-		<p>Grows into view</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'zoom-in' }}>
+	<h2>Zoom In</h2>
+	<p>Grows into view</p>
+</div>
 ```
 
 #### `zoom-out`
@@ -429,12 +273,10 @@ Scales from 50% to 100% while fading in.
 Scales from 150% to 100% while fading in.
 
 ```svelte
-<Rs animation="zoom-out">
-	<div class="card">
-		<h2>Zoom Out</h2>
-		<p>Shrinks into view</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'zoom-out' }}>
+	<h2>Zoom Out</h2>
+	<p>Shrinks into view</p>
+</div>
 ```
 
 #### `zoom-in-up`
@@ -442,12 +284,10 @@ Scales from 150% to 100% while fading in.
 Scales from 50% while translating up 50px.
 
 ```svelte
-<Rs animation="zoom-in-up">
-	<div class="card">
-		<h2>Zoom In Up</h2>
-		<p>Grows while moving up</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'zoom-in-up' }}>
+	<h2>Zoom In Up</h2>
+	<p>Grows while moving up</p>
+</div>
 ```
 
 #### `zoom-in-left`
@@ -455,12 +295,10 @@ Scales from 50% while translating up 50px.
 Scales from 50% while translating left 50px.
 
 ```svelte
-<Rs animation="zoom-in-left">
-	<div class="card">
-		<h2>Zoom In Left</h2>
-		<p>Grows while moving left</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'zoom-in-left' }}>
+	<h2>Zoom In Left</h2>
+	<p>Grows while moving left</p>
+</div>
 ```
 
 #### `zoom-in-right`
@@ -468,12 +306,10 @@ Scales from 50% while translating left 50px.
 Scales from 50% while translating right 50px.
 
 ```svelte
-<Rs animation="zoom-in-right">
-	<div class="card">
-		<h2>Zoom In Right</h2>
-		<p>Grows while moving right</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'zoom-in-right' }}>
+	<h2>Zoom In Right</h2>
+	<p>Grows while moving right</p>
+</div>
 ```
 
 ---
@@ -485,12 +321,10 @@ Scales from 50% while translating right 50px.
 3D rotation on Y axis (left to right).
 
 ```svelte
-<Rs animation="flip">
-	<div class="card">
-		<h2>Flip</h2>
-		<p>Rotates on Y axis</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'flip' }}>
+	<h2>Flip</h2>
+	<p>Rotates on Y axis</p>
+</div>
 ```
 
 #### `flip-x`
@@ -498,12 +332,10 @@ Scales from 50% while translating right 50px.
 3D rotation on X axis (top to bottom).
 
 ```svelte
-<Rs animation="flip-x">
-	<div class="card">
-		<h2>Flip X</h2>
-		<p>Rotates on X axis</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'flip-x' }}>
+	<h2>Flip X</h2>
+	<p>Rotates on X axis</p>
+</div>
 ```
 
 ---
@@ -515,12 +347,10 @@ Scales from 50% while translating right 50px.
 Slides from left while rotating 45 degrees.
 
 ```svelte
-<Rs animation="slide-rotate">
-	<div class="card">
-		<h2>Slide Rotate</h2>
-		<p>Slides and spins</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'slide-rotate' }}>
+	<h2>Slide Rotate</h2>
+	<p>Slides and spins</p>
+</div>
 ```
 
 ---
@@ -532,30 +362,28 @@ Slides from left while rotating 45 degrees.
 Bouncy entrance with scaling keyframe animation.
 
 ```svelte
-<Rs animation="bounce-in" duration={800}>
-	<div class="card">
-		<h2>Bounce In</h2>
-		<p>Bounces into view</p>
-	</div>
-</Rs>
+<div use:runeScroller={{ animation: 'bounce-in', duration: 800 }}>
+	<h2>Bounce In</h2>
+	<p>Bounces into view</p>
+</div>
 ```
 
 ---
 
-### Compare: Once vs Repeat
+### One-Time vs Repeat Animations
 
-**Same animation, different behavior using the `repeat` prop:**
+Control animation behavior with the `repeat` option:
 
 ```svelte
-<!-- Plays once on scroll down (default) -->
-<Rs animation="fade-in-up">
-	<div class="card">Animates once</div>
-</Rs>
+<!-- Plays once on scroll (default) -->
+<div use:runeScroller={{ animation: 'fade-in-up' }}>
+	Animates once when scrolled into view
+</div>
 
 <!-- Repeats each time you scroll by -->
-<Rs animation="fade-in-up" repeat>
-	<div class="card">Animates on every scroll</div>
-</Rs>
+<div use:runeScroller={{ animation: 'fade-in-up', repeat: true }}>
+	Animates every time you scroll past it
+</div>
 ```
 
 ---
@@ -568,17 +396,17 @@ Animate cards with progressive delays:
 
 ```svelte
 <script>
-	import Rs from '$lib/Rs.svelte';
+	import runeScroller from 'rune-scroller';
 </script>
 
 <div class="grid">
 	{#each items as item, i}
-		<Rs animation="fade-in-up" delay={i * 100}>
+		<div use:runeScroller={{ animation: 'fade-in-up', duration: 800 + i * 100 }}>
 			<div class="card">
 				<h3>{item.title}</h3>
 				<p>{item.description}</p>
 			</div>
-		</Rs>
+		</div>
 	{/each}
 </div>
 ```
@@ -586,40 +414,42 @@ Animate cards with progressive delays:
 ### Mixed Animations
 
 ```svelte
-<Rs animation="fade-in">
-	<section>Content fades in</section>
-</Rs>
+<script>
+	import runeScroller from 'rune-scroller';
+</script>
 
-<Rs animation="slide-rotate">
-	<section>Content slides and rotates</section>
-</Rs>
+<section use:runeScroller={{ animation: 'fade-in' }}>
+	Content fades in
+</section>
+
+<section use:runeScroller={{ animation: 'slide-rotate' }}>
+	Content slides and rotates
+</section>
 
-<Rs animation="zoom-in" repeat>
-	<section>Content zooms in repeatedly</section>
-</Rs>
+<section use:runeScroller={{ animation: 'zoom-in', repeat: true }}>
+	Content zooms in repeatedly
+</section>
 ```
 
 ### Hero Section
 
 ```svelte
 <script>
-	import Rs from '$lib/Rs.svelte';
+	import runeScroller from 'rune-scroller';
 </script>
 
 <section class="hero">
-	<div class="hero-content">
-		<Rs animation="fade-in" delay={0}>
-			<h1>Welcome</h1>
-		</Rs>
-
-		<Rs animation="fade-in" delay={200}>
-			<p>Scroll to reveal more</p>
-		</Rs>
-
-		<Rs animation="zoom-in" delay={400}>
-			<button>Get Started</button>
-		</Rs>
-	</div>
+	<h1 use:runeScroller={{ animation: 'fade-in', duration: 1000 }}>
+		Welcome
+	</h1>
+
+	<p use:runeScroller={{ animation: 'fade-in', duration: 1200 }}>
+		Scroll to reveal more
+	</p>
+
+	<button use:runeScroller={{ animation: 'zoom-in', duration: 1000 }}>
+		Get Started
+	</button>
 </section>
 ```
 
@@ -653,7 +483,7 @@ function runeScroller(
 
 ```svelte
 <script>
-	import { runeScroller } from 'rune-scroller';
+	import runeScroller from 'rune-scroller';
 </script>
 
 <!-- Animation plays once when sentinel enters viewport -->
@@ -675,7 +505,7 @@ function runeScroller(
 
 ```svelte
 <script>
-	import { runeScroller } from 'rune-scroller';
+	import runeScroller from 'rune-scroller';
 </script>
 
 <!-- Fade in once on scroll -->
@@ -713,7 +543,6 @@ function runeScroller(
 - ✅ Consistent timing across layouts
 - ✅ Minimal overhead applications
 - ✅ Both one-time and repeating animations
-- ❌ Complex layout with component isolation (use `Rs` component instead)
 
 ---
 
@@ -789,13 +618,9 @@ function animate(
 2. **dom-utils.svelte.ts** - Reusable DOM manipulation utilities (CSS variables, animation setup, sentinel creation)
 3. **useIntersection.svelte.ts** - IntersectionObserver composables for element visibility detection
 
-**Middle Layer - Base Implementation:**
-4. **animate.svelte.ts** - Action for direct DOM node animation control
-5. **runeScroller.svelte.ts** - **Recommended** - Sentinel-based action for precise animation timing
-6. **BaseAnimated.svelte** - Base component handling intersection observer + animation logic
-
 **Top Layer - Consumer API:**
-7. **Rs.svelte** - Main unified component (supports one-time & repeating via `repeat` prop)
+4. **runeScroller.svelte.ts** - **Recommended** - Sentinel-based action for scroll animation triggering
+5. **animate.svelte.ts** - Alternative action for direct DOM node animation control
 
 **Styles:**
 - **animations.css** - All animation keyframes & styles (14 animations, GPU-accelerated)
@@ -903,6 +728,8 @@ pnpm preview
 
 ## 🔗 Links
 
+- [Live Demo](https://runescroller.lelab.dev/) - Interactive showcase of all animations
+- [npm Package](https://www.npmjs.com/package/rune-scroller) - Install from npm
 - [Svelte 5 Documentation](https://svelte.dev)
 - [IntersectionObserver MDN](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)
 - [LeLab.dev](https://lelab.dev)

package/dist/animate.svelte.d.ts

@@ -1,13 +1,5 @@
 import type { Action } from 'svelte/action';
-import { type AnimationType } from './animations';
-export interface AnimateOptions {
-    animation?: AnimationType;
-    duration?: number;
-    delay?: number;
-    offset?: number;
-    threshold?: number;
-    rootMargin?: string;
-}
+import type { AnimateOptions } from './types';
 /**
  * Svelte action for scroll animations
  * Triggers animation once when element enters viewport

package/dist/animate.svelte.js

@@ -1,4 +1,5 @@
 import { calculateRootMargin } from './animations';
+import { setCSSVariables, setupAnimationElement } from './dom-utils.svelte';
 /**
  * Svelte action for scroll animations
  * Triggers animation once when element enters viewport
@@ -11,17 +12,15 @@ import { calculateRootMargin } from './animations';
  * ```
  */
 export const animate = (node, options = {}) => {
-    const { animation = 'fade-in', duration = 800, delay = 0, offset, threshold = 0, rootMargin } = options;
+    let { animation = 'fade-in', duration = 800, delay = 0, offset, threshold = 0, rootMargin } = options;
     // Calculate rootMargin from offset (0-100%)
-    const finalRootMargin = calculateRootMargin(offset, rootMargin);
-    // Set CSS custom properties for timing
-    node.style.setProperty('--duration', `${duration}ms`);
-    node.style.setProperty('--delay', `${delay}ms`);
-    // Add base animation class and data attribute
-    node.classList.add('scroll-animate');
-    node.setAttribute('data-animation', animation);
+    let finalRootMargin = calculateRootMargin(offset, rootMargin);
+    // Setup animation with utilities
+    setupAnimationElement(node, animation);
+    setCSSVariables(node, duration, delay);
     // Track if animation has been triggered
     let animated = false;
+    let observerConnected = true;
     // Create IntersectionObserver for one-time animation
     const observer = new IntersectionObserver((entries) => {
         entries.forEach((entry) => {
@@ -31,6 +30,7 @@ export const animate = (node, options = {}) => {
                 animated = true;
                 // Stop observing after animation triggers
                 observer.unobserve(node);
+                observerConnected = false;
             }
         });
     }, {
@@ -40,20 +40,40 @@ export const animate = (node, options = {}) => {
     observer.observe(node);
     return {
         update(newOptions) {
-            const { duration: newDuration = 800, delay: newDelay = 0, animation: newAnimation } = newOptions;
+            const { duration: newDuration, delay: newDelay, animation: newAnimation, offset: newOffset, threshold: newThreshold, rootMargin: newRootMargin } = newOptions;
             // Update CSS properties
-            if (newDuration !== duration) {
-                node.style.setProperty('--duration', `${newDuration}ms`);
+            if (newDuration !== undefined) {
+                duration = newDuration;
+                setCSSVariables(node, duration, newDelay ?? delay);
             }
-            if (newDelay !== delay) {
-                node.style.setProperty('--delay', `${newDelay}ms`);
+            if (newDelay !== undefined && newDelay !== delay) {
+                delay = newDelay;
+                setCSSVariables(node, duration, delay);
             }
             if (newAnimation && newAnimation !== animation) {
+                animation = newAnimation;
                 node.setAttribute('data-animation', newAnimation);
             }
+            // Recreate observer if threshold or rootMargin changed
+            if (newThreshold !== undefined || newOffset !== undefined || newRootMargin !== undefined) {
+                if (observerConnected) {
+                    observer.disconnect();
+                    observerConnected = false;
+                }
+                threshold = newThreshold ?? threshold;
+                offset = newOffset ?? offset;
+                rootMargin = newRootMargin ?? rootMargin;
+                finalRootMargin = calculateRootMargin(offset, rootMargin);
+                if (!animated) {
+                    observer.observe(node);
+                    observerConnected = true;
+                }
+            }
         },
         destroy() {
-            observer.disconnect();
+            if (observerConnected) {
+                observer.disconnect();
+            }
         }
     };
 };

package/dist/dom-utils.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { AnimationType } from './animations';
+/**
+ * Set CSS custom properties on an element
+ * @param element - Target DOM element
+ * @param duration - Animation duration in milliseconds
+ * @param delay - Animation delay in milliseconds
+ */
+export declare function setCSSVariables(element: HTMLElement, duration?: number, delay?: number): void;
+/**
+ * Setup animation element with required classes and attributes
+ * @param element - Target DOM element
+ * @param animation - Animation type to apply
+ */
+export declare function setupAnimationElement(element: HTMLElement, animation: AnimationType): void;
+/**
+ * Create sentinel element for observer-based triggering
+ * Positioned absolutely after element, stays fixed while element animates
+ * @param element - Reference element (used to position sentinel at its bottom)
+ * @param debug - If true, shows the sentinel as a visible line for debugging
+ * @returns The created sentinel element
+ */
+export declare function createSentinel(element: HTMLElement, debug?: boolean): HTMLElement;

package/dist/dom-utils.svelte.js

@@ -0,0 +1,46 @@
+/**
+ * Set CSS custom properties on an element
+ * @param element - Target DOM element
+ * @param duration - Animation duration in milliseconds
+ * @param delay - Animation delay in milliseconds
+ */
+export function setCSSVariables(element, duration, delay = 0) {
+    if (duration !== undefined) {
+        element.style.setProperty('--duration', `${duration}ms`);
+    }
+    element.style.setProperty('--delay', `${delay}ms`);
+}
+/**
+ * Setup animation element with required classes and attributes
+ * @param element - Target DOM element
+ * @param animation - Animation type to apply
+ */
+export function setupAnimationElement(element, animation) {
+    element.classList.add('scroll-animate');
+    element.setAttribute('data-animation', animation);
+}
+/**
+ * Create sentinel element for observer-based triggering
+ * Positioned absolutely after element, stays fixed while element animates
+ * @param element - Reference element (used to position sentinel at its bottom)
+ * @param debug - If true, shows the sentinel as a visible line for debugging
+ * @returns The created sentinel element
+ */
+export function createSentinel(element, debug = false) {
+    const sentinel = document.createElement('div');
+    // Get element dimensions to position sentinel at its bottom
+    const rect = element.getBoundingClientRect();
+    const elementHeight = rect.height;
+    if (debug) {
+        // Debug mode: visible primary color line (cyan #00e0ff)
+        sentinel.style.cssText =
+            `position:absolute;top:${elementHeight}px;left:0;right:0;height:3px;background:#00e0ff;margin:0;padding:0;box-sizing:border-box;z-index:999;pointer-events:none`;
+        sentinel.setAttribute('data-sentinel-debug', 'true');
+    }
+    else {
+        // Production: invisible positioned absolutely (no layout impact)
+        sentinel.style.cssText =
+            `position:absolute;top:${elementHeight}px;left:0;right:0;height:1px;visibility:hidden;margin:0;padding:0;box-sizing:border-box;pointer-events:none`;
+    }
+    return sentinel;
+}

package/dist/index.d.ts

@@ -1,9 +1,7 @@
-export { default as rs } from './Rs.svelte';
+export type { RuneScrollerOptions, AnimateOptions, IntersectionOptions, UseIntersectionReturn } from './types';
+export type { AnimationType } from './animations';
+export { runeScroller as default } from './runeScroller.svelte.ts';
+export { default as RuneScroller } from './runeScroller.svelte';
 export { animate } from './animate.svelte';
-export type { AnimateOptions } from './animate.svelte';
-export { runeScroller } from './runeScroller.svelte';
-export type { RuneScrollerOptions } from './runeScroller.svelte';
 export { useIntersection, useIntersectionOnce } from './useIntersection.svelte';
-export type { IntersectionOptions, UseIntersectionReturn } from './useIntersection.svelte';
 export { calculateRootMargin } from './animations';
-export type { AnimationType } from './animations';

package/dist/index.js

@@ -1,8 +1,9 @@
-// Components
-export { default as rs } from './Rs.svelte';
-// Actions
+// Main action (default export)
+export { runeScroller as default } from './runeScroller.svelte.ts';
+// Component
+export { default as RuneScroller } from './runeScroller.svelte';
+// Alternative actions
 export { animate } from './animate.svelte';
-export { runeScroller } from './runeScroller.svelte';
 // Composables
 export { useIntersection, useIntersectionOnce } from './useIntersection.svelte';
 // Utilities

package/dist/runeScroller.svelte.d.ts

@@ -1,29 +1,16 @@
+import type { Snippet } from 'svelte';
 import type { AnimationType } from './animations';
-export interface RuneScrollerOptions {
+interface Props {
     animation?: AnimationType;
+    threshold?: number;
+    rootMargin?: string;
+    offset?: number;
     duration?: number;
+    delay?: number;
     repeat?: boolean;
+    children: Snippet;
+    [key: string]: any;
 }
-/**
- * Action pour animer un élément au scroll avec un sentinel invisible juste en dessous
- * @param element - L'élément à animer
- * @param options - Options d'animation (animation type, duration, et repeat)
- * @returns Objet action Svelte
- *
- * @example
- * ```svelte
- * <!-- Animation une seule fois -->
- * <div use:runeScroller={{ animation: 'fade-in-up', duration: 1000 }}>
- *   Content
- * </div>
- *
- * <!-- Animation répétée à chaque scroll -->
- * <div use:runeScroller={{ animation: 'fade-in-up', duration: 1000, repeat: true }}>
- *   Content
- * </div>
- * ```
- */
-export declare function runeScroller(element: HTMLElement, options?: RuneScrollerOptions): {
-    update(newOptions?: RuneScrollerOptions): void;
-    destroy(): void;
-};
+declare const RuneScroller: import("svelte").Component<Props, {}, "">;
+type RuneScroller = ReturnType<typeof RuneScroller>;
+export default RuneScroller;

package/dist/runeScroller.svelte.js

@@ -1,3 +1,4 @@
+import { setCSSVariables, setupAnimationElement, createSentinel } from './dom-utils.svelte';
 /**
  * Action pour animer un élément au scroll avec un sentinel invisible juste en dessous
  * @param element - L'élément à animer
@@ -18,27 +19,26 @@
  * ```
  */
 export function runeScroller(element, options) {
-    // Setup animation classes et variables CSS si options sont fournies
+    // Setup animation classes et variables CSS
     if (options?.animation || options?.duration) {
-        element.classList.add('scroll-animate');
-        if (options.animation) {
-            element.setAttribute('data-animation', options.animation);
-        }
-        if (options.duration) {
-            element.style.setProperty('--duration', `${options.duration}ms`);
+        setupAnimationElement(element, options.animation);
+        setCSSVariables(element, options.duration);
+    }
+    // Créer le sentinel invisible (ou visible si debug=true)
+    // Sentinel positioned absolutely relative to parent (stays fixed while element animates)
+    const sentinel = createSentinel(element, options?.debug);
+    const parent = element.parentElement;
+    if (parent) {
+        // Ensure parent has position context for absolute positioning
+        const parentPosition = window.getComputedStyle(parent).position;
+        if (parentPosition === 'static') {
+            parent.style.position = 'relative';
         }
-        element.style.setProperty('--delay', '0ms');
+        // Insert sentinel after element, positioned absolutely
+        element.insertAdjacentElement('afterend', sentinel);
     }
-    // Créer le sentinel invisible juste en dessous
-    const sentinel = document.createElement('div');
-    sentinel.style.height = '20px';
-    sentinel.style.margin = '0';
-    sentinel.style.padding = '0';
-    sentinel.style.marginTop = '0.5rem';
-    sentinel.style.visibility = 'hidden';
-    // Insérer le sentinel après l'élément
-    element.parentNode?.insertBefore(sentinel, element.nextSibling);
-    // Observer le sentinel
+    // Observer le sentinel avec cleanup tracking
+    let observerConnected = true;
     const observer = new IntersectionObserver((entries) => {
         const isIntersecting = entries[0].isIntersecting;
         if (isIntersecting) {
@@ -47,6 +47,7 @@ export function runeScroller(element, options) {
             // Déconnecter si pas en mode repeat
             if (!options?.repeat) {
                 observer.disconnect();
+                observerConnected = false;
             }
         }
         else if (options?.repeat) {
@@ -61,7 +62,7 @@ export function runeScroller(element, options) {
                 element.setAttribute('data-animation', newOptions.animation);
             }
             if (newOptions?.duration) {
-                element.style.setProperty('--duration', `${newOptions.duration}ms`);
+                setCSSVariables(element, newOptions.duration);
             }
             // Update repeat option
             if (newOptions?.repeat !== undefined && newOptions.repeat !== options?.repeat) {
@@ -69,7 +70,9 @@ export function runeScroller(element, options) {
             }
         },
         destroy() {
-            observer.disconnect();
+            if (observerConnected) {
+                observer.disconnect();
+            }
             sentinel.remove();
         }
     };

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Centralized type definitions for Rune Scroller library
+ * All types are defined here for consistency and ease of maintenance
+ */
+import type { AnimationType } from './animations';
+/**
+ * Options for the runeScroller action
+ * Sentinel-based scroll animation triggering
+ */
+export interface RuneScrollerOptions {
+    animation?: AnimationType;
+    duration?: number;
+    repeat?: boolean;
+    debug?: boolean;
+}
+/**
+ * Options for the animate action
+ * Direct DOM node animation control with threshold/offset support
+ */
+export interface AnimateOptions {
+    animation?: AnimationType;
+    duration?: number;
+    delay?: number;
+    offset?: number;
+    threshold?: number;
+    rootMargin?: string;
+}
+/**
+ * Configuration options for IntersectionObserver
+ * Used by useIntersection and useIntersectionOnce composables
+ */
+export interface IntersectionOptions {
+    threshold?: number | number[];
+    rootMargin?: string;
+    root?: Element | null;
+}
+/**
+ * Return type for useIntersection and useIntersectionOnce composables
+ * Provides reactive element reference and visibility state
+ */
+export interface UseIntersectionReturn {
+    element: HTMLElement | null;
+    isVisible: boolean;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Centralized type definitions for Rune Scroller library
+ * All types are defined here for consistency and ease of maintenance
+ */
+export {};

package/dist/useIntersection.svelte.d.ts

@@ -1,16 +1,4 @@
-/**
- * Composable for handling IntersectionObserver logic
- * Reduces duplication between animation components
- */
-export interface IntersectionOptions {
-    threshold?: number | number[];
-    rootMargin?: string;
-    root?: Element | null;
-}
-export interface UseIntersectionReturn {
-    element: HTMLElement | null;
-    isVisible: boolean;
-}
+import type { IntersectionOptions } from './types';
 /**
  * Track element visibility with IntersectionObserver
  * Updates isVisible whenever visibility changes

package/dist/useIntersection.svelte.js

@@ -1,4 +1,8 @@
 import { onMount } from 'svelte';
+/**
+ * Composable for handling IntersectionObserver logic
+ * Reduces duplication between animation components
+ */
 /**
  * Factory function to create intersection observer composables
  * Eliminates duplication between useIntersection and useIntersectionOnce

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rune-scroller",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lightweight, high-performance scroll animations for Svelte 5. ~2KB bundle, zero dependencies.",
   "type": "module",
   "sideEffects": false,

package/dist/Rs.svelte.d.ts

@@ -1,16 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { AnimationType } from './animations';
-interface Props {
-    animation?: AnimationType;
-    threshold?: number;
-    rootMargin?: string;
-    offset?: number;
-    duration?: number;
-    delay?: number;
-    repeat?: boolean;
-    children: Snippet;
-    [key: string]: any;
-}
-declare const Rs: import("svelte").Component<Props, {}, "">;
-type Rs = ReturnType<typeof Rs>;
-export default Rs;