rune-scroller 3.0.1 → 3.0.2

package/dist/animations.css

@@ -0,0 +1,237 @@
+/**
+ * Rune Scroller — scroll animation styles
+ * CSS custom properties for flexible animation control
+ * Supports both native and AOS-compatible animation names
+ */
+
+/* ===== Distance variable ===== */
+:root {
+  --rs-distance: 100px;
+}
+
+/* ===== Base animation container ===== */
+[data-animation] {
+  opacity: 0;
+  transition-property: opacity, transform;
+  transition-duration: var(--duration, 400ms);
+  transition-delay: var(--delay, 0ms);
+  transition-timing-function: var(--easing, ease);
+  transform: translate3d(var(--tx, 0), var(--ty, 0), 0) scale(var(--scale, 1))
+    rotateX(var(--rx, 0deg)) rotateY(var(--ry, 0deg))
+    rotate(var(--rotate, 0deg));
+}
+
+/* ===== Visible state ===== */
+[data-animation].is-visible {
+  opacity: 1 !important;
+  will-change: transform, opacity;
+  transform: translate3d(0, 0, 0) scale(1) rotateX(0deg) rotateY(0deg)
+    rotate(0deg);
+}
+
+/* ===== Fade animations ===== */
+[data-animation="fade"] {
+  --tx: 0;
+  --ty: 0;
+}
+[data-animation="fade-up"] {
+  --ty: var(--rs-distance);
+}
+[data-animation="fade-down"] {
+  --ty: calc(-1 * var(--rs-distance));
+}
+[data-animation="fade-left"] {
+  --tx: calc(-1 * var(--rs-distance));
+}
+[data-animation="fade-right"] {
+  --tx: var(--rs-distance);
+}
+[data-animation="fade-up-right"] {
+  --tx: var(--rs-distance);
+  --ty: var(--rs-distance);
+}
+[data-animation="fade-up-left"] {
+  --tx: calc(-1 * var(--rs-distance));
+  --ty: var(--rs-distance);
+}
+[data-animation="fade-down-right"] {
+  --tx: var(--rs-distance);
+  --ty: calc(-1 * var(--rs-distance));
+}
+[data-animation="fade-down-left"] {
+  --tx: calc(-1 * var(--rs-distance));
+  --ty: calc(-1 * var(--rs-distance));
+}
+
+/* ===== Zoom animations ===== */
+[data-animation="zoom-in"] {
+  --scale: 0.6;
+}
+[data-animation="zoom-in-up"] {
+  --scale: 0.6;
+  --ty: var(--rs-distance);
+}
+[data-animation="zoom-in-down"] {
+  --scale: 0.6;
+  --ty: calc(-1 * var(--rs-distance));
+}
+[data-animation="zoom-in-left"] {
+  --scale: 0.6;
+  --tx: calc(-1 * var(--rs-distance));
+}
+[data-animation="zoom-in-right"] {
+  --scale: 0.6;
+  --tx: var(--rs-distance);
+}
+
+[data-animation="zoom-out"] {
+  --scale: 1.2;
+}
+[data-animation="zoom-out-up"] {
+  --scale: 1.2;
+  --ty: var(--rs-distance);
+}
+[data-animation="zoom-out-down"] {
+  --scale: 1.2;
+  --ty: calc(-1 * var(--rs-distance));
+}
+[data-animation="zoom-out-left"] {
+  --scale: 1.2;
+  --tx: calc(-1 * var(--rs-distance));
+}
+[data-animation="zoom-out-right"] {
+  --scale: 1.2;
+  --tx: var(--rs-distance);
+}
+
+/* ===== Slide animations ===== */
+[data-animation="slide-up"] {
+  opacity: 1;
+  transform: translate3d(0, 100%, 0);
+}
+[data-animation="slide-down"] {
+  opacity: 1;
+  transform: translate3d(0, -100%, 0);
+}
+[data-animation="slide-left"] {
+  opacity: 1;
+  transform: translate3d(100%, 0, 0);
+}
+[data-animation="slide-right"] {
+  opacity: 1;
+  transform: translate3d(-100%, 0, 0);
+}
+[data-animation="slide-up"].is-visible,
+[data-animation="slide-down"].is-visible,
+[data-animation="slide-left"].is-visible,
+[data-animation="slide-right"].is-visible {
+  transform: translate3d(0, 0, 0);
+}
+
+/* ===== Flip animations ===== */
+[data-animation="flip-left"] {
+  opacity: 1;
+  backface-visibility: hidden;
+  transform: perspective(2500px) rotateY(-100deg);
+}
+[data-animation="flip-right"] {
+  opacity: 1;
+  backface-visibility: hidden;
+  transform: perspective(2500px) rotateY(100deg);
+}
+[data-animation="flip-up"] {
+  opacity: 1;
+  backface-visibility: hidden;
+  transform: perspective(2500px) rotateX(-100deg);
+}
+[data-animation="flip-down"] {
+  opacity: 1;
+  backface-visibility: hidden;
+  transform: perspective(2500px) rotateX(100deg);
+}
+[data-animation="flip-left"].is-visible {
+  transform: perspective(2500px) rotateY(0);
+}
+[data-animation="flip-right"].is-visible {
+  transform: perspective(2500px) rotateY(0);
+}
+[data-animation="flip-up"].is-visible {
+  transform: perspective(2500px) rotateX(0);
+}
+[data-animation="flip-down"].is-visible {
+  transform: perspective(2500px) rotateX(0);
+}
+
+/* ===== Special animations ===== */
+[data-animation="slide-rotate"] {
+  --tx: calc(-1 * var(--rs-distance));
+  --rotate: -45deg;
+}
+
+/* Bounce — uses keyframes */
+[data-animation="bounce-in"] {
+  --scale: 0;
+}
+
+@keyframes rs-bounce {
+  0% {
+    transform: scale(0);
+  }
+  50% {
+    transform: scale(1.1);
+  }
+  100% {
+    transform: scale(1);
+  }
+}
+
+[data-animation="bounce-in"].is-visible {
+  animation: rs-bounce var(--duration, 1500ms)
+    cubic-bezier(0.68, -0.55, 0.265, 1.55);
+  animation-delay: var(--delay, 0ms);
+}
+
+/* ===== Legacy aliases (backward compat with v2.x) ===== */
+[data-animation="fade-in"] {
+  --tx: 0;
+  --ty: 0;
+}
+[data-animation="fade-in-up"] {
+  --ty: var(--rs-distance);
+}
+[data-animation="fade-in-down"] {
+  --ty: calc(-1 * var(--rs-distance));
+}
+[data-animation="fade-in-left"] {
+  --tx: calc(-1 * var(--rs-distance));
+}
+[data-animation="fade-in-right"] {
+  --tx: var(--rs-distance);
+}
+[data-animation="flip"] {
+  backface-visibility: hidden;
+  --ry: 90deg;
+}
+[data-animation="flip"].is-visible {
+  --ry: 0deg;
+}
+[data-animation="flip-x"] {
+  backface-visibility: hidden;
+  --rx: 90deg;
+}
+[data-animation="flip-x"].is-visible {
+  --rx: 0deg;
+}
+
+/* ===== Accessibility: Respect user's motion preferences ===== */
+@media (prefers-reduced-motion: reduce) {
+  [data-animation] {
+    transition: none;
+    animation: none !important;
+  }
+
+  [data-animation].is-visible {
+    opacity: 1;
+    transform: none !important;
+  }
+}

