rune-scroller 0.1.11 → 2.0.0

package/README.md

@@ -1,4 +1,12 @@
-# ⚡ Rune Scroller
+# ⚡ Rune Scroller - Full Reference
+
+**📚 Complete API Reference** — Detailed documentation for all features and options.
+
+**Quick start?** See [README.md](../README.md) for a simpler introduction.
+
+**Development?** See [CLAUDE.md](../CLAUDE.md) for the developer guide.
+
+---
 
 <div align="center">
 	<img src="./logo.png" alt="Rune Scroller Logo" width="200" />
@@ -13,13 +21,28 @@
 
 ## ✨ Features
 
-- **~2KB gzipped** - Minimal overhead
+- **~3.4KB gzipped** (11.5KB uncompressed) - Minimal overhead
 - **Zero dependencies** - Pure Svelte 5 + IntersectionObserver
 - **14 animations** - Fade, Zoom, Flip, Slide, Bounce variants
-- **TypeScript** - Full type coverage
+- **Full TypeScript support** - Type definitions generated from JSDoc
 - **SSR-ready** - SvelteKit compatible
 - **GPU-accelerated** - Pure CSS transforms
 - **Accessible** - Respects `prefers-reduced-motion`
+- **v2.0.0 New** - `onVisible` callback, ResizeObserver support, animation validation, sentinel customization
+- **✨ Latest** - `useIntersection` migrated to Svelte 5 `$effect` rune for better lifecycle management
+
+---
+
+## 📊 Performance & Quality
+
+**Recent Optimization (2026-01-06):**
+- ✅ **278/278 tests passing** (100%)
+- ✅ **Bundle size:** 10.5KiB gzipped (stable, no regression)
+- ✅ **Type safety:** 0 errors (JSDoc + TypeScript)
+- ✅ **Memory leaks:** 0 detected
+- ✅ **Svelte 5 aligned:** Full runes support
+
+See [`MIGRATION_METRICS.md`](../MIGRATION_METRICS.md) for detailed performance benchmarks.
 
 ---
 
@@ -37,11 +60,37 @@ yarn add rune-scroller
 
 ## 🚀 Quick Start
 
+### Step 1: Import CSS (required)
+
+**⚠️ Important:** You must import the CSS file once in your app.
+
+**Option A - In your root layout (recommended for SvelteKit):**
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+	import 'rune-scroller/animations.css';
+</script>
+
+<slot />
+```
+
+**Option B - In each component that uses animations:**
+
 ```svelte
 <script>
 	import runeScroller from 'rune-scroller';
 	import 'rune-scroller/animations.css';
 </script>
+```
+
+### Step 2: Use the animations
+
+```svelte
+<script>
+	import runeScroller from 'rune-scroller';
+	// CSS already imported in layout or above
+</script>
 
 <!-- Simple animation -->
 <div use:runeScroller={{ animation: 'fade-in' }}>
@@ -65,17 +114,17 @@ yarn add rune-scroller
 
 ### Fade (5)
 - `fade-in` - Simple opacity fade
-- `fade-in-up` - Fade + move up 100px
-- `fade-in-down` - Fade + move down 100px
-- `fade-in-left` - Fade + move from right
-- `fade-in-right` - Fade + move from left
+- `fade-in-up` - Fade + move up 300px
+- `fade-in-down` - Fade + move down 300px
+- `fade-in-left` - Fade + move from right 300px
+- `fade-in-right` - Fade + move from left 300px
 
 ### Zoom (5)
