domet 1.0.6 → 1.1.1

package/dist/es/index.mjs

@@ -1,40 +1,410 @@
-import { useMemo, useState, useRef, useCallback, useLayoutEffect, useEffect } from 'react';
+'use client';
+import { useLayoutEffect, useEffect, useMemo, useRef, useState, useCallback } from 'react';
 
-const DEFAULT_VISIBILITY_THRESHOLD = 0.6;
-const DEFAULT_HYSTERESIS_MARGIN = 150;
+const DEFAULT_THRESHOLD = 0.6;
+const DEFAULT_HYSTERESIS = 150;
+const DEFAULT_OFFSET = 0;
+const DEFAULT_THROTTLE = 10;
 const SCROLL_IDLE_MS = 100;
+const MIN_SCROLL_THRESHOLD = 10;
+const EDGE_TOLERANCE = 5;
+
+const PERCENT_REGEX$1 = /^(-?\d+(?:\.\d+)?)%$/;
+const VALIDATION_LIMITS = {
+    offset: {
+        min: -1e4,
+        max: 10000
+    },
+    offsetPercent: {
+        min: -500,
+        max: 500
+    },
+    threshold: {
+        min: 0,
+        max: 1
+    },
+    hysteresis: {
+        min: 0,
+        max: 1000
+    },
+    throttle: {
+        min: 0,
+        max: 1000
+    }
+};
+function warn(message) {
+    if (process.env.NODE_ENV !== "production") {
+        console.warn(`[domet] ${message}`);
+    }
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function sanitizeOffset(offset) {
+    if (offset === undefined) {
+        return DEFAULT_OFFSET;
+    }
+    if (typeof offset === "number") {
+        if (!isFiniteNumber(offset)) {
+            warn(`Invalid offset value: ${offset}. Using default.`);
+            return DEFAULT_OFFSET;
+        }
+        const { min, max } = VALIDATION_LIMITS.offset;
+        if (offset < min || offset > max) {
+            warn(`Offset ${offset} clamped to [${min}, ${max}].`);
+            return clamp(offset, min, max);
+        }
+        return offset;
+    }
+    if (typeof offset === "string") {
+        const trimmed = offset.trim();
+        const match = PERCENT_REGEX$1.exec(trimmed);
+        if (!match) {
+            warn(`Invalid offset format: "${offset}". Using default.`);
+            return DEFAULT_OFFSET;
+        }
+        const percent = parseFloat(match[1]);
+        if (!isFiniteNumber(percent)) {
+            warn(`Invalid percentage value in offset: "${offset}". Using default.`);
+            return DEFAULT_OFFSET;
+        }
+        const { min, max } = VALIDATION_LIMITS.offsetPercent;
+        if (percent < min || percent > max) {
+            warn(`Offset percentage ${percent}% clamped to [${min}%, ${max}%].`);
+            return `${clamp(percent, min, max)}%`;
+        }
+        return trimmed;
+    }
+    warn(`Invalid offset type: ${typeof offset}. Using default.`);
+    return DEFAULT_OFFSET;
+}
+function sanitizeThreshold(threshold) {
+    if (threshold === undefined) {
+        return DEFAULT_THRESHOLD;
+    }
+    if (!isFiniteNumber(threshold)) {
+        warn(`Invalid threshold value: ${threshold}. Using default.`);
+        return DEFAULT_THRESHOLD;
+    }
+    const { min, max } = VALIDATION_LIMITS.threshold;
+    if (threshold < min || threshold > max) {
+        warn(`Threshold ${threshold} clamped to [${min}, ${max}].`);
+        return clamp(threshold, min, max);
+    }
+    return threshold;
+}
+function sanitizeHysteresis(hysteresis) {
+    if (hysteresis === undefined) {
+        return DEFAULT_HYSTERESIS;
+    }
+    if (!isFiniteNumber(hysteresis)) {
+        warn(`Invalid hysteresis value: ${hysteresis}. Using default.`);
+        return DEFAULT_HYSTERESIS;
+    }
+    const { min, max } = VALIDATION_LIMITS.hysteresis;
+    if (hysteresis < min || hysteresis > max) {
+        warn(`Hysteresis ${hysteresis} clamped to [${min}, ${max}].`);
+        return clamp(hysteresis, min, max);
+    }
+    return hysteresis;
+}
+function sanitizeThrottle(throttle) {
+    if (throttle === undefined) {
+        return DEFAULT_THROTTLE;
+    }
+    if (!isFiniteNumber(throttle)) {
+        warn(`Invalid throttle value: ${throttle}. Using default.`);
+        return DEFAULT_THROTTLE;
+    }
+    const { min, max } = VALIDATION_LIMITS.throttle;
+    if (throttle < min || throttle > max) {
+        warn(`Throttle ${throttle} clamped to [${min}, ${max}].`);
+        return clamp(throttle, min, max);
+    }
+    return throttle;
+}
+function sanitizeIds(ids) {
+    if (!ids || !Array.isArray(ids)) {
+        warn("Invalid ids: expected an array. Using empty array.");
+        return [];
+    }
+    const seen = new Set();
+    const sanitized = [];
+    for (const id of ids){
+        if (typeof id !== "string") {
+            warn(`Invalid id type: ${typeof id}. Skipping.`);
+            continue;
+        }
+        const trimmed = id.trim();
+        if (trimmed === "") {
+            warn("Empty string id detected. Skipping.");
+            continue;
+        }
+        if (seen.has(trimmed)) {
+            warn(`Duplicate id "${trimmed}" detected. Skipping.`);
+            continue;
+        }
+        seen.add(trimmed);
+        sanitized.push(trimmed);
+    }
+    return sanitized;
+}
+function sanitizeSelector(selector) {
+    if (selector === undefined) {
+        return "";
+    }
+    if (typeof selector !== "string") {
+        warn(`Invalid selector type: ${typeof selector}. Using empty string.`);
+        return "";
+    }
+    const trimmed = selector.trim();
+    if (trimmed === "") {
+        warn("Empty selector provided.");
+    }
+    return trimmed;
+}
+
+const PERCENT_REGEX = /^(-?\d+(?:\.\d+)?)%$/;
+function resolveContainer(input) {
+    if (typeof window === "undefined") return null;
+    if (input === undefined) return null;
+    return input.current;
+}
+function resolveSectionsFromIds(ids, refs) {
+    return ids.map((id)=>({
+            id,
+            element: refs[id]
+        })).filter((s)=>s.element != null);
+}
+function resolveSectionsFromSelector(selector) {
+    if (typeof window === "undefined") return [];
+    try {
+        const elements = document.querySelectorAll(selector);
+        return Array.from(elements).map((el, index)=>({
+                id: el.id || el.dataset.domet || `section-${index}`,
+                element: el
+            }));
+    } catch  {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn(`[domet] Invalid CSS selector: "${selector}"`);
+        }
+        return [];
+    }
+}
+function resolveOffset(offset, viewportHeight, defaultOffset) {
+    const value = offset ?? defaultOffset;
+    const safeViewportHeight = Number.isFinite(viewportHeight) ? viewportHeight : 0;
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : 0;
+    }
+    const match = PERCENT_REGEX.exec(value);
+    if (match) {
+        const percent = parseFloat(match[1]);
+        if (!Number.isFinite(percent)) return 0;
+        return percent / 100 * safeViewportHeight;
+    }
+    return 0;
+}
+
+function getSectionBounds(sections, container) {
+    const scrollTop = container ? container.scrollTop : window.scrollY;
+    const containerTop = container ? container.getBoundingClientRect().top : 0;
+    return sections.map(({ id, element })=>{
+        const rect = element.getBoundingClientRect();
+        const relativeTop = container ? rect.top - containerTop + scrollTop : rect.top + window.scrollY;
+        return {
+            id,
+            top: relativeTop,
+            bottom: relativeTop + rect.height,
+            height: rect.height
+        };
+    });
+}
+function calculateSectionScores(sectionBounds, sections, ctx) {
+    const { scrollY, viewportHeight, effectiveOffset, visibilityThreshold} = ctx;
+    const viewportTop = scrollY;
+    const viewportBottom = scrollY + viewportHeight;
+    const maxScroll = Math.max(1, ctx.scrollHeight - viewportHeight);
+    const scrollProgress = Math.min(1, Math.max(0, scrollY / maxScroll));
+    const dynamicOffset = effectiveOffset + scrollProgress * (viewportHeight - effectiveOffset);
+    const triggerLine = scrollY + dynamicOffset;
+    const elementMap = new Map(sections.map((s)=>[
+            s.id,
+            s.element
+        ]));
+    return sectionBounds.map((section)=>{
+        const visibleTop = Math.max(section.top, viewportTop);
+        const visibleBottom = Math.min(section.bottom, viewportBottom);
+        const visibleHeight = Math.max(0, visibleBottom - visibleTop);
+        const visibilityRatio = section.height > 0 ? visibleHeight / section.height : 0;
+        const visibleInViewportRatio = viewportHeight > 0 ? visibleHeight / viewportHeight : 0;
+        const isInView = section.bottom > viewportTop && section.top < viewportBottom;
+        const sectionProgress = (()=>{
+            if (section.height === 0) return 0;
+            const entryPoint = viewportBottom;
+            const totalTravel = viewportHeight + section.height;
+            const traveled = entryPoint - section.top;
+            return Math.max(0, Math.min(1, traveled / totalTravel));
+        })();
+        let score = 0;
+        if (visibilityRatio >= visibilityThreshold) {
+            score += 1000 + visibilityRatio * 500;
+        } else if (isInView) {
+            score += visibleInViewportRatio * 800;
+        }
+        if (isInView) {
+            const containsTriggerLine = triggerLine >= section.top && triggerLine < section.bottom;
+            if (containsTriggerLine) {
+                score += 300;
+            }
+            const sectionCenter = section.top + section.height / 2;
+            const distanceFromTrigger = Math.abs(sectionCenter - triggerLine);
+            const maxDistance = viewportHeight;
+            const proximityScore = Math.max(0, 1 - distanceFromTrigger / maxDistance) * 500;
+            score += proximityScore;
+        }
+        const element = elementMap.get(section.id);
+        const rect = element ? element.getBoundingClientRect() : null;
+        return {
+            id: section.id,
+            score,
+            visibilityRatio,
+            inView: isInView,
+            bounds: section,
+            progress: sectionProgress,
+            rect
+        };
+    });
+}
+function determineActiveSection(scores, sectionIds, currentActiveId, hysteresisMargin, scrollY, viewportHeight, scrollHeight) {
+    if (scores.length === 0 || sectionIds.length === 0) return null;
+    const scoredIds = new Set(scores.map((s)=>s.id));
+    const maxScroll = Math.max(0, scrollHeight - viewportHeight);
+    const hasScroll = maxScroll > MIN_SCROLL_THRESHOLD;
+    const isAtBottom = hasScroll && scrollY + viewportHeight >= scrollHeight - EDGE_TOLERANCE;
+    const isAtTop = hasScroll && scrollY <= EDGE_TOLERANCE;
+    if (isAtBottom && sectionIds.length >= 2) {
+        const lastId = sectionIds[sectionIds.length - 1];
+        const secondLastId = sectionIds[sectionIds.length - 2];
+        const secondLastScore = scores.find((s)=>s.id === secondLastId);
+        const secondLastNotVisible = !secondLastScore || !secondLastScore.inView;
+        if (scoredIds.has(lastId) && secondLastNotVisible) {
+            return lastId;
+        }
+    }
+    if (isAtTop && sectionIds.length >= 2) {
+        const firstId = sectionIds[0];
+        const secondId = sectionIds[1];
+        const secondScore = scores.find((s)=>s.id === secondId);
+        const secondNotVisible = !secondScore || !secondScore.inView;
+        if (scoredIds.has(firstId) && secondNotVisible) {
+            return firstId;
+        }
+    }
+    const visibleScores = scores.filter((s)=>s.inView);
+    const candidates = visibleScores.length > 0 ? visibleScores : scores;
+    const sorted = [
+        ...candidates
+    ].sort((a, b)=>b.score - a.score);
+    if (sorted.length === 0) return null;
+    const bestCandidate = sorted[0];
+    const currentScore = scores.find((s)=>s.id === currentActiveId);
+    const shouldSwitch = !currentScore || !currentScore.inView || bestCandidate.score > currentScore.score + hysteresisMargin || bestCandidate.id === currentActiveId;
+    return shouldSwitch ? bestCandidate.id : currentActiveId;
+}
+
 const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