package/dist/animations.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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
+ * Includes both native rune-scroller animations and AOS-compatible names
+ * @type {readonly string[]}
+ */
+export const ANIMATION_TYPES: readonly string[];

package/dist/animations.js

@@ -0,0 +1,70 @@
+/**
+ * Animation utilities
+ * Type definitions have been moved to types.js for single source of truth
+ */
+
+/**
+ * All available animation types in the library
+ * Includes both native rune-scroller animations and AOS-compatible names
+ * @type {readonly string[]}
+ */
+export const ANIMATION_TYPES = [
+  // Fade (10)
+  "fade",
+  "fade-up",
+  "fade-down",
+  "fade-left",
+  "fade-right",
+  "fade-up-right",
+  "fade-up-left",
+  "fade-down-right",
+  "fade-down-left",
+  // Zoom (10)
+  "zoom-in",
+  "zoom-in-up",
+  "zoom-in-down",
+  "zoom-in-left",
+  "zoom-in-right",
+  "zoom-out",
+  "zoom-out-up",
+  "zoom-out-down",
+  "zoom-out-left",
+  "zoom-out-right",
+  // Slide (4)
+  "slide-up",
+  "slide-down",
+  "slide-left",
+  "slide-right",
+  // Flip (4)
+  "flip-left",
+  "flip-right",
+  "flip-up",
+  "flip-down",
+  // Special (2)
+  "slide-rotate",
+  "bounce-in",
+  // Legacy aliases (v2.x backward compat)
+  "fade-in",
+  "fade-in-up",
+  "fade-in-down",
+  "fade-in-left",
+  "fade-in-right",
+  "flip",
+  "flip-x",
+];
+
+/**
+ * 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/aos.d.ts

@@ -0,0 +1,38 @@
+declare namespace _default {
+    export { init };
+    export { refresh };
+    export { refreshHard };
+    export { disable };
+}
+export default _default;
+export type AOSOptions = {
+    offset?: number;
+    delay?: number;
+    duration?: number;
+    easing?: string;
+    once?: boolean;
+    mirror?: boolean;
+    anchorPlacement?: string;
+    disable?: boolean | string;
+    useClassNames?: boolean;
+    startEvent?: string;
+    animatedClassName?: string;
+    initClassName?: string;
+};
+/**
+ * Initialize AOS compatibility mode
+ * @param {AOSOptions} [settings]
+ */
+export function init(settings?: AOSOptions): void;
+/**
+ * Soft refresh — recalculate positions (no-op for IntersectionObserver)
+ */
+export function refresh(): void;
+/**
+ * Hard refresh — destroy and re-process all elements
+ */
+export function refreshHard(): void;
+/**
+ * Disable — remove all AOS attributes and classes
+ */
+export function disable(): void;