-- `zoom-in` - Scale from 0.6 to 1
-- `zoom-out` - Scale from 1.2 to 1
-- `zoom-in-up` - Zoom + move up
-- `zoom-in-left` - Zoom + move from right
-- `zoom-in-right` - Zoom + move from left
+- `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
 
 ### Others (4)
 - `flip` - 3D flip on Y-axis
@@ -90,12 +139,27 @@ yarn add rune-scroller
 ```typescript
 interface RuneScrollerOptions {
 	animation?: AnimationType;  // Animation name (default: 'fade-in')
-	duration?: number;          // Duration in ms (default: 2000)
+	duration?: number;          // Duration in ms (default: 800)
 	repeat?: boolean;           // Repeat on scroll (default: false)
-	debug?: boolean;            // Show sentinel element (default: false)
+	debug?: boolean;            // Show sentinel as visible line (default: false)
+	offset?: number;            // Sentinel offset in px (default: 0, negative = above)
+	onVisible?: (element: HTMLElement) => void;  // Callback when animation triggers (v2.0.0+)
+	sentinelColor?: string;     // Sentinel debug color, e.g. '#ff6b6b' (v2.0.0+)
+	sentinelId?: string;        // Custom ID for sentinel identification (v2.0.0+)
 }
 ```
 
+### Option Details
+
+- **`animation`** - Type of animation to play. Choose from 14 built-in animations listed above. Invalid animations automatically fallback to 'fade-in' with a console warning.
+- **`duration`** - How long the animation lasts in milliseconds (default: 800ms).
+- **`repeat`** - If `true`, animation plays every time sentinel enters viewport. If `false`, plays only once.
+- **`debug`** - If `true`, displays the sentinel element as a visible line below your element. Useful for seeing exactly when animations trigger. Default color is cyan (#00e0ff), customize with `sentinelColor`.
+- **`offset`** - Offset of the sentinel in pixels. Positive values move sentinel down (delays animation), negative values move it up (triggers earlier). Useful for large elements where you want animation to trigger before the entire element is visible.
+- **`onVisible`** *(v2.0.0+)* - Callback function triggered when the animation becomes visible. Receives the animated element as parameter. Useful for analytics, lazy loading, or triggering custom effects.
+- **`sentinelColor`** *(v2.0.0+)* - Customize the debug sentinel color (e.g., '#ff6b6b' for red). Only visible when `debug: true`. Useful for distinguishing multiple sentinels on the same page.
+- **`sentinelId`** *(v2.0.0+)* - Set a custom ID for the sentinel element. If not provided, an auto-ID is generated (`sentinel-1`, `sentinel-2`, etc.). Useful for identifying sentinels in DevTools and tracking which element owns which sentinel.
+
 ### Examples
 
 ```svelte