-function useDomet(sectionIds, containerRef = null, options = {}) {
-    const { offset = 0, offsetRatio = 0.08, debounceMs = 10, visibilityThreshold = DEFAULT_VISIBILITY_THRESHOLD, hysteresisMargin = DEFAULT_HYSTERESIS_MARGIN, behavior = "auto", onActiveChange, onSectionEnter, onSectionLeave, onScrollStart, onScrollEnd } = options;
-    JSON.stringify(sectionIds);
-    const stableSectionIds = useMemo(()=>sectionIds, [
-        sectionIds
+function areIdInputsEqual(a, b) {
+    if (Object.is(a, b)) return true;
+    if (!Array.isArray(a) || !Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for(let i = 0; i < a.length; i++){
+        if (!Object.is(a[i], b[i])) return false;
+    }
+    return true;
+}
+
+function useDomet(options) {
+    const { container: containerInput, tracking, scrolling, onActive, onEnter, onLeave, onScrollStart, onScrollEnd } = options;
+    const trackingOffset = sanitizeOffset(tracking?.offset);
+    const throttle = sanitizeThrottle(tracking?.throttle);
+    const threshold = sanitizeThreshold(tracking?.threshold);
+    const hysteresis = sanitizeHysteresis(tracking?.hysteresis);
+    const scrollingDefaults = useMemo(()=>{
+        if (!scrolling) {
+            return {
+                behavior: "auto",
+                offset: undefined,
+                position: undefined,
+                lockActive: undefined
+            };
+        }
+        return {
+            behavior: scrolling.behavior ?? "auto",
+            offset: scrolling.offset !== undefined ? sanitizeOffset(scrolling.offset) : undefined,
+            position: scrolling.position,
+            lockActive: scrolling.lockActive
+        };
+    }, [
+        scrolling
     ]);
-    const sectionIndexMap = useMemo(()=>{
-        const map = new Map();
-        for(let i = 0; i < stableSectionIds.length; i++){
-            map.set(stableSectionIds[i], i);
+    const rawIds = "ids" in options ? options.ids : undefined;
+    const rawSelector = "selector" in options ? options.selector : undefined;
+    const idsCacheRef = useRef({
+        raw: undefined,
+        sanitized: undefined
+    });
+    const idsArray = useMemo(()=>{
+        if (rawIds === undefined) {
+            idsCacheRef.current = {
+                raw: undefined,
+                sanitized: undefined
+            };
+            return undefined;
         }
-        return map;
+        if (areIdInputsEqual(rawIds, idsCacheRef.current.raw)) {
+            idsCacheRef.current.raw = rawIds;
+            return idsCacheRef.current.sanitized;
+        }
+        const sanitized = sanitizeIds(rawIds);
+        idsCacheRef.current = {
+            raw: rawIds,
+            sanitized
+        };
+        return sanitized;
     }, [
-        stableSectionIds
+        rawIds
     ]);
-    const [activeId, setActiveId] = useState(stableSectionIds[0] || null);
+    const selectorString = useMemo(()=>{
+        if (rawSelector === undefined) return undefined;
+        return sanitizeSelector(rawSelector);
+    }, [
+        rawSelector
+    ]);
+    const useSelector = selectorString !== undefined && selectorString !== "";
+    const initialActiveId = idsArray && idsArray.length > 0 ? idsArray[0] : null;
+    const [containerElement, setContainerElement] = useState(null);
+    const [resolvedSections, setResolvedSections] = useState([]);
+    const [activeId, setActiveId] = useState(initialActiveId);
     const [scroll, setScroll] = useState({
         y: 0,
         progress: 0,
         direction: null,
         velocity: 0,
-        isScrolling: false,
+        scrolling: false,
         maxScroll: 0,
         viewportHeight: 0,
-        offset: 0
+        trackingOffset: 0,
+        triggerLine: 0
     });
     const [sections, setSections] = useState({});
-    const [containerElement, setContainerElement] = useState(null);
     const refs = useRef({});
     const refCallbacks = useRef({});
-    const activeIdRef = useRef(stableSectionIds[0] || null);
+    const registerPropsCache = useRef({});
+    const activeIdRef = useRef(initialActiveId);
     const lastScrollY = useRef(0);
     const lastScrollTime = useRef(Date.now());
     const rafId = useRef(null);
@@ -42,50 +412,174 @@ function useDomet(sectionIds, containerRef = null, options = {}) {
     const throttleTimeoutId = useRef(null);
     const hasPendingScroll = useRef(false);
     const isProgrammaticScrolling = useRef(false);
-    const programmaticScrollTimeoutId = useRef(null);
     const isScrollingRef = useRef(false);
     const scrollIdleTimeoutRef = useRef(null);
     const prevSectionsInViewport = useRef(new Set());
     const recalculateRef = useRef(()=>{});
+    const scheduleRecalculate = useCallback(()=>{
+        if (typeof window === "undefined") return;
+        if (rafId.current) {
+            cancelAnimationFrame(rafId.current);
+        }
+        rafId.current = requestAnimationFrame(()=>{
+            rafId.current = null;
+            recalculateRef.current();
+        });
+    }, []);
     const scrollCleanupRef = useRef(null);
+    const mutationObserverRef = useRef(null);
+    const mutationDebounceRef = useRef(null);
+    const optionsRef = useRef({
+        trackingOffset,
+        scrolling: scrollingDefaults
+    });
     const callbackRefs = useRef({
-        onActiveChange,
-        onSectionEnter,
-        onSectionLeave,
+        onActive,
+        onEnter,
+        onLeave,
         onScrollStart,
         onScrollEnd
     });
-    callbackRefs.current = {
-        onActiveChange,
-        onSectionEnter,
-        onSectionLeave,
+    useIsomorphicLayoutEffect(()=>{
+        optionsRef.current = {
+            trackingOffset,
+            scrolling: scrollingDefaults
+        };
+    }, [
+        trackingOffset,
+        scrollingDefaults
+    ]);
+    useEffect(()=>{
+        scheduleRecalculate();
+    }, [
+        trackingOffset,
+        scheduleRecalculate
+    ]);
+    useIsomorphicLayoutEffect(()=>{
+        callbackRefs.current = {
+            onActive,
+            onEnter,
+            onLeave,
+            onScrollStart,
+            onScrollEnd
+        };
+    }, [
+        onActive,
+        onEnter,
+        onLeave,
         onScrollStart,
         onScrollEnd
-    };
-    const getEffectiveOffset = useCallback(()=>{
-        return offset;
+    ]);
+    const sectionIds = useMemo(()=>{
+        if (!useSelector && idsArray) return idsArray;
+        return resolvedSections.map((s)=>s.id);
     }, [
-        offset
+        useSelector,
+        idsArray,
+        resolvedSections
     ]);
-    const getScrollBehavior = useCallback(()=>{
-        if (behavior === "auto") {
-            if (typeof window === "undefined") return "instant";
-            const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-            return prefersReducedMotion ? "instant" : "smooth";
+    const sectionIndexMap = useMemo(()=>{
+        const map = new Map();
+        for(let i = 0; i < sectionIds.length; i++){
+            map.set(sectionIds[i], i);
         }
-        return behavior;
+        return map;
     }, [
-        behavior
+        sectionIds
     ]);
+    const containerRefCurrent = containerInput?.current ?? null;
     useIsomorphicLayoutEffect(()=>{
-        var _ref;
-        const nextContainer = (_ref = containerRef == null ? void 0 : containerRef.current) != null ? _ref : null;
-        if (nextContainer !== containerElement) {
-            setContainerElement(nextContainer);
+        const resolved = resolveContainer(containerInput);
+        if (resolved !== containerElement) {
+            setContainerElement(resolved);
+        }
+    }, [
+        containerInput,
+        containerRefCurrent
+    ]);
+    const updateSectionsFromSelector = useCallback((selector)=>{
+        const resolved = resolveSectionsFromSelector(selector);
+        setResolvedSections(resolved);
+        if (resolved.length > 0) {
+            const currentStillExists = resolved.some((s)=>s.id === activeIdRef.current);
+            if (!activeIdRef.current || !currentStillExists) {
+                activeIdRef.current = resolved[0].id;
+                setActiveId(resolved[0].id);
+            }
+        } else if (activeIdRef.current !== null) {
+            activeIdRef.current = null;
+            setActiveId(null);
+        }
+    }, []);
+    useIsomorphicLayoutEffect(()=>{
+        if (useSelector && selectorString) {
+            updateSectionsFromSelector(selectorString);
+        }
+    }, [
+        selectorString,
+        useSelector,
+        updateSectionsFromSelector
+    ]);
+    useEffect(()=>{
+        if (!useSelector || !selectorString || typeof window === "undefined" || typeof MutationObserver === "undefined") {
+            return;
         }
+        const handleMutation = ()=>{
+            if (mutationDebounceRef.current) {
+                clearTimeout(mutationDebounceRef.current);
+            }
+            mutationDebounceRef.current = setTimeout(()=>{
+                updateSectionsFromSelector(selectorString);
+            }, 50);
+        };
+        mutationObserverRef.current = new MutationObserver(handleMutation);
+        mutationObserverRef.current.observe(document.body, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: [
+                "id",
+                "data-domet"
+            ]
+        });
+        return ()=>{
+            if (mutationDebounceRef.current) {
+                clearTimeout(mutationDebounceRef.current);
+                mutationDebounceRef.current = null;
+            }
+            if (mutationObserverRef.current) {
+                mutationObserverRef.current.disconnect();
+                mutationObserverRef.current = null;
+            }
+        };
     }, [
-        containerRef,
-        containerElement
+        useSelector,
+        selectorString,
+        updateSectionsFromSelector
+    ]);
+    useEffect(()=>{
+        if (!useSelector && idsArray) {
+            const idsSet = new Set(idsArray);
+            for (const id of Object.keys(refs.current)){
+                if (!idsSet.has(id)) {
+                    delete refs.current[id];
+                }
+            }
+            for (const id of Object.keys(refCallbacks.current)){
+                if (!idsSet.has(id)) {
+                    delete refCallbacks.current[id];
+                }
+            }
+            const currentActive = activeIdRef.current;
+            const nextActive = currentActive && idsSet.has(currentActive) ? currentActive : idsArray[0] ?? null;
+            if (nextActive !== currentActive) {
+                activeIdRef.current = nextActive;
+                setActiveId(nextActive);
+            }
+        }
+    }, [
+        idsArray,
+        useSelector
     ]);
     const registerRef = useCallback((id)=>{
         const existing = refCallbacks.current[id];
@@ -96,323 +590,341 @@ function useDomet(sectionIds, containerRef = null, options = {}) {
             } else {
                 delete refs.current[id];
             }
+            scheduleRecalculate();
         };
         refCallbacks.current[id] = callback;
         return callback;
-    }, []);
-    const scrollToSection = useCallback((id)=>{
-        if (!stableSectionIds.includes(id)) {
-            if (process.env.NODE_ENV !== "production") {
-                console.warn(`[domet] scrollToSection: id "${id}" not in sectionIds`);
+    }, [
+        scheduleRecalculate
+    ]);
+    const getResolvedBehavior = useCallback((behaviorOverride)=>{
+        const b = behaviorOverride ?? optionsRef.current.scrolling.behavior;
+        if (b === "auto") {
+            if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+                return "smooth";
             }
-            return;
+            const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+            return prefersReducedMotion ? "instant" : "smooth";
         }
-        const element = refs.current[id];
-        if (!element) return;
-        if (programmaticScrollTimeoutId.current) {
-            clearTimeout(programmaticScrollTimeoutId.current);
+        return b;
+    }, []);
+    const getCurrentSections = useCallback(()=>{
+        if (!useSelector && idsArray) {
+            return resolveSectionsFromIds(idsArray, refs.current);
         }
-        scrollCleanupRef.current == null ? void 0 : scrollCleanupRef.current.call(scrollCleanupRef);
-        isProgrammaticScrolling.current = true;
-        activeIdRef.current = id;
-        setActiveId(id);
+        return resolvedSections;
+    }, [
+        useSelector,
+        idsArray,
+        resolvedSections
+    ]);
+    const scrollTo = useCallback((target, scrollOptions)=>{
+        const resolvedTarget = typeof target === "string" ? {
+            type: "id",
+            id: target
+        } : "id" in target ? {
+            type: "id",
+            id: target.id
+        } : {
+            type: "top",
+            top: target.top
+        };
+        const defaultScroll = optionsRef.current.scrolling;
+        const lockActive = scrollOptions?.lockActive ?? defaultScroll.lockActive ?? resolvedTarget.type === "id";
         const container = containerElement;
-        const elementRect = element.getBoundingClientRect();
-        const effectiveOffset = getEffectiveOffset() + 10;
         const scrollTarget = container || window;
-        const unlockScroll = ()=>{
-            isProgrammaticScrolling.current = false;
-            if (programmaticScrollTimeoutId.current) {
-                clearTimeout(programmaticScrollTimeoutId.current);
-                programmaticScrollTimeoutId.current = null;
+        const viewportHeight = container ? container.clientHeight : window.innerHeight;
+        const scrollHeight = container ? container.scrollHeight : document.documentElement.scrollHeight;
+        const maxScroll = Math.max(0, scrollHeight - viewportHeight);
+        const scrollBehavior = getResolvedBehavior(scrollOptions?.behavior ?? defaultScroll.behavior);
+        const offsetCandidate = scrollOptions?.offset ?? defaultScroll.offset;
+        const offsetValue = sanitizeOffset(offsetCandidate);
+        const effectiveOffset = resolveOffset(offsetValue, viewportHeight, DEFAULT_OFFSET);
+        const stopProgrammaticScroll = ()=>{
+            if (scrollCleanupRef.current) {
+                scrollCleanupRef.current();
+                scrollCleanupRef.current = null;
             }
-            requestAnimationFrame(()=>{
-                recalculateRef.current();
-            });
+            isProgrammaticScrolling.current = false;
         };
-        let debounceTimer = null;
-        let isUnlocked = false;
-        const cleanup = ()=>{
-            if (debounceTimer) {
-                clearTimeout(debounceTimer);
-                debounceTimer = null;
-            }
-            scrollTarget.removeEventListener("scroll", handleScrollActivity);
+        if (!lockActive) {
+            stopProgrammaticScroll();
+        } else if (scrollCleanupRef.current) {
+            scrollCleanupRef.current();
+        }
+        const setupLock = ()=>{
+            const unlockScroll = ()=>{
+                isProgrammaticScrolling.current = false;
+            };
+            let debounceTimer = null;
+            let isUnlocked = false;
+            const cleanup = ()=>{
+                if (debounceTimer) {
+                    clearTimeout(debounceTimer);
+                    debounceTimer = null;
+                }
+                scrollTarget.removeEventListener("scroll", handleScrollActivity);
+                if ("onscrollend" in scrollTarget) {
+                    scrollTarget.removeEventListener("scrollend", handleScrollEnd);
+                }
+                scrollCleanupRef.current = null;
+            };
+            const doUnlock = ()=>{
+                if (isUnlocked) return;
+                isUnlocked = true;
+                cleanup();
+                unlockScroll();
+            };
+            const resetDebounce = ()=>{
+                if (debounceTimer) {
+                    clearTimeout(debounceTimer);
+                }
+                debounceTimer = setTimeout(doUnlock, SCROLL_IDLE_MS);
+            };
+            const handleScrollActivity = ()=>{
+                resetDebounce();
+            };
+            const handleScrollEnd = ()=>{
+                doUnlock();
+            };
+            scrollTarget.addEventListener("scroll", handleScrollActivity, {
+                passive: true
+            });
             if ("onscrollend" in scrollTarget) {
-                scrollTarget.removeEventListener("scrollend", handleScrollEnd);
+                scrollTarget.addEventListener("scrollend", handleScrollEnd, {
+                    once: true
+                });
             }
-            scrollCleanupRef.current = null;
-        };
-        const doUnlock = ()=>{
-            if (isUnlocked) return;
-            isUnlocked = true;
-            cleanup();
-            unlockScroll();
+            scrollCleanupRef.current = cleanup;
+            return {
+                doUnlock,
+                resetDebounce
+            };
         };
-        const resetDebounce = ()=>{
-            if (debounceTimer) {
-                clearTimeout(debounceTimer);
+        const clampValue = (value, min, max)=>Math.max(min, Math.min(max, value));
+        let targetScroll = null;
+        let activeTargetId = null;
+        if (resolvedTarget.type === "id") {
+            const id = resolvedTarget.id;
+            if (!sectionIndexMap.has(id)) {
+                if (process.env.NODE_ENV !== "production") {
+                    console.warn(`[domet] scrollTo: id "${id}" not found`);
+                }
+                return;
             }
-            debounceTimer = setTimeout(doUnlock, SCROLL_IDLE_MS);
-        };
-        const handleScrollActivity = ()=>{
-            resetDebounce();
-        };
-        const handleScrollEnd = ()=>{
-            doUnlock();
-        };
-        scrollTarget.addEventListener("scroll", handleScrollActivity, {
-            passive: true
-        });
-        if ("onscrollend" in scrollTarget) {
-            scrollTarget.addEventListener("scrollend", handleScrollEnd, {
-                once: true
-            });
+            const currentSections = getCurrentSections();
+            const section = currentSections.find((s)=>s.id === id);
+            if (!section) {
+                if (process.env.NODE_ENV !== "production") {
+                    console.warn(`[domet] scrollTo: element for id "${id}" not yet mounted`);
+                }
+                return;
+            }
+            const elementRect = section.element.getBoundingClientRect();
+            const position = scrollOptions?.position ?? defaultScroll.position;
+            const sectionTop = container ? elementRect.top - container.getBoundingClientRect().top + container.scrollTop : elementRect.top + window.scrollY;
+            const sectionHeight = elementRect.height;
+            const calculateTargetScroll = ()=>{
+                if (maxScroll <= 0) return 0;
+                const topTarget = sectionTop - effectiveOffset;
+                const centerTarget = sectionTop - (viewportHeight - sectionHeight) / 2;
+                const bottomTarget = sectionTop + sectionHeight - viewportHeight;
+                if (position === "top") {
+                    return clampValue(topTarget, 0, maxScroll);
+                }
+                if (position === "center") {
+                    return clampValue(centerTarget, 0, maxScroll);
+                }
+                if (position === "bottom") {
+                    return clampValue(bottomTarget, 0, maxScroll);
+                }
+                const fits = sectionHeight <= viewportHeight;
+                const dynamicRange = viewportHeight - effectiveOffset;
+                const denominator = dynamicRange !== 0 ? 1 + dynamicRange / maxScroll : 1;
+                const triggerMin = (sectionTop - effectiveOffset) / denominator;
+                const triggerMax = (sectionTop + sectionHeight - effectiveOffset) / denominator;
+                if (fits) {
+                    if (centerTarget >= triggerMin && centerTarget <= triggerMax) {
+                        return clampValue(centerTarget, 0, maxScroll);
+                    }
+                    if (centerTarget < triggerMin) {
+                        return clampValue(triggerMin, 0, maxScroll);
+                    }
+                    return clampValue(triggerMax, 0, maxScroll);
+                }
+                return clampValue(topTarget, 0, maxScroll);
+            };
+            targetScroll = calculateTargetScroll();
+            activeTargetId = id;
+        } else {
+            const top = resolvedTarget.top;
+            if (!Number.isFinite(top)) {
+                if (process.env.NODE_ENV !== "production") {
+                    console.warn(`[domet] scrollTo: top "${top}" is not a valid number`);
+                }
+                return;
+            }
+            targetScroll = clampValue(top - effectiveOffset, 0, maxScroll);
         }
-        scrollCleanupRef.current = cleanup;
-        const scrollBehavior = getScrollBehavior();
+        if (targetScroll === null) return;
+        if (lockActive) {
+            isProgrammaticScrolling.current = true;
+            if (activeTargetId) {
+                activeIdRef.current = activeTargetId;
+                setActiveId(activeTargetId);
+            }
+        }
+        const lockControls = lockActive ? setupLock() : null;
         if (container) {
-            const containerRect = container.getBoundingClientRect();
-            const relativeTop = elementRect.top - containerRect.top + container.scrollTop;
             container.scrollTo({
-                top: relativeTop - effectiveOffset,
+                top: targetScroll,
                 behavior: scrollBehavior
             });
         } else {
-            const absoluteTop = elementRect.top + window.scrollY;
             window.scrollTo({
-                top: absoluteTop - effectiveOffset,
+                top: targetScroll,
                 behavior: scrollBehavior
             });
         }
-        if (scrollBehavior === "instant") {
-            doUnlock();
-        } else {
-            resetDebounce();
+        if (lockControls) {
+            if (scrollBehavior === "instant") {
+                lockControls.doUnlock();
+            } else {
+                lockControls.resetDebounce();
+            }
         }
     }, [
-        stableSectionIds,
+        sectionIndexMap,
         containerElement,
-        getEffectiveOffset,
-        getScrollBehavior
+        getResolvedBehavior,
+        getCurrentSections
     ]);
-    const sectionProps = useCallback((id)=>({
+    const register = useCallback((id)=>{
+        const cached = registerPropsCache.current[id];
+        if (cached) return cached;
+        const props = {
             id,
             ref: registerRef(id),
             "data-domet": id
-        }), [
+        };
+        registerPropsCache.current[id] = props;
+        return props;
+    }, [
         registerRef
     ]);
-    const navProps = useCallback((id)=>({
-            onClick: ()=>scrollToSection(id),
+    const link = useCallback((id, options)=>({
+            onClick: ()=>scrollTo(id, options),
             "aria-current": activeId === id ? "page" : undefined,
             "data-active": activeId === id
         }), [
         activeId,
-        scrollToSection
-    ]);
-    useEffect(()=>{
-        var _stableSectionIds_;
-        const idsSet = new Set(stableSectionIds);
-        for (const id of Object.keys(refs.current)){
-            if (!idsSet.has(id)) {
-                delete refs.current[id];
-            }
-        }
-        for (const id of Object.keys(refCallbacks.current)){
-            if (!idsSet.has(id)) {
-                delete refCallbacks.current[id];
-            }
-        }
-        const currentActive = activeIdRef.current;
-        const nextActive = currentActive && idsSet.has(currentActive) ? currentActive : (_stableSectionIds_ = stableSectionIds[0]) != null ? _stableSectionIds_ : null;
-        if (nextActive !== currentActive) {
-            activeIdRef.current = nextActive;
-        }
-        setActiveId((prev)=>prev !== nextActive ? nextActive : prev);
-    }, [
-        stableSectionIds
-    ]);
-    const getSectionBounds = useCallback(()=>{
-        const container = containerElement;
-        const scrollTop = container ? container.scrollTop : window.scrollY;
-        const containerTop = container ? container.getBoundingClientRect().top : 0;
-        return stableSectionIds.map((id)=>{
-            const el = refs.current[id];
-            if (!el) return null;
-            const rect = el.getBoundingClientRect();
-            const relativeTop = container ? rect.top - containerTop + scrollTop : rect.top + window.scrollY;
-            return {
-                id,
-                top: relativeTop,
-                bottom: relativeTop + rect.height,
-                height: rect.height
-            };
-        }).filter((bounds)=>bounds !== null);
-    }, [
-        stableSectionIds,
-        containerElement
+        scrollTo
     ]);
     const calculateActiveSection = useCallback(()=>{
-        if (isProgrammaticScrolling.current) return;
         const container = containerElement;
         const currentActiveId = activeIdRef.current;
         const now = Date.now();
         const scrollY = container ? container.scrollTop : window.scrollY;
         const viewportHeight = container ? container.clientHeight : window.innerHeight;
         const scrollHeight = container ? container.scrollHeight : document.documentElement.scrollHeight;
-        const maxScroll = Math.max(0, scrollHeight - viewportHeight);
-        const scrollProgress = maxScroll > 0 ? scrollY / maxScroll : 0;
+        const maxScroll = Math.max(1, scrollHeight - viewportHeight);
+        const scrollProgress = Math.min(1, Math.max(0, scrollY / maxScroll));
         const scrollDirection = scrollY === lastScrollY.current ? null : scrollY > lastScrollY.current ? "down" : "up";
         const deltaTime = now - lastScrollTime.current;
         const deltaY = scrollY - lastScrollY.current;
         const velocity = deltaTime > 0 ? Math.abs(deltaY) / deltaTime : 0;
         lastScrollY.current = scrollY;
         lastScrollTime.current = now;
-        const sectionBounds = getSectionBounds();
+        const currentSections = getCurrentSections();
+        const sectionBounds = getSectionBounds(currentSections, container);
         if (sectionBounds.length === 0) return;
-        const baseOffset = getEffectiveOffset();
-        const effectiveOffset = Math.max(baseOffset, viewportHeight * offsetRatio);
-        const triggerLine = scrollY + effectiveOffset;
-        const viewportTop = scrollY;
-        const viewportBottom = scrollY + viewportHeight;
-        const scores = sectionBounds.map((section)=>{
-            var _sectionIndexMap_get;
-            const visibleTop = Math.max(section.top, viewportTop);
-            const visibleBottom = Math.min(section.bottom, viewportBottom);
-            const visibleHeight = Math.max(0, visibleBottom - visibleTop);
-            const visibilityRatio = section.height > 0 ? visibleHeight / section.height : 0;
-            const visibleInViewportRatio = viewportHeight > 0 ? visibleHeight / viewportHeight : 0;
-            const isInViewport = section.bottom > viewportTop && section.top < viewportBottom;
-            const sectionProgress = (()=>{
-                if (section.height === 0) return 0;
-                const entryPoint = viewportBottom;
-                const totalTravel = viewportHeight + section.height;
-                const traveled = entryPoint - section.top;
-                return Math.max(0, Math.min(1, traveled / totalTravel));
-            })();
-            let score = 0;
-            if (visibilityRatio >= visibilityThreshold) {
-                score += 1000 + visibilityRatio * 500;
-            } else if (isInViewport) {
-                score += visibleInViewportRatio * 800;
-            }
-            const sectionIndex = (_sectionIndexMap_get = sectionIndexMap.get(section.id)) != null ? _sectionIndexMap_get : 0;
-            if (scrollDirection && isInViewport && section.top <= triggerLine && section.bottom > triggerLine) {
-                score += 200;
-            }
-            score -= sectionIndex * 0.1;
-            return {
-                id: section.id,
-                score,
-                visibilityRatio,
-                isInViewport,
-                bounds: section,
-                progress: sectionProgress
-            };
-        });
-        const hasScroll = maxScroll > 10;
-        const isAtBottom = hasScroll && scrollY + viewportHeight >= scrollHeight - 5;
-        const isAtTop = hasScroll && scrollY <= 5;
-        let newActiveId = null;
-        if (isAtBottom && stableSectionIds.length > 0) {
-            newActiveId = stableSectionIds[stableSectionIds.length - 1];
-        } else if (isAtTop && stableSectionIds.length > 0) {
-            newActiveId = stableSectionIds[0];
-        } else {
-            const visibleScores = scores.filter((s)=>s.isInViewport);
-            const candidates = visibleScores.length > 0 ? visibleScores : scores;
-            candidates.sort((a, b)=>b.score - a.score);
-            if (candidates.length > 0) {
-                const bestCandidate = candidates[0];
-                const currentScore = scores.find((s)=>s.id === currentActiveId);
-                const shouldSwitch = !currentScore || !currentScore.isInViewport || bestCandidate.score > currentScore.score + hysteresisMargin || bestCandidate.id === currentActiveId;
-                newActiveId = shouldSwitch ? bestCandidate.id : currentActiveId;
-            }
-        }
-        if (newActiveId !== currentActiveId) {
+        const effectiveOffset = resolveOffset(trackingOffset, viewportHeight, DEFAULT_OFFSET);
+        const scores = calculateSectionScores(sectionBounds, currentSections, {
+            scrollY,
+            viewportHeight,
+            scrollHeight,
+            effectiveOffset,
+            visibilityThreshold: threshold});
+        const isProgrammatic = isProgrammaticScrolling.current;
+        const newActiveId = isProgrammatic ? currentActiveId : determineActiveSection(scores, sectionIds, currentActiveId, hysteresis, scrollY, viewportHeight, scrollHeight);
+        if (!isProgrammatic && newActiveId !== currentActiveId) {
             activeIdRef.current = newActiveId;
             setActiveId(newActiveId);
-            callbackRefs.current.onActiveChange == null ? void 0 : callbackRefs.current.onActiveChange.call(callbackRefs.current, newActiveId, currentActiveId);
+            callbackRefs.current.onActive?.(newActiveId, currentActiveId);
         }
-        const currentInViewport = new Set(scores.filter((s)=>s.isInViewport).map((s)=>s.id));
-        const prevInViewport = prevSectionsInViewport.current;
-        for (const id of currentInViewport){
-            if (!prevInViewport.has(id)) {
-                callbackRefs.current.onSectionEnter == null ? void 0 : callbackRefs.current.onSectionEnter.call(callbackRefs.current, id);
+        if (!isProgrammatic) {
+            const currentInViewport = new Set(scores.filter((s)=>s.inView).map((s)=>s.id));
+            const prevInViewport = prevSectionsInViewport.current;
+            for (const id of currentInViewport){
+                if (!prevInViewport.has(id)) {
+                    callbackRefs.current.onEnter?.(id);
+                }
             }
-        }
-        for (const id of prevInViewport){
-            if (!currentInViewport.has(id)) {
-                callbackRefs.current.onSectionLeave == null ? void 0 : callbackRefs.current.onSectionLeave.call(callbackRefs.current, id);
+            for (const id of prevInViewport){
+                if (!currentInViewport.has(id)) {
+                    callbackRefs.current.onLeave?.(id);
+                }
             }
+            prevSectionsInViewport.current = currentInViewport;
         }
-        prevSectionsInViewport.current = currentInViewport;
+        const triggerLine = Math.round(effectiveOffset + scrollProgress * (viewportHeight - effectiveOffset));
         const newScrollState = {
-            y: scrollY,
+            y: Math.round(scrollY),
             progress: Math.max(0, Math.min(1, scrollProgress)),
             direction: scrollDirection,
-            velocity,
-            isScrolling: isScrollingRef.current,
-            maxScroll,
-            viewportHeight,
-            offset: effectiveOffset
+            velocity: Math.round(velocity),
+            scrolling: isScrollingRef.current,
+            maxScroll: Math.round(maxScroll),
+            viewportHeight: Math.round(viewportHeight),
+            trackingOffset: Math.round(effectiveOffset),
+            triggerLine
         };
         const newSections = {};
         for (const s of scores){
             newSections[s.id] = {
                 bounds: {
-                    top: s.bounds.top,
-                    bottom: s.bounds.bottom,
-                    height: s.bounds.height
+                    top: Math.round(s.bounds.top),
+                    bottom: Math.round(s.bounds.bottom),
+                    height: Math.round(s.bounds.height)
                 },
                 visibility: Math.round(s.visibilityRatio * 100) / 100,
                 progress: Math.round(s.progress * 100) / 100,
-                isInViewport: s.isInViewport,
-                isActive: s.id === newActiveId
+                inView: s.inView,
+                active: s.id === (isProgrammatic ? currentActiveId : newActiveId),
+                rect: s.rect
             };
         }
         setScroll(newScrollState);
         setSections(newSections);
     }, [
-        stableSectionIds,
+        sectionIds,
         sectionIndexMap,
-        getEffectiveOffset,
-        offsetRatio,
-        visibilityThreshold,
-        hysteresisMargin,
-        getSectionBounds,
-        containerElement
+        trackingOffset,
+        threshold,
+        hysteresis,
+        containerElement,
+        getCurrentSections
     ]);
     recalculateRef.current = calculateActiveSection;
     useEffect(()=>{
         const container = containerElement;
         const scrollTarget = container || window;
-        const scheduleCalculate = ()=>{
-            if (rafId.current) {
-                cancelAnimationFrame(rafId.current);
-            }
-            rafId.current = requestAnimationFrame(()=>{
-                rafId.current = null;
-                calculateActiveSection();
-            });
-        };
         const handleScrollEnd = ()=>{
             isScrollingRef.current = false;
             setScroll((prev)=>({
                     ...prev,
-                    isScrolling: false
+                    scrolling: false
                 }));
-            callbackRefs.current.onScrollEnd == null ? void 0 : callbackRefs.current.onScrollEnd.call(callbackRefs.current);
+            callbackRefs.current.onScrollEnd?.();
         };
         const handleScroll = ()=>{
             if (!isScrollingRef.current) {
                 isScrollingRef.current = true;
                 setScroll((prev)=>({
                         ...prev,
-                        isScrolling: true
+                        scrolling: true
                     }));
-                callbackRefs.current.onScrollStart == null ? void 0 : callbackRefs.current.onScrollStart.call(callbackRefs.current);
+                callbackRefs.current.onScrollStart?.();
             }
             if (scrollIdleTimeoutRef.current) {
                 clearTimeout(scrollIdleTimeoutRef.current);
@@ -427,7 +939,7 @@ function useDomet(sectionIds, containerRef = null, options = {}) {
             if (throttleTimeoutId.current) {
                 clearTimeout(throttleTimeoutId.current);
             }
-            scheduleCalculate();
+            scheduleRecalculate();
             throttleTimeoutId.current = setTimeout(()=>{
                 isThrottled.current = false;
                 throttleTimeoutId.current = null;
@@ -435,14 +947,16 @@ function useDomet(sectionIds, containerRef = null, options = {}) {
                     hasPendingScroll.current = false;
                     handleScroll();
                 }
-            }, debounceMs);
+            }, throttle);
         };
         const handleResize = ()=>{
-            scheduleCalculate();
+            if (useSelector && selectorString) {
+                updateSectionsFromSelector(selectorString);
+            }
+            scheduleRecalculate();
         };
-        calculateActiveSection();
         const deferredRecalcId = setTimeout(()=>{
-            calculateActiveSection();
+            scheduleRecalculate();
         }, 0);
         scrollTarget.addEventListener("scroll", handleScroll, {
             passive: true
@@ -462,43 +976,43 @@ function useDomet(sectionIds, containerRef = null, options = {}) {
                 clearTimeout(throttleTimeoutId.current);
                 throttleTimeoutId.current = null;
             }
-            if (programmaticScrollTimeoutId.current) {
-                clearTimeout(programmaticScrollTimeoutId.current);
-                programmaticScrollTimeoutId.current = null;
-            }
             if (scrollIdleTimeoutRef.current) {
                 clearTimeout(scrollIdleTimeoutRef.current);
                 scrollIdleTimeoutRef.current = null;
             }
-            scrollCleanupRef.current == null ? void 0 : scrollCleanupRef.current.call(scrollCleanupRef);
+            scrollCleanupRef.current?.();
             isThrottled.current = false;
             hasPendingScroll.current = false;
             isProgrammaticScrolling.current = false;
             isScrollingRef.current = false;
         };
     }, [
-        calculateActiveSection,
-        debounceMs,
-        containerElement
+        throttle,
+        containerElement,
+        useSelector,
+        selectorString,
+        updateSectionsFromSelector,
+        scheduleRecalculate
     ]);
-    const activeIndex = useMemo(()=>{
-        var _sectionIndexMap_get;
+    const index = useMemo(()=>{
         if (!activeId) return -1;
-        return (_sectionIndexMap_get = sectionIndexMap.get(activeId)) != null ? _sectionIndexMap_get : -1;
+        return sectionIndexMap.get(activeId) ?? -1;
     }, [
         activeId,
         sectionIndexMap
     ]);
     return {
-        activeId,
-        activeIndex,
+        active: activeId,
+        index,
+        progress: scroll.progress,
+        direction: scroll.direction,
         scroll,
         sections,
-        registerRef,
-        scrollToSection,
-        sectionProps,
-        navProps
+        ids: sectionIds,
+        scrollTo,
+        register,
+        link
     };
 }
 
-export { useDomet as default, useDomet };
+export { VALIDATION_LIMITS, useDomet as default, useDomet };