package/dist/aos.js

@@ -0,0 +1,273 @@
+/**
+ * AOS compatibility layer for rune-scroller
+ *
+ * Drop-in replacement for AOS (Animate On Scroll).
+ * Supports the same data attributes and init() API.
+ *
+ * Usage:
+ *   import { init, refresh, refreshHard } from 'rune-scroller/aos'
+ *   init()
+ *
+ * Or as AOS drop-in:
+ *   import AOS from 'rune-scroller/aos'
+ *   AOS.init()
+ */
+
+import { runeScroller } from "./runeScroller.js";
+import { ANIMATION_TYPES } from "./animations.js";
+
+/** @typedef {{ offset?: number, delay?: number, duration?: number, easing?: string, once?: boolean, mirror?: boolean, anchorPlacement?: string, disable?: boolean | string, useClassNames?: boolean, startEvent?: string, animatedClassName?: string, initClassName?: string }} AOSOptions */
+
+/**
+ * Map old animation names (v2.x) to new names
+ * @type {Record<string, string>}
+ */
+const LEGACY_MAP = {
+  "fade-in": "fade",
+  "fade-in-up": "fade-up",
+  "fade-in-down": "fade-down",
+  "fade-in-left": "fade-left",
+  "fade-in-right": "fade-right",
+  flip: "flip-left",
+  "flip-x": "flip-up",
+};
+
+/**
+ * Normalize animation name (resolve legacy + validate)
+ * @param {string} name
+ * @returns {string}
+ */
+function resolveAnimation(name) {
+  if (LEGACY_MAP[name]) return LEGACY_MAP[name];
+  if (ANIMATION_TYPES.includes(name)) return name;
+  // Unknown animation — try as-is, CSS will silently ignore
+  return name;
+}
+
+/** @type {AOSOptions} */
+let options = {
+  offset: 120,
+  delay: 0,
+  duration: 400,
+  easing: "ease",
+  once: false,
+  mirror: false,
+  anchorPlacement: "top-bottom",
+  disable: false,
+  useClassNames: false,
+  startEvent: "DOMContentLoaded",
+  animatedClassName: "aos-animate",
+  initClassName: "aos-init",
+};
+
+/** @type {Array<{ destroy: () => void }>} */
+let activeActions = [];
+
+/** @type {MutationObserver | null} */
+let mutationObserver = null;
+
+/** @type {boolean} */
+let initialized = false;
+
+/**
+ * Read a data-aos-* attribute from an element
+ * @param {HTMLElement} el
+ * @param {string} key
+ * @param {*} fallback
+ * @returns {*}
+ */
+function getInlineOption(el, key, fallback) {
+  const attr = el.getAttribute("data-aos-" + key);
+  if (attr === "true") return true;
+  if (attr === "false") return false;
+  return attr || fallback;
+}
+
+/**
+ * Apply rune-scroller action to a single element
+ * @param {HTMLElement} el
+ */
+function applyToElement(el) {
+  const animation = resolveAnimation(el.getAttribute("data-aos") || "fade-up");
+
+  const duration = Number(getInlineOption(el, "duration", options.duration));
+  const delay = Number(getInlineOption(el, "delay", options.delay));
+  const offset = Number(getInlineOption(el, "offset", options.offset));
+  const once = getInlineOption(el, "once", options.once);
+  const mirror = getInlineOption(el, "mirror", options.mirror);
+
+  // Set easing as CSS variable
+  if (options.easing || el.getAttribute("data-aos-easing")) {
+    const easing = getInlineOption(el, "easing", options.easing);
+    el.style.setProperty("--easing", easing);
+  }
+
+  // Add init class
+  if (options.initClassName) {
+    el.classList.add(options.initClassName);
+  }
+
+  // Use useClassNames to add animation name as extra class
+  if (options.useClassNames && animation) {
+    el.classList.add(animation);
+  }
+
+  // Apply runeScroller action
+  const action = runeScroller(el, {
+    animation,
+    duration,
+    offset: offset - 120, // AOS offset is "px from viewport bottom", we adjust
+    repeat: !once || mirror,
+  });
+
+  // Set delay CSS variable AFTER runeScroller (which sets --delay: 0ms)
+  el.style.setProperty("--delay", `${delay}ms`);
+
+  activeActions.push(action);
+}
+
+/**
+ * Process all [data-aos] elements in the DOM
+ */
+function processElements() {
+  /** @type {NodeListOf<HTMLElement>} */
+  const elements = document.querySelectorAll("[data-aos]");
+  elements.forEach(applyToElement);
+}
+
+/**
+ * Watch for new [data-aos] elements added to the DOM
+ */
+function observeMutations() {
+  if (mutationObserver) mutationObserver.disconnect();
+
+  mutationObserver = new MutationObserver((mutations) => {
+    let hasNewAOS = false;
+
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node instanceof HTMLElement) {
+          if (node.hasAttribute && node.hasAttribute("data-aos")) {
+            hasNewAOS = true;
+          }
+          if (node.querySelectorAll) {
+            const aosChildren = node.querySelectorAll("[data-aos]");
+            if (aosChildren.length > 0) hasNewAOS = true;
+          }
+        }
+      }
+    }
+
+    if (hasNewAOS) {
+      refreshHard();
+    }
+  });
+
+  mutationObserver.observe(document.documentElement, {
+    childList: true,
+    subtree: true,
+  });
+}
+
+/**
+ * Initialize AOS compatibility mode
+ * @param {AOSOptions} [settings]
+ */
+function init(settings = {}) {
+  if (typeof window === "undefined") return;
+
+  Object.assign(options, settings);
+
+  // Set global easing on body for CSS
+  const body = document.querySelector("body");
+  if (body) {
+    body.setAttribute("data-aos-easing", options.easing);
+    body.setAttribute("data-aos-duration", String(options.duration));
+    body.setAttribute("data-aos-delay", String(options.delay));
+  }
+
+  // Process elements on start event or immediately
+  const startEvent = options.startEvent || "DOMContentLoaded";
+
+  if (
+    startEvent === "DOMContentLoaded" &&
+    ["complete", "interactive"].includes(document.readyState)
+  ) {
+    processElements();
+    observeMutations();
+    initialized = true;
+  } else if (startEvent === "load") {
+    window.addEventListener("load", () => {
+      processElements();
+      observeMutations();
+      initialized = true;
+    });
+  } else {
+    document.addEventListener(startEvent, () => {
+      processElements();
+      observeMutations();
+      initialized = true;
+    });
+  }
+}
+
+/**
+ * Soft refresh — recalculate positions (no-op for IntersectionObserver)
+ */
+function refresh() {
+  // IntersectionObserver handles position automatically
+  // Only refresh if initialized
+  if (!initialized) return;
+}
+
+/**
+ * Hard refresh — destroy and re-process all elements
+ */
+function refreshHard() {
+  // Destroy all active actions
+  activeActions.forEach((action) => {
+    try {
+      action.destroy();
+    } catch {
+      /* ignore */
+    }
+  });
+  activeActions = [];
+
+  // Remove init classes
+  if (options.initClassName) {
+    document
+      .querySelectorAll(`[data-aos].${options.initClassName}`)
+      .forEach((el) => el.classList.remove(options.initClassName));
+  }
+
+  processElements();
+}
+
+/**
+ * Disable — remove all AOS attributes and classes
+ */
+function disable() {
+  activeActions.forEach((action) => {
+    try {
+      action.destroy();
+    } catch {
+      /* ignore */
+    }
+  });
+  activeActions = [];
+
+  document.querySelectorAll("[data-aos]").forEach((el) => {
+    el.removeAttribute("data-aos");
+    el.removeAttribute("data-aos-easing");
+    el.removeAttribute("data-aos-duration");
+    el.removeAttribute("data-aos-delay");
+    el.removeAttribute("data-aos-offset");
+
+    if (options.initClassName) el.classList.remove(options.initClassName);
+  });
+}
+
+// Public API — compatible with AOS
+export default { init, refresh, refreshHard, disable };
+export { init, refresh, refreshHard, disable };

package/dist/dom-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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

@@ -0,0 +1,118 @@
+/**
+ * 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 (typeof process !== "undefined" && 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

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

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * 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 };
+export { runeScroller as rs };
+
+// Composables
+export {
+  useIntersection,
+  useIntersectionOnce,
+} from "./useIntersection.svelte.js";
+
+// Utilities
+export { calculateRootMargin, ANIMATION_TYPES } from "./animations.js";

package/dist/observer-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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

@@ -0,0 +1,31 @@
+/**
+ * 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

@@ -0,0 +1,9 @@
+/**
+ * @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

@@ -0,0 +1,184 @@
+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 (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+      console.warn(
+        `[rune-scroller] Invalid animation "${animation}". Using "fade-in" instead. ` +
+          `Valid options: ${ANIMATION_TYPES.join(", ")}`,
+      );
+    }
+    animation = "fade-in";
+  }
+
+  // CSS handles initial opacity via [data-animation] { opacity: 0 }
+  // No inline opacity needed — it would override slide animations that use opacity: 1
+
+  // Setup animation classes and CSS variables
+  if (animation) {
+    setupAnimationElement(element, animation);
+  }
+
+  // Warn about overflow:hidden in debug mode
+  if (options?.debug && element.style.overflow === "hidden") {
+    console.warn(
+      "[rune-scroller] Element has overflow:hidden — the sentinel indicator may be clipped in debug mode.",
+    );
+  }
+
+  // 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

@@ -0,0 +1,79 @@
+/**
+ * Animation type names (includes AOS-compatible names)
+ */
+export type AnimationType = "fade" | "fade-up" | "fade-down" | "fade-left" | "fade-right" | "fade-up-right" | "fade-up-left" | "fade-down-right" | "fade-down-left" | "zoom-in" | "zoom-in-up" | "zoom-in-down" | "zoom-in-left" | "zoom-in-right" | "zoom-out" | "zoom-out-up" | "zoom-out-down" | "zoom-out-left" | "zoom-out-right" | "slide-up" | "slide-down" | "slide-left" | "slide-right" | "flip-left" | "flip-right" | "flip-up" | "flip-down" | "slide-rotate" | "bounce-in" | "fade-in" | "fade-in-up" | "fade-in-down" | "fade-in-left" | "fade-in-right" | "flip" | "flip-x";
+/**
+ * Options for the runeScroller action
+ */
+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
+     */
+    sentinelColor?: string | undefined;
+    /**
+     * - Unique identifier for sentinel
+     */
+    sentinelId?: string | undefined;
+    /**
+     * - Debug label to show on sentinel
+     */
+    debugLabel?: string | undefined;
+    /**
+     * - Offset of sentinel in pixels (negative = above element)
+     */
+    offset?: number | undefined;
+    /**
+     * - CSS timing function
+     */
+    easing?: string | undefined;
+    /**
+     * - Callback when animation triggers
+     */
+    onVisible?: ((element: HTMLElement) => void) | undefined;
+};
+/**
+ * Configuration options for IntersectionObserver
+ */
+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
+ */
+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

@@ -0,0 +1,40 @@
+/**
+ * Centralized type definitions for Rune Scroller library
+ */
+
+/**
+ * Animation type names (includes AOS-compatible names)
+ * @typedef {'fade' | 'fade-up' | 'fade-down' | 'fade-left' | 'fade-right' | 'fade-up-right' | 'fade-up-left' | 'fade-down-right' | 'fade-down-left' | 'zoom-in' | 'zoom-in-up' | 'zoom-in-down' | 'zoom-in-left' | 'zoom-in-right' | 'zoom-out' | 'zoom-out-up' | 'zoom-out-down' | 'zoom-out-left' | 'zoom-out-right' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'flip-left' | 'flip-right' | 'flip-up' | 'flip-down' | 'slide-rotate' | 'bounce-in' | 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left' | 'fade-in-right' | 'flip' | 'flip-x'} AnimationType
+ */
+
+/**
+ * Options for the runeScroller action
+ * @typedef {Object} RuneScrollerOptions
+ * @property {AnimationType} [animation='fade-up'] - Animation type to apply
+ * @property {number} [duration=400] - 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
+ * @property {string} [sentinelId] - Unique identifier for sentinel
+ * @property {string} [debugLabel] - Debug label to show on sentinel
+ * @property {number} [offset=0] - Offset of sentinel in pixels (negative = above element)
+ * @property {string} [easing='ease'] - CSS timing function
+ * @property {(element: HTMLElement) => void} [onVisible] - Callback when animation triggers
+ */
+
+/**
+ * Configuration options for IntersectionObserver
+ * @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
+ * @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

@@ -0,0 +1,11 @@
+/**
+ * @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

@@ -0,0 +1,98 @@
+/**
+ * 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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rune-scroller",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Lightweight scroll animations for Svelte 5. Drop-in AOS replacement. 30 animations, zero dependencies.",
   "type": "module",
   "sideEffects": false,