rune-scroller 0.0.1 → 0.1.0

package/README.md

@@ -15,7 +15,7 @@
 - ✅ **Svelte 5 Runes** : `$state`, `$props()` with snippets
 - ✅ **Zero Dependencies** : Pure Svelte 5 + IntersectionObserver
 - ✅ **Native Performance** : GPU-accelerated CSS animations
-- ✅ **26+ Animations** : Fade, Zoom, Flip, Slide, Bounce, and more
+- ✅ **14 Built-in Animations** : Fade (5), Zoom (5), Flip (2), Slide Rotate, Bounce
 - ✅ **TypeScript** : Full type coverage with strict mode
 - ✅ **Customizable** : Duration, delay, threshold, offset per element
 - ✅ **Play Once or Repeat** : Control animation behavior
@@ -55,73 +55,225 @@ For a typical SvelteKit app:
 ## 📦 Project Structure
 
 ```
-rune-scroller/
+rune-scroller-lib/
 ├── src/lib/
-│   ├── ScrollAnimate.svelte           # One-time animation component
-│   ├── AnimatedElements.svelte        # Repeating animation component
-│   ├── useIntersection.svelte.ts      # IntersectionObserver composable
-│   ├── animations.ts                  # Animation configuration
-│   ├── animations.css                 # Animation styles
-│   └── viking-theme.css               # Modern granite theme
-├── src/routes/
-│   ├── +layout.svelte
-│   └── +page.svelte                   # Demo page
-└── package.json
+│   ├── Rs.svelte                      # Main animation component (one-time or repeat)
+│   ├── BaseAnimated.svelte            # Base animation implementation
+│   ├── runeScroller.svelte.ts         # Sentinel-based animation action (recommended)
+│   ├── useIntersection.svelte.ts      # IntersectionObserver composables
+│   ├── animate.svelte.ts              # Animation action for direct DOM control
+│   ├── animations.ts                  # Animation configuration & validation
+│   ├── animations.css                 # Animation styles (14 animations)
+│   ├── animations.test.ts             # Animation configuration tests
+│   ├── scroll-animate.test.ts         # Component behavior tests
+│   └── index.ts                       # Library entry point
+├── dist/                              # Built library (created by pnpm build)
+├── package.json                       # npm package configuration
+├── svelte.config.js                   # SvelteKit configuration
+├── vite.config.ts                     # Vite build configuration
+├── tsconfig.json                      # TypeScript configuration
+└── eslint.config.js                   # ESLint configuration
 ```
 
 ---
 
 ## 🚀 Quick Start
 
-### 1. ScrollAnimate Component (Plays Once)
+### Installation
 
-Use `ScrollAnimate` for animations that play once when elements enter the viewport:
+```bash
+npm install rune-scroller
+```
+
+Or with other package managers:
+
+```bash
+pnpm add rune-scroller
+yarn add rune-scroller
+```
+
+### Basic Usage with `Rs` Component
+
+The `Rs` component is the main component for scroll animations. Use the `repeat` prop to control animation behavior:
 
 ```svelte
 <script>
-	import ScrollAnimate from '$lib/ScrollAnimate.svelte';
+	import Rs from 'rune-scroller';
+	import 'rune-scroller/animations.css';
 </script>
 
-<ScrollAnimate animation="fade-in">
-	<div class="rune-card">
+<!-- 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>
-</ScrollAnimate>
-```
+</Rs>
 
-### 2. AnimatedElements Component (Repeating)
+<!-- 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>
+```
 
-Use `AnimatedElements` for animations that trigger every time the element enters the viewport:
+### In SvelteKit/Local Development
 
 ```svelte
 <script>
-	import AnimatedElements from '$lib/AnimatedElements.svelte';
+	import Rs from '$lib/Rs.svelte';
+	import '$lib/animations.css';
 </script>
 
-<AnimatedElements animation="zoom-in">
-	<div class="rune-card">
-		<h2>Repeating Animation</h2>
-		<p>This triggers each time you scroll past it</p>
+<Rs animation="fade-in-up" duration={1000} delay={200}>
+	<div class="card">
+		<h2>Animated Content</h2>
 	</div>
-</AnimatedElements>
+</Rs>
+```
+
+### API Overview
+
+The `Rs` component is the unified API for all scroll animations:
+
+```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>
+```
+
+---
+
+## 🎯 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.
+
+### Why Sentinels?
+
+- **Accurate Timing** - Instead of triggering when the element enters, sentinel triggers slightly earlier
+- **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>
+```
+
+### Sentinel-Based Examples
+
+**Staggered animations with sentinels:**
+
+```svelte
+<script>
+	import { runeScroller } from 'rune-scroller';
+</script>
+
+<div class="grid">
+	{#each items as item, i}
+		<div use:runeScroller={{ animation: 'fade-in-up', duration: 800 }}>
+			<h3>{item.title}</h3>
+			<p>{item.description}</p>
+		</div>
+	{/each}
+</div>
+```
+
+**Hero section with sentinel triggering:**
+
+```svelte
+<div use:runeScroller={{ animation: 'fade-in-down', duration: 1000 }}>
+	<h1>Welcome to Our Site</h1>
+</div>
+
+<div use:runeScroller={{ animation: 'fade-in-up', duration: 1200 }}>
+	<p>Engaging content appears as you scroll</p>
+</div>
+
+<div use:runeScroller={{ animation: 'zoom-in', duration: 1000 }}>
+	<button class="cta">Get Started</button>
+</div>
+```
+
+### `runeScroller` Options
+
+```typescript
+interface RuneScrollerOptions {
+	animation?: AnimationType; // Animation type (e.g., 'fade-in-up')
+	duration?: number;         // Duration in milliseconds (default: 2000)
+	repeat?: boolean;          // Repeat animation on each scroll (default: false)
+}
 ```
 
+### 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
 
-### ScrollAnimate
+### Rs Component
 
 ```typescript
-interface ScrollAnimateProps {
+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.)
 }
 ```
 
@@ -138,45 +290,51 @@ Controls when the animation triggers as the element scrolls into view. If not sp
 
 ```svelte
 <!-- Early trigger (bottom of screen) -->
-<ScrollAnimate animation="fade-in-up" offset={0}>
-	<div class="rune-card">Animates early</div>
-</ScrollAnimate>
+<Rs animation="fade-in-up" offset={0}>
+	<div class="card">Animates early</div>
+</Rs>
 
 <!-- Late trigger (top of screen) -->
-<ScrollAnimate animation="fade-in-up" offset={100}>
-	<div class="rune-card">Animates late</div>
-</ScrollAnimate>
+<Rs animation="fade-in-up" offset={100}>
+	<div class="card">Animates late</div>
+</Rs>
 
 <!-- Custom timing -->
-<ScrollAnimate animation="fade-in-up" offset={75}>
-	<div class="rune-card">Animates at 75%</div>
-</ScrollAnimate>
+<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
-<ScrollAnimate animation="fade-in-up" duration={1200} delay={300} threshold={0.8} offset={25}>
-	<div class="rune-card">
+<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>
-</ScrollAnimate>
+</Rs>
 ```
 
-### AnimatedElements
+#### Repeat Behavior
 
-```typescript
-interface AnimatedElementsProps {
-	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)
-	children: Snippet; // Content to animate
-}
-```
+Use the `repeat` prop to control animation behavior:
 
-Same `offset` behavior as `ScrollAnimate`, but animation **repeats on every scroll pass** instead of playing once.
+- `repeat={false}` (default) - Animation plays **once** when element enters viewport
+- `repeat={true}` - Animation **repeats** every time element enters viewport
 
 ---
 
@@ -189,12 +347,12 @@ Same `offset` behavior as `ScrollAnimate`, but animation **repeats on every scro
 Simple opacity fade from transparent to visible.
 
 ```svelte
-<ScrollAnimate animation="fade-in">
-	<div class="rune-card">
+<Rs animation="fade-in">
+	<div class="card">
 		<h2>Fade In</h2>
 		<p>Simple fade entrance</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 #### `fade-in-up`
@@ -202,12 +360,12 @@ Simple opacity fade from transparent to visible.
 Fades in while moving up 100px.
 
 ```svelte
-<ScrollAnimate animation="fade-in-up">
-	<div class="rune-card">
+<Rs animation="fade-in-up">
+	<div class="card">
 		<h2>Fade In Up</h2>
 		<p>Rises from below</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 #### `fade-in-down`
@@ -215,12 +373,12 @@ Fades in while moving up 100px.
 Fades in while moving down 100px.
 
 ```svelte
-<ScrollAnimate animation="fade-in-down">
-	<div class="rune-card">
+<Rs animation="fade-in-down">
+	<div class="card">
 		<h2>Fade In Down</h2>
 		<p>Descends from above</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 #### `fade-in-left`
@@ -228,12 +386,12 @@ Fades in while moving down 100px.
 Fades in while moving left 100px.
 
 ```svelte
-<ScrollAnimate animation="fade-in-left">
-	<div class="rune-card">
+<Rs animation="fade-in-left">
+	<div class="card">
 		<h2>Fade In Left</h2>
 		<p>Comes from the right</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 #### `fade-in-right`
@@ -241,29 +399,29 @@ Fades in while moving left 100px.
 Fades in while moving right 100px.
 
 ```svelte
-<ScrollAnimate animation="fade-in-right">
-	<div class="rune-card">
+<Rs animation="fade-in-right">
+	<div class="card">
 		<h2>Fade In Right</h2>
 		<p>Comes from the left</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 ---
 
-### Zoom (2 variants)
+### Zoom (5 variants)
 
 #### `zoom-in`
 
 Scales from 50% to 100% while fading in.
 
 ```svelte
-<ScrollAnimate animation="zoom-in">
-	<div class="rune-card">
+<Rs animation="zoom-in">
+	<div class="card">
 		<h2>Zoom In</h2>
 		<p>Grows into view</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 #### `zoom-out`
@@ -271,12 +429,51 @@ Scales from 50% to 100% while fading in.
 Scales from 150% to 100% while fading in.
 
 ```svelte
-<ScrollAnimate animation="zoom-out">
-	<div class="rune-card">
+<Rs animation="zoom-out">
+	<div class="card">
 		<h2>Zoom Out</h2>
 		<p>Shrinks into view</p>
 	</div>
-</ScrollAnimate>
+</Rs>
+```
+
+#### `zoom-in-up`
+
+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>
+```
+
+#### `zoom-in-left`
+
+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>
+```
+
+#### `zoom-in-right`
+
+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>
 ```
 
 ---
@@ -288,12 +485,12 @@ Scales from 150% to 100% while fading in.
 3D rotation on Y axis (left to right).
 
 ```svelte
-<ScrollAnimate animation="flip">
-	<div class="rune-card">
+<Rs animation="flip">
+	<div class="card">
 		<h2>Flip</h2>
 		<p>Rotates on Y axis</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 #### `flip-x`
@@ -301,12 +498,12 @@ Scales from 150% to 100% while fading in.
 3D rotation on X axis (top to bottom).
 
 ```svelte
-<ScrollAnimate animation="flip-x">
-	<div class="rune-card">
+<Rs animation="flip-x">
+	<div class="card">
 		<h2>Flip X</h2>
 		<p>Rotates on X axis</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 ---
@@ -318,12 +515,12 @@ Scales from 150% to 100% while fading in.
 Slides from left while rotating 45 degrees.
 
 ```svelte
-<ScrollAnimate animation="slide-rotate">
-	<div class="rune-card">
+<Rs animation="slide-rotate">
+	<div class="card">
 		<h2>Slide Rotate</h2>
 		<p>Slides and spins</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 ---
@@ -335,30 +532,30 @@ Slides from left while rotating 45 degrees.
 Bouncy entrance with scaling keyframe animation.
 
 ```svelte
-<ScrollAnimate animation="bounce-in" duration={800}>
-	<div class="rune-card">
+<Rs animation="bounce-in" duration={800}>
+	<div class="card">
 		<h2>Bounce In</h2>
 		<p>Bounces into view</p>
 	</div>
-</ScrollAnimate>
+</Rs>
 ```
 
 ---
 
 ### Compare: Once vs Repeat
 
-**Same animation, different behavior:**
+**Same animation, different behavior using the `repeat` prop:**
 
 ```svelte
-<!-- Plays once on scroll down -->
-<ScrollAnimate animation="fade-in-up">
-	<div class="rune-card">Animates once</div>
-</ScrollAnimate>
+<!-- Plays once on scroll down (default) -->
+<Rs animation="fade-in-up">
+	<div class="card">Animates once</div>
+</Rs>
 
 <!-- Repeats each time you scroll by -->
-<AnimatedElements animation="fade-in-up">
-	<div class="rune-card">Animates on every scroll</div>
-</AnimatedElements>
+<Rs animation="fade-in-up" repeat>
+	<div class="card">Animates on every scroll</div>
+</Rs>
 ```
 
 ---
@@ -371,17 +568,17 @@ Animate cards with progressive delays:
 
 ```svelte
 <script>
-	import ScrollAnimate from '$lib/ScrollAnimate.svelte';
+	import Rs from '$lib/Rs.svelte';
 </script>
 
 <div class="grid">
 	{#each items as item, i}
-		<ScrollAnimate animation="fade-in-up" delay={i * 100}>
-			<div class="rune-card">
+		<Rs animation="fade-in-up" delay={i * 100}>
+			<div class="card">
 				<h3>{item.title}</h3>
 				<p>{item.description}</p>
 			</div>
-		</ScrollAnimate>
+		</Rs>
 	{/each}
 </div>
 ```
@@ -389,100 +586,154 @@ Animate cards with progressive delays:
 ### Mixed Animations
 
 ```svelte
-<ScrollAnimate animation="fade-in">
+<Rs animation="fade-in">
 	<section>Content fades in</section>
-</ScrollAnimate>
+</Rs>
 
-<ScrollAnimate animation="slide-rotate">
+<Rs animation="slide-rotate">
 	<section>Content slides and rotates</section>
-</ScrollAnimate>
+</Rs>
 
-<AnimatedElements animation="zoom-in">
+<Rs animation="zoom-in" repeat>
 	<section>Content zooms in repeatedly</section>
-</AnimatedElements>
+</Rs>
 ```
 
 ### Hero Section
 
 ```svelte
 <script>
-	import ScrollAnimate from '$lib/ScrollAnimate.svelte';
+	import Rs from '$lib/Rs.svelte';
 </script>
 
 <section class="hero">
 	<div class="hero-content">
-		<ScrollAnimate animation="fade-in" delay={0}>
+		<Rs animation="fade-in" delay={0}>
 			<h1>Welcome</h1>
-		</ScrollAnimate>
+		</Rs>
 
-		<ScrollAnimate animation="fade-in" delay={200}>
+		<Rs animation="fade-in" delay={200}>
 			<p>Scroll to reveal more</p>
-		</ScrollAnimate>
+		</Rs>
 
-		<ScrollAnimate animation="zoom-in" delay={400}>
+		<Rs animation="zoom-in" delay={400}>
 			<button>Get Started</button>
-		</ScrollAnimate>
+		</Rs>
 	</div>
 </section>
 ```
 
 ---
 
-## 🎨 Theming
+## 🔧 Composables & Actions
 
-The project includes a modern **Granite + Electric Blue** theme in `src/lib/viking-theme.css`.
+### runeScroller (Recommended)
 
-### Color Palette
+The `runeScroller` action provides sentinel-based animation triggering for precise timing control:
 
-```css
---granite-dark: #0f1419;
---granite-medium: #1a1f2e;
---granite-light: #252d3d;
---electric-blue: #00d9ff;
---text-primary: #f0f2f5;
---text-secondary: #a8b0be;
+```typescript
+function runeScroller(
+	element: HTMLElement,
+	options?: {
+		animation?: AnimationType;  // Animation type
+		duration?: number;          // Duration in ms (default: 2000)
+		repeat?: boolean;           // Repeat animation on each scroll (default: false)
+	}
+): { update?: (newOptions) => void; destroy?: () => void }
+```
+
+**Key Features:**
+- Automatically creates an invisible 20px sentinel element below your content
+- Triggers animation when sentinel enters viewport
+- Provides consistent timing across all screen sizes
+- Minimal configuration needed
+- Supports both one-time and repeating animations
+
+**Basic Example (One-time animation):**
+
+```svelte
+<script>
+	import { runeScroller } from 'rune-scroller';
+</script>
+
+<!-- Animation plays once when sentinel enters viewport -->
+<div use:runeScroller={{ animation: 'fade-in-up', duration: 1000 }}>
+	Animated content with sentinel-based triggering
+</div>
+```
+
+**Repeating Animation:**
+
+```svelte
+<!-- Animation repeats each time sentinel enters viewport -->
+<div use:runeScroller={{ animation: 'bounce-in', duration: 800, repeat: true }}>
+	This animates every time you scroll past it
+</div>
 ```
 
-### Card Classes
+**Complete Examples:**
 
 ```svelte
-<!-- Large card -->
-<div class="rune-card">
-	<h2>Title</h2>
-	<p>Content</p>
+<script>
+	import { runeScroller } from 'rune-scroller';
+</script>
+
+<!-- Fade in once on scroll -->
+<div use:runeScroller={{ animation: 'fade-in', duration: 600 }}>
+	<h2>Section Title</h2>
+	<p>Fades in when scrolled into view</p>
 </div>
 
-<!-- Small card (for grids) -->
-<div class="rune-card small">
-	<h3>Small Title</h3>
-	<p>Small content</p>
+<!-- Zoom in with longer duration -->
+<div use:runeScroller={{ animation: 'zoom-in-up', duration: 1200 }}>
+	<div class="card">
+		<h3>Card Title</h3>
+		<p>Zooms in from below</p>
+	</div>
 </div>
 
-<!-- Divider line -->
-<div class="rune-divider"></div>
+<!-- Repeating animation for interactive effect -->
+<div use:runeScroller={{ animation: 'bounce-in', duration: 700, repeat: true }}>
+	<button class="interactive-button">Bounces on each scroll</button>
+</div>
+
+<!-- Complex staggered layout -->
+<div class="grid">
+	{#each items as item, i}
+		<div use:runeScroller={{ animation: 'fade-in-up', duration: 800 }}>
+			<h3>{item.title}</h3>
+			<p>{item.description}</p>
+		</div>
+	{/each}
+</div>
 ```
 
----
+**When to use:**
+- ✅ Simple element animations
+- ✅ Consistent timing across layouts
+- ✅ Minimal overhead applications
+- ✅ Both one-time and repeating animations
+- ❌ Complex layout with component isolation (use `Rs` component instead)
 
-## 🔧 Composables
+---
 
 ### useIntersectionOnce
 
-For animations that play only once (used by `ScrollAnimate`):
+For one-time animations:
 
 ```typescript
 function useIntersectionOnce(options?: {
 	threshold?: number;
 	rootMargin?: string;
 	root?: Element | null;
-});
+}): { element: HTMLElement | null; isVisible: boolean }
 ```
 
-Returns `{ element, isVisible }` — bind `element` to your target, `isVisible` becomes `true` once.
+Returns `{ element, isVisible }` — bind `element` to your target, `isVisible` becomes `true` once, then observer unobserves.
 
 ### useIntersection
 
-For repeating animations (used by `AnimatedElements`):
+For repeating animations:
 
 ```typescript
 function useIntersection(
@@ -492,22 +743,62 @@ function useIntersection(
 		root?: Element | null;
 	},
 	onVisible?: (isVisible: boolean) => void
-);
+): { element: HTMLElement | null; isVisible: boolean }
+```
+
+Returns `{ element, isVisible }` — `isVisible` toggles `true`/`false` on each scroll pass.
+
+### animate Action
+
+For direct DOM animation control without component wrapper:
+
+```typescript
+function animate(
+	node: HTMLElement,
+	options?: {
+		animation?: AnimationType;    // Default: 'fade-in'
+		duration?: number;             // Default: 800
+		delay?: number;                // Default: 0
+		offset?: number;               // Optional trigger offset
+		threshold?: number;            // Default: 0
+		rootMargin?: string;           // Optional custom margin
+	}
+): { update?: (newOptions) => void; destroy?: () => void }
 ```
 
-Returns `{ element, isVisible }` — `isVisible` toggles on each scroll.
+**Example:**
+
+```svelte
+<script>
+	import { animate } from 'rune-scroller';
+</script>
+
+<div use:animate={{ animation: 'fade-in-up', duration: 1000, delay: 200 }}>
+	Animated content
+</div>
+```
 
 ---
 
 ## 🏗️ Architecture
 
-### Animation System
+### Core Layer Architecture
+
+**Bottom Layer - Browser APIs & Utilities:**
+1. **animations.ts** - Animation type definitions, validation, and utilities
+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)
 
-1. **animations.ts** - Configuration and validation
-2. **animations.css** - Reusable animation styles
-3. **useIntersection.svelte.ts** - IntersectionObserver logic
-4. **ScrollAnimate.svelte** - One-time wrapper component
-5. **AnimatedElements.svelte** - Repeating wrapper component
+**Styles:**
+- **animations.css** - All animation keyframes & styles (14 animations, GPU-accelerated)
 
 ### Key Principles
 
@@ -515,6 +806,45 @@ Returns `{ element, isVisible }` — `isVisible` toggles on each scroll.
 - **CSS-Based** : Animations use CSS transforms + transitions (hardware-accelerated)
 - **Type-Safe** : Full TypeScript support
 - **Composable** : Use hooks directly or wrapped components
+- **DRY (Don't Repeat Yourself)** : Utility functions eliminate code duplication
+- **Optimal DOM Manipulation** : Uses `cssText` for efficient single-statement styling
+
+---
+
+## 🚀 Optimizations
+
+### Recent Improvements (v1.1.0)
+
+**DOM Utility Extraction**
+- Extracted repeated DOM manipulation patterns into reusable utilities (`dom-utils.svelte.ts`)
+- `setCSSVariables()` - Centralizes CSS custom property management
+- `setupAnimationElement()` - Consistent animation class/attribute setup
+- `createSentinel()` - Optimized sentinel creation using single `cssText` statement
+- **Result**: Reduced code duplication, improved maintainability, cleaner codebase
+
+**Memory Leak Fixes**
+- Fixed potential memory leaks in repeat mode by tracking observer connection state
+- Observer now properly disconnects in destroy lifecycle
+- Prevents accumulation of observers on long-scroll pages
+- **Result**: Better performance on content-heavy sites with many animations
+
+**Observer Logic Improvements**
+- Fixed `animate.svelte.ts` to properly handle dynamic threshold/rootMargin changes
+- Observer now recreates when trigger options change at runtime
+- Maintains correct state throughout component lifecycle
+- **Result**: More reliable dynamic animation updates
+
+**Bundle Size Optimization**
+- Updated `.npmignore` to exclude test files from npm distribution
+- Removes `*.test.ts`, `*.test.js` and built test files
+- **Result**: ~3.6 KB reduction in package size
+
+### Performance Impact
+
+- **Code Size**: Reduced duplication without sacrificing readability
+- **Runtime Performance**: Fewer DOM operations via optimized `cssText` usage
+- **Memory Efficiency**: Proper observer cleanup prevents memory leaks
+- **Bundle Size**: Test files excluded from distribution
 
 ---
 
@@ -540,10 +870,22 @@ pnpm dev
 # Type checking
 pnpm check
 
+# Type checking in watch mode
+pnpm check:watch
+
 # Format code
 pnpm format
 
-# Preview build
+# Lint code
+pnpm lint
+
+# Build library for npm
+pnpm build
+
+# Run tests
+pnpm test
+
+# Preview built library
 pnpm preview
 ```
 
@@ -552,9 +894,10 @@ pnpm preview
 ## 📝 Notes
 
 - **Why "Rune"?** Svelte 5 uses **Runes** (`$state`, `$props()`) as core reactivity primitives
-- **Theme Name** : Granite + Electric Blue = Modern, minimalist aesthetic
-- **No Dependencies** : Pure Svelte 5 + Browser APIs
+- **Zero Dependencies** : Pure Svelte 5 + Native Browser APIs (IntersectionObserver)
 - **Extensible** : Add new animations by extending `animations.ts` and `animations.css`
+- **Library Only** : This is the library repository. The demo website is in `rune-scroller-site`
+- **Published as npm Package** : `rune-scroller` on npm registry
 
 ---