@@ -114,9 +178,74 @@ interface RuneScrollerOptions {
 	Repeats every time you scroll
 </div>
 
-<!-- Debug mode (shows invisible sentinel) -->
+<!-- Debug mode - shows cyan line marking sentinel position -->
 <div use:runeScroller={{ animation: 'fade-in', debug: true }}>
-	You'll see a cyan line (the sentinel trigger)
+	The cyan line below this shows when animation will trigger
+</div>
+
+<!-- Multiple options -->
+<div use:runeScroller={{
+	animation: 'fade-in-up',
+	duration: 1200,
+	repeat: true,
+	debug: true
+}}>
+	Full featured example
+</div>
+
+<!-- Large element - trigger animation earlier with negative offset -->
+<div use:runeScroller={{
+	animation: 'fade-in-up',
+	offset: -200  // Trigger 200px before element bottom
+}}>
+	Large content that needs early triggering
+</div>
+
+<!-- Delay animation by moving sentinel down -->
+<div use:runeScroller={{
+	animation: 'zoom-in',
+	offset: 300  // Trigger 300px after element bottom
+}}>
+	Content with delayed animation
+</div>
+
+<!-- v2.0.0: onVisible callback for analytics tracking -->
+<div use:runeScroller={{
+	animation: 'fade-in-up',
+	onVisible: (el) => {
+		console.log('Animation visible!', el);
+		// Track analytics, load images, trigger API calls, etc.
+		window.gtag?.('event', 'animation_visible', { element: el.id });
+	}
+}}>
+	Tracked animation
+</div>
+
+<!-- v2.0.0: Custom sentinel color for debugging -->
+<div use:runeScroller={{
+	animation: 'fade-in',
+	debug: true,
+	sentinelColor: '#ff6b6b'  // Red instead of default cyan
+}}>
+	Red debug sentinel
+</div>
+
+<!-- v2.0.0: Custom sentinel ID for identification -->
+<div use:runeScroller={{
+	animation: 'zoom-in',
+	sentinelId: 'hero-zoom',
+	debug: true
+}}>
+	Identified sentinel (shows "hero-zoom" in debug mode)
+</div>
+
+<!-- v2.0.0: Auto-ID (sentinel-1, sentinel-2, etc) -->
+<div use:runeScroller={{
+	animation: 'fade-in-up',
+	debug: true
+	// sentinelId omitted → auto generates "sentinel-1", "sentinel-2", etc
+}}>
+	Auto-identified sentinel
 </div>
 ```
 
@@ -139,19 +268,19 @@ For advanced use cases, use `animate` for fine-grained IntersectionObserver cont
 	duration: 1000,
 	delay: 200,
 	threshold: 0.5,
-	offset: 20,
-	once: true
+	offset: 20
 }}>
 	Advanced control
 </div>
 ```
 
 **Options:**
-- `threshold` - Intersection ratio to trigger (0-1)
+- `threshold` - Intersection ratio to trigger (0-1, default: 0)
 - `offset` - Viewport offset percentage (0-100)
 - `rootMargin` - Custom IntersectionObserver margin
-- `delay` - Animation delay in ms
-- `once` - Trigger only once
+- `delay` - Animation delay in ms (default: 0)
+
+**Note:** `animate` triggers the animation **once** when the element enters the viewport (it's one-time by default, unlike `runeScroller` with `repeat: true`)
 
 ### Using Composables
 
@@ -184,24 +313,42 @@ Rune Scroller uses **sentinel-based triggering**:
 3. This ensures precise timing regardless of element size
 4. Uses native IntersectionObserver for performance
 5. Pure CSS animations (GPU-accelerated)
+6. *(v2.0.0)* Sentinel automatically repositions on element resize via ResizeObserver
 
 **Why sentinels?**
 - Accurate timing across all screen sizes
 - No complex offset calculations
 - Handles staggered animations naturally
+- Sentinel stays fixed while element animates (no observer confusion with transforms)
+
+**Automatic ResizeObserver** *(v2.0.0+)*
+- Sentinel repositions automatically when element resizes
+- Works with responsive layouts and dynamic content
+- No configuration needed—it just works
 
 ---
 
 ## 🌐 SSR Compatibility
 
-Works seamlessly with SvelteKit:
+Works seamlessly with SvelteKit. Import CSS in your root layout:
 
 ```svelte
+<!-- src/routes/+layout.svelte -->
 <script>
-	import runeScroller from 'rune-scroller';
 	import 'rune-scroller/animations.css';
 </script>
 
+<slot />
+```
+
+Then use animations anywhere in your app:
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script>
+	import runeScroller from 'rune-scroller';
+</script>
+
 <!-- No special handling needed -->
 <div use:runeScroller={{ animation: 'fade-in-up' }}>
 	Works in SvelteKit SSR!
@@ -233,6 +380,19 @@ Users who prefer reduced motion will see content without animations.
 
 ## 📚 API Reference
 
+### Public API
+
+Rune Scroller exports **2 action-based APIs** (no components):
+
+1. **`runeScroller`** (default) - Recommended, sentinel-based, simple
+2. **`animate`** (advanced) - Direct observation, fine-grained control
+
+**Why actions instead of components?**
+- Actions are lightweight directives
+- No DOM wrapper overhead
+- Better performance
+- More flexible
+
 ### Main Export
 
 ```typescript
@@ -270,16 +430,23 @@ interface RuneScrollerOptions {
 	duration?: number;
 	repeat?: boolean;
 	debug?: boolean;
+	offset?: number;
+	onVisible?: (element: HTMLElement) => void;      // v2.0.0+
+	sentinelColor?: string;                          // v2.0.0+
+	sentinelId?: string;                             // v2.0.0+
 }
 
 interface AnimateOptions {
 	animation?: AnimationType;
-	duration?: number;
+	duration?: number;                               // default: 2500
 	delay?: number;
 	threshold?: number;
 	rootMargin?: string;
 	offset?: number;
 	once?: boolean;
+	onVisible?: (element: HTMLElement) => void;      // v2.0.0+
+	sentinelColor?: string;                          // v2.0.0+
+	sentinelId?: string;                             // v2.0.0+
 }
 ```
 
@@ -333,7 +500,6 @@ interface AnimateOptions {
 
 - **npm Package**: [rune-scroller](https://www.npmjs.com/package/rune-scroller)
 - **GitHub**: [lelabdev/rune-scroller](https://github.com/lelabdev/rune-scroller)
-- **Documentation**: [CLAUDE.md](./CLAUDE.md)
 - **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
 
 ---
@@ -350,10 +516,10 @@ Contributions welcome! Please open an issue or PR on GitHub.
 
 ```bash
 # Development
-pnpm install
-pnpm dev
-pnpm test
-pnpm build
+bun install
+bun run dev
+bun test
+bun run build
 ```
 
 ---

package/dist/__mocks__/IntersectionObserver.d.ts

@@ -0,0 +1,25 @@
+export class IntersectionObserverMock {
+    constructor(callback: any, options?: {});
+    id: number;
+    callback: any;
+    options: {};
+    observedElements: Set<any>;
+    isConnected: boolean;
+    observe(element: any): void;
+    unobserve(element: any): void;
+    disconnect(): void;
+    trigger(element: any, isIntersecting: any): void;
+}
+export namespace mockIntersectionObserver {
+    let observers: Map<any, any>;
+    let lastObserver: null;
+    function install(): void;
+    function uninstall(): void;
+    function reset(): void;
+    function getLastCreated(): any;
+    function getAll(): any[];
+    function trigger(element: any, isIntersecting: any): void;
+    function triggerAll(isIntersecting: any): void;
+    function getObserverFor(element: any): any;
+}
+export default IntersectionObserverMock;

package/dist/__mocks__/IntersectionObserver.js

@@ -0,0 +1,116 @@
+/**
+ * Mock IntersectionObserver for testing
+ * Allows manual triggering of intersection events for animation testing
+ */
+
+const observers = new Map();
+let observerId = 0;
+
+export class IntersectionObserverMock {
+	constructor(callback, options = {}) {
+		this.id = observerId++;
+		this.callback = callback;
+		this.options = options;
+		this.observedElements = new Set();
+		this.isConnected = true;
+
+		observers.set(this.id, this);
+	}
+
+	observe(element) {
+		if (!this.isConnected) return;
+		this.observedElements.add(element);
+	}
+
+	unobserve(element) {
+		this.observedElements.delete(element);
+	}
+
+	disconnect() {
+		this.isConnected = false;
+		this.observedElements.clear();
+		observers.delete(this.id);
+	}
+
+	// Testing API: Manually trigger intersection
+	trigger(element, isIntersecting) {
+		if (!this.observedElements.has(element)) return;
+
+		const entry = {
+			target: element,
+			isIntersecting,
+			intersectionRatio: isIntersecting ? 1 : 0,
+			boundingClientRect: element.getBoundingClientRect?.() || {},
+			intersectionRect: isIntersecting ? { top: 0, height: 100 } : {},
+			rootBounds: { top: 0, height: window.innerHeight || 768 },
+			time: Date.now(),
+			toJSON: () => ({})
+		};
+
+		this.callback([entry], this);
+	}
+}
+
+// Global API
+export const mockIntersectionObserver = {
+	observers: new Map(),
+	lastObserver: null,
+
+	install() {
+		global.IntersectionObserver = IntersectionObserverMock;
+		this.reset();
+	},
+
+	uninstall() {
+		if (typeof global !== 'undefined') {
+			delete global.IntersectionObserver;
+		}
+	},
+
+	reset() {
+		observers.forEach((obs) => obs.disconnect());
+		observers.clear();
+		observerId = 0;
+		this.lastObserver = null;
+		this.observers.clear();
+	},
+
+	// Get the last created observer
+	getLastCreated() {
+		if (observers.size === 0) return null;
+		const ids = Array.from(observers.keys());
+		return observers.get(ids[ids.length - 1]);
+	},
+
+	// Get all observers
+	getAll() {
+		return Array.from(observers.values());
+	},
+
+	// Trigger intersection on an element
+	trigger(element, isIntersecting) {
+		const matchingObservers = Array.from(observers.values()).filter((obs) =>
+			obs.observedElements.has(element)
+		);
+
+		matchingObservers.forEach((obs) => obs.trigger(element, isIntersecting));
+	},
+
+	// Trigger intersection on all observed elements
+	triggerAll(isIntersecting) {
+		observers.forEach((obs) => {
+			obs.observedElements.forEach((element) => {
+				obs.trigger(element, isIntersecting);
+			});
+		});
+	},
+
+	// Get observer for specific element
+	getObserverFor(element) {
+		return Array.from(observers.values()).find((obs) =>
+			obs.observedElements.has(element)
+		);
+	}
+};
+
+export default IntersectionObserverMock;

package/dist/__mocks__/svelte-runes.d.ts

@@ -0,0 +1,25 @@
+export namespace mockSvelteRunes {
+    export { effects };
+    export { effectCleanups };
+    export function install(): void;
+    export function uninstall(): void;
+    export function reset(): void;
+    export function getEffects(): any[];
+    export function runCleanups(): void;
+    export function createState(initialValue: any): ReactiveValue;
+}
+export default mockSvelteRunes;
+declare let effects: any[];
+declare let effectCleanups: any[];
+/**
+ * Mock Svelte 5 Runes for testing useIntersection composables
+ * Allows testing reactive state and effects without Svelte runtime
+ */
+declare class ReactiveValue {
+    constructor(initialValue: any);
+    _value: any;
+    _subscribers: Set<any>;
+    set value(newValue: any);
+    get value(): any;
+    subscribe(fn: any): () => boolean;
+}

package/dist/__mocks__/svelte-runes.js

@@ -0,0 +1,117 @@
+/**
+ * Mock Svelte 5 Runes for testing useIntersection composables
+ * Allows testing reactive state and effects without Svelte runtime
+ */
+
+class ReactiveValue {
+	constructor(initialValue) {
+		this._value = initialValue;
+		this._subscribers = new Set();
+	}
+
+	get value() {
+		return this._value;
+	}
+
+	set value(newValue) {
+		if (this._value !== newValue) {
+			this._value = newValue;
+			this._subscribers.forEach((fn) => fn(newValue));
+		}
+	}
+
+	subscribe(fn) {
+		this._subscribers.add(fn);
+		return () => this._subscribers.delete(fn);
+	}
+}
+
+// Global state management for mocks
+let effects = [];
+let effectCleanups = [];
+
+export const mockSvelteRunes = {
+	effects,
+	effectCleanups,
+
+	install() {
+		// Mock $state
+		global.$state = (initialValue) => {
+			return new ReactiveValue(initialValue);
+		};
+
+		// Mock $effect
+		global.$effect = (fn) => {
+			const cleanup = fn();
+			effects.push(fn);
+			effectCleanups.push(cleanup);
+			return cleanup;
+		};
+
+		// Mock $effect.pre
+		global.$effect.pre = (fn) => {
+			const cleanup = fn();
+			effects.push(fn);
+			effectCleanups.push(cleanup);
+			return cleanup;
+		};
+
+		// Mock $derived
+		global.$derived = (expression) => {
+			return expression;
+		};
+
+		// Mock $derived.by
+		global.$derived.by = (fn) => {
+			return fn();
+		};
+
+		this.reset();
+	},
+
+	uninstall() {
+		if (typeof global !== 'undefined') {
+			delete global.$state;
+			delete global.$effect;
+			delete global.$derived;
+		}
+	},
+
+	reset() {
+		// Run all cleanups
+		effectCleanups.forEach((cleanup) => {
+			if (typeof cleanup === 'function') {
+				try {
+					cleanup();
+				} catch (e) {
+					// Silently ignore cleanup errors
+				}
+			}
+		});
+
+		effects.length = 0;
+		effectCleanups.length = 0;
+	},
+
+	getEffects() {
+		return effects;
+	},
+
+	runCleanups() {
+		effectCleanups.forEach((cleanup) => {
+			if (typeof cleanup === 'function') {
+				try {
+					cleanup();
+				} catch (e) {
+					// Silently ignore cleanup errors
+				}
+			}
+		});
+	},
+
+	createState(initialValue) {
+		return new ReactiveValue(initialValue);
+	}
+};
+
+export default mockSvelteRunes;