@humanspeak/svelte-virtual-list 0.3.1-beta.1 → 0.3.1

package/dist/SvelteVirtualList.svelte

@@ -61,7 +61,7 @@
     MIT License © Humanspeak, Inc.
 -->
 
-<script lang="ts" generics="TItem = any">
+<script lang="ts" generics="TItem = unknown">
     /**
      * SvelteVirtualList Implementation Journey
      *
@@ -171,7 +171,7 @@
     import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
     import { calculateScrollTarget } from './utils/scrollCalculation.js'
     import { createAdvancedThrottledCallback } from './utils/throttle.js'
-    import { ReactiveHeightManager } from './reactive-height-manager/index.js'
+    import { ReactiveListManager } from './index.js'
     import { BROWSER } from 'esm-env'
     import { onMount, tick, untrack } from 'svelte'
 
@@ -202,22 +202,18 @@
     /**
      * DOM References and Core State
      */
-    let containerElement: HTMLElement // Reference to the main container element
-    let viewportElement: HTMLElement // Reference to the scrollable viewport element
     const itemElements = $state<HTMLElement[]>([]) // Array of rendered item element references
 
     /**
      * Scroll and Height Management
      */
-    let scrollTop = $state(0) // Current scroll position
     let height = $state(0) // Container height
-    let calculatedItemHeight = $state(defaultEstimatedItemHeight) // Current average item height
 
     /**
      * State Flags and Control
      */
-    let initialized = $state(false) // Tracks if initial setup is complete
-    let isCalculatingHeight = $state(false) // Prevents concurrent height calculations
+
+    const isCalculatingHeight = $state(false) // Prevents concurrent height calculations
     let isScrolling = $state(false) // Tracks active scrolling state
     let lastMeasuredIndex = $state(-1) // Index of last measured item
     let lastScrollTopSnapshot = $state(0) // Previous scroll position snapshot
@@ -232,37 +228,45 @@
     /**
      * Performance Optimization State
      */
-    let heightCache = $state<Record<number, number>>({}) // Cache of measured item heights
-    let dirtyItems = $state(new Set<number>()) // Set of item indices that need height recalculation
+    const dirtyItems = $state(new Set<number>()) // Set of item indices that need height recalculation
     let dirtyItemsCount = $state(0) // Reactive count of dirty items
+    // Fallback measurement used only when height has not been established yet
+    let measuredFallbackHeight = $state(0)
 
     let prevVisibleRange = $state<SvelteVirtualListPreviousVisibleRange | null>(null)
     let prevHeight = $state<number>(0)
+    let prevTotalHeightForScrollCorrection = $state<number>(0)
+    let lastBottomDistance = $state<number | null>(null)
 
     /**
      * Reactive Height Manager - O(1) height calculation system
      * Replaces O(n) totalHeight loop with incremental updates
      */
-    let heightManager = new ReactiveHeightManager({
+    const heightManager = new ReactiveListManager({
         itemLength: items.length,
-        itemHeight: defaultEstimatedItemHeight
+        itemHeight: defaultEstimatedItemHeight,
+        internalDebug: INTERNAL_DEBUG
     })
 
     // Dynamic update coordination to avoid UA scroll anchoring interference
-    let dynamicUpdateInProgress = $state(false)
     let suppressBottomAnchoringUntilMs = $state(0)
-    function beginDynamicUpdate(): void {
-        dynamicUpdateInProgress = true
-        if (viewportElement) {
-            viewportElement.style.setProperty('overflow-anchor', 'none')
-        }
-    }
-    function endDynamicUpdate(): void {
-        dynamicUpdateInProgress = false
-        if (viewportElement) {
-            viewportElement.style.setProperty('overflow-anchor', 'auto')
-        }
-    }
+
+    const displayItems = $derived(() => {
+        const visibleRange = visibleItems()
+        const slice =
+            mode === 'bottomToTop'
+                ? items.slice(visibleRange.start, visibleRange.end).reverse()
+                : items.slice(visibleRange.start, visibleRange.end)
+
+        return slice.map((item, sliceIndex) => ({
+            item,
+            originalIndex:
+                mode === 'bottomToTop'
+                    ? visibleRange.end - 1 - sliceIndex
+                    : visibleRange.start + sliceIndex,
+            sliceIndex
+        }))
+    })
 
     /**
      * Handles scroll position corrections when item heights change, ensuring proper positioning
@@ -280,7 +284,7 @@
     const handleHeightChangesScrollCorrection = (
         heightChanges: Array<{ index: number; oldHeight: number; newHeight: number; delta: number }>
     ) => {
-        if (!viewportElement || !initialized || userHasScrolledAway) {
+        if (!heightManager.viewportElement || !heightManager.initialized || userHasScrolledAway) {
             return
         }
 
@@ -332,16 +336,18 @@
             wasAtBottomBeforeHeightChange &&
             !programmaticScrollInProgress &&
             performance.now() >= suppressBottomAnchoringUntilMs &&
-            !dynamicUpdateInProgress
+            !heightManager.isDynamicUpdateInProgress
         ) {
             // Step 1: Scroll to approximate position to ensure Item 0 gets rendered in virtual viewport
             const approximateScrollTop = Math.max(0, totalHeight() - height)
-            viewportElement.scrollTop = approximateScrollTop
-            scrollTop = approximateScrollTop
+            heightManager.viewport.scrollTop = approximateScrollTop
+            heightManager.scrollTop = approximateScrollTop
 
             // Step 2: Use native scrollIntoView for precise bottom-edge positioning after DOM updates
             tick().then(() => {
-                const item0Element = viewportElement.querySelector('[data-original-index="0"]')
+                const item0Element = heightManager.viewport.querySelector(
+                    '[data-original-index="0"]'
+                )
                 if (item0Element) {
                     // Native browser API handles all positioning edge cases perfectly
                     item0Element.scrollIntoView({
@@ -351,14 +357,14 @@
                     })
 
                     // Sync our internal scroll state with actual DOM position
-                    scrollTop = viewportElement.scrollTop
+                    heightManager.scrollTop = heightManager.viewport.scrollTop
                 }
             })
 
             return // Skip remaining scroll correction logic - we've handled bottomToTop case
         }
 
-        const currentScrollTop = viewportElement.scrollTop
+        const currentScrollTop = heightManager.viewport.scrollTop
         const maxScrollTop = Math.max(0, totalHeight() - height)
 
         // Calculate total height change impact above current visible area
@@ -379,8 +385,8 @@
                 Math.max(0, currentScrollTop + heightChangeAboveViewport)
             )
 
-            viewportElement.scrollTop = newScrollTop
-            scrollTop = newScrollTop
+            heightManager.viewport.scrollTop = newScrollTop
+            heightManager.scrollTop = newScrollTop
         }
     }
 
@@ -391,7 +397,7 @@
             if (BROWSER && dirtyItemsCount > 0) {
                 // Capture bottom state before any height processing to prevent cascading corrections
                 wasAtBottomBeforeHeightChange = atBottom
-                beginDynamicUpdate()
+                heightManager.startDynamicUpdate()
                 updateHeight()
             }
         },
@@ -413,32 +419,56 @@
     })
 
     const updateHeight = () => {
+        // Capture previous total height for scroll correction (topToBottom anchoring)
+        prevTotalHeightForScrollCorrection = heightManager.totalHeight
         heightUpdateTimeout = calculateAverageHeightDebounced(
             isCalculatingHeight,
             heightUpdateTimeout,
             visibleItems,
             itemElements,
-            heightCache,
+            heightManager.getHeightCache(),
             lastMeasuredIndex,
             heightManager.averageHeight,
             (result) => {
                 // Critical updates that must trigger reactive effects immediately
                 heightManager.itemHeight = result.newHeight
                 lastMeasuredIndex = result.newLastMeasuredIndex
-                heightCache = result.updatedHeightCache
 
-                // Handle height changes for scroll correction (needs updated heightCache)
+                // Update manager totals/cache before any scroll correction logic relies on them
+                if (result.heightChanges.length > 0) {
+                    heightManager.processDirtyHeights(result.heightChanges)
+                }
+
+                // Handle height changes for scroll correction (manager totals already updated)
                 if (result.heightChanges.length > 0 && mode === 'bottomToTop') {
                     handleHeightChangesScrollCorrection(result.heightChanges)
                 }
 
-                // Non-critical updates wrapped in untrack to prevent reactive cascades
-                untrack(() => {
-                    // Process height changes with ReactiveHeightManager (O(dirty) instead of O(n)!)
-                    if (result.heightChanges.length > 0) {
-                        heightManager.processDirtyHeights(result.heightChanges)
+                // TopToBottom: maintain bottom anchoring when total height changes
+                if (mode === 'topToBottom' && heightManager.isReady && heightManager.initialized) {
+                    const oldTotal = prevTotalHeightForScrollCorrection
+                    const newTotal = heightManager.totalHeight
+                    const deltaTotal = newTotal - oldTotal
+                    // Ignore micro deltas to prevent oscillation
+                    if (Math.abs(deltaTotal) > 1) {
+                        const maxScrollTop = Math.max(0, newTotal - (height || 0))
+                        const tolerance = Math.max(heightManager.averageHeight, 10)
+                        const currentScrollTop = heightManager.viewport.scrollTop
+                        const isAtBottom = Math.abs(currentScrollTop - maxScrollTop) <= tolerance
+                        if (isAtBottom) {
+                            // Adjust scrollTop by total height delta to hold bottom anchor
+                            const adjusted = Math.min(
+                                maxScrollTop,
+                                Math.max(0, currentScrollTop + deltaTotal)
+                            )
+                            heightManager.viewport.scrollTop = adjusted
+                            heightManager.scrollTop = adjusted
+                        }
                     }
+                }
 
+                // Non-critical updates wrapped in untrack to prevent reactive cascades
+                untrack(() => {
                     // Clear processed dirty items (all dirty items were processed)
                     dirtyItems.clear()
                     dirtyItemsCount = 0
@@ -446,12 +476,12 @@
                     // Reset bottom state flag
                     wasAtBottomBeforeHeightChange = false
                 })
-                endDynamicUpdate()
+                heightManager.endDynamicUpdate()
             },
-            100, // debounceTime
+            lastMeasuredIndex < 0 ? 0 : 100, // debounceTime (no debounce on first pass)
             dirtyItems, // Pass dirty items for processing
-            0, // Don't pass ReactiveHeightManager state - let each system manage its own totals
-            0, // Don't pass ReactiveHeightManager state - let each system manage its own totals
+            0, // Don't pass ReactiveListManager state - let each system manage its own totals
+            0, // Don't pass ReactiveListManager state - let each system manage its own totals
             mode // Pass mode for correct element indexing
         )
     }
@@ -467,7 +497,7 @@
      * CRITICAL: O(1) Reactive Total Height Calculation
      * ===============================================
      *
-     * Uses ReactiveHeightManager for O(1) height calculations instead of O(n) loops.
+     * Uses ReactiveListManager for O(1) height calculations instead of O(n) loops.
      * This fixes the root cause of massive scroll jumps in bottomToTop mode.
      *
      * Problem with Previous O(n) Approach:
@@ -478,7 +508,7 @@
      *   - Total height jumps from 200,000px to 223,500px (+23,500px!)
      *   - This 23,500px error caused massive scroll position overshoots
      *
-     * Solution with ReactiveHeightManager:
+     * Solution with ReactiveListManager:
      * - O(1) reactive calculations using incremental updates
      * - Uses actual measured heights from heightCache where available
      * - Only estimates heights for items that haven't been measured yet
@@ -494,20 +524,40 @@
      * This getter is reactive and updates whenever heightManager's internal state changes.
      * Used by: atBottom calculation, scroll corrections, maxScrollTop calculations
      */
-    let totalHeight = $derived(() => heightManager.totalHeight)
+    const totalHeight = $derived(() => heightManager.totalHeight)
 
-    let atTop = $derived(scrollTop <= 1)
-    let atBottom = $derived(scrollTop >= totalHeight() - height - 1)
+    const atBottom = $derived(heightManager.scrollTop >= totalHeight() - height - 1)
     let wasAtBottomBeforeHeightChange = false
     let lastVisibleRange: SvelteVirtualListPreviousVisibleRange | null = null
 
-    $inspect('scrollState: atTop', atTop)
-    $inspect('scrollState: atBottom', atBottom)
+    function updateDebugTailDistance() {
+        if (!heightManager.viewportElement) return
+        const last = heightManager.viewport.querySelector(
+            '[data-original-index="999"]'
+        ) as HTMLElement | null
+        if (!last) return
+        const v = heightManager.viewport.getBoundingClientRect()
+        const r = last.getBoundingClientRect()
+        lastBottomDistance = Math.round(Math.abs(r.bottom - v.bottom))
+        if (INTERNAL_DEBUG) {
+            console.info('[SVL] bottomDistance(px):', lastBottomDistance)
+        }
+    }
+
+    // no UI export; rely on console logs when debug=true
+
+    // $inspect('scrollState: atTop', atTop)
+    // $inspect('scrollState: atBottom', atBottom)
 
     $effect(() => {
-        if (BROWSER && initialized && mode === 'bottomToTop' && viewportElement) {
+        if (
+            BROWSER &&
+            heightManager.initialized &&
+            mode === 'bottomToTop' &&
+            heightManager.viewportElement
+        ) {
             const targetScrollTop = Math.max(0, totalHeight() - height)
-            const currentScrollTop = viewportElement.scrollTop
+            const currentScrollTop = heightManager.viewport.scrollTop
             const scrollDifference = Math.abs(currentScrollTop - targetScrollTop)
 
             // Only correct scroll if:
@@ -515,33 +565,34 @@
             // 2. User hasn't intentionally scrolled away from bottom
             // 3. We're significantly off target
             // 4. We're not at the bottom (where height changes should be handled more carefully)
-            const heightChanged = Math.abs(calculatedItemHeight - lastCalculatedHeight) > 1
+            const heightChanged = Math.abs(heightManager.averageHeight - lastCalculatedHeight) > 1
             const maxScrollTop = Math.max(0, totalHeight() - height)
 
             // In bottomToTop mode, we're "at bottom" when scroll is at max position
-            const isAtBottom = Math.abs(currentScrollTop - maxScrollTop) < calculatedItemHeight
+            const isAtBottom =
+                Math.abs(currentScrollTop - maxScrollTop) < heightManager.averageHeight
             const shouldCorrect =
                 heightChanged &&
                 !userHasScrolledAway &&
                 !isAtBottom && // Don't apply aggressive correction when at bottom
                 !programmaticScrollInProgress && // Don't interfere with programmatic scrolls
                 performance.now() >= suppressBottomAnchoringUntilMs &&
-                !dynamicUpdateInProgress &&
-                scrollDifference > calculatedItemHeight * 3
+                !heightManager.isDynamicUpdateInProgress &&
+                scrollDifference > heightManager.averageHeight * 3
 
             if (shouldCorrect) {
                 // Round to avoid subpixel positioning issues in bottomToTop mode
                 const roundedTargetScrollTop = Math.round(targetScrollTop)
-                viewportElement.scrollTop = roundedTargetScrollTop
-                scrollTop = roundedTargetScrollTop
+                heightManager.viewport.scrollTop = roundedTargetScrollTop
+                heightManager.scrollTop = roundedTargetScrollTop
             }
 
             // Track if user has scrolled significantly away from bottom
-            if (scrollDifference > calculatedItemHeight * 5) {
+            if (scrollDifference > heightManager.averageHeight * 5) {
                 userHasScrolledAway = true
             }
 
-            lastCalculatedHeight = calculatedItemHeight
+            lastCalculatedHeight = heightManager.averageHeight
         }
     })
 
@@ -552,17 +603,17 @@
 
         if (
             BROWSER &&
-            initialized &&
+            heightManager.initialized &&
             mode === 'bottomToTop' &&
-            viewportElement &&
+            heightManager.isReady &&
             lastItemsLength > 0
         ) {
             const itemsAdded = currentItemsLength - lastItemsLength
 
             if (itemsAdded !== 0) {
                 // Capture all reactive values immediately to prevent re-triggering
-                const currentScrollTop = viewportElement.scrollTop
-                const currentCalculatedItemHeight = calculatedItemHeight
+                const currentScrollTop = heightManager.viewport.scrollTop
+                const currentCalculatedItemHeight = heightManager.averageHeight
                 const currentHeight = height
                 const currentTotalHeight = totalHeight()
                 const maxScrollTop = Math.max(0, currentTotalHeight - currentHeight)
@@ -580,14 +631,14 @@
 
                 if (wasNearBottom || currentScrollTop === 0) {
                     // User was at bottom, keep them at bottom after new items are added
-                    beginDynamicUpdate()
-                    const newScrollTop = maxScrollTop
-                    viewportElement.scrollTop = newScrollTop
-                    scrollTop = newScrollTop
-
-                    // Reset the "scrolled away" flag since we're actively managing position
-                    userHasScrolledAway = false
-                    endDynamicUpdate()
+                    void heightManager.runDynamicUpdate(() => {
+                        const newScrollTop = maxScrollTop
+                        heightManager.viewport.scrollTop = newScrollTop
+                        heightManager.scrollTop = newScrollTop
+
+                        // Reset the "scrolled away" flag since we're actively managing position
+                        userHasScrolledAway = false
+                    })
                 }
             }
         }
@@ -595,42 +646,23 @@
         lastItemsLength = currentItemsLength
     })
 
-    // Update container height when element is mounted
+    // Update container height continuously to reflect layout changes that
+    // may occur outside ResizeObserver timing (keeps buffers correct across engines)
     $effect(() => {
-        if (BROWSER && containerElement) {
-            height = containerElement.getBoundingClientRect().height
+        if (BROWSER && heightManager.isReady) {
+            const h = heightManager.container.getBoundingClientRect().height
+            if (Number.isFinite(h) && h > 0) height = h
         }
     })
 
-    // Special handling for bottom-to-top mode initialization
-    $effect(() => {
-        if (
-            BROWSER &&
-            mode === 'bottomToTop' &&
-            viewportElement &&
-            height > 0 &&
-            items.length &&
-            !initialized
-        ) {
-            const targetScrollTop = Math.max(0, totalHeight() - height)
+    // One-time fallback measurement when height hasn't been established yet
 
-            // Add delay to ensure layout is complete
-            tick().then(() => {
-                if (viewportElement) {
-                    // Start at the bottom for bottom-to-top mode
-                    viewportElement.scrollTop = targetScrollTop
-                    scrollTop = targetScrollTop
-
-                    // Double-check the scroll position after a frame
-                    requestAnimationFrame(() => {
-                        if (viewportElement && viewportElement.scrollTop !== targetScrollTop) {
-                            viewportElement.scrollTop = targetScrollTop
-                            scrollTop = targetScrollTop
-                        }
-                        initialized = true
-                    })
-                }
-            })
+    // Provide a one-time synchronous measurement only when height is still 0,
+    // to avoid DOM reads inside render-time expressions.
+    $effect(() => {
+        if (BROWSER && height === 0 && heightManager.isReady) {
+            const h = heightManager.container.getBoundingClientRect().height
+            if (Number.isFinite(h) && h > 0) measuredFallbackHeight = h
         }
     })
 
@@ -648,7 +680,7 @@
      * @example
      * ```typescript
      * const range = visibleItems()
-     * console.log(`Rendering items from ${range.start} to ${range.end}`)
+     * console.info(`Rendering items from ${range.start} to ${range.end}`)
      * ```
      *
      * @returns {SvelteVirtualListPreviousVisibleRange} Object containing start and end indices of visible items
@@ -659,7 +691,12 @@
 
         // For bottomToTop mode, don't calculate visible range until properly initialized
         // This prevents showing wrong items when scrollTop starts at 0
-        if (mode === 'bottomToTop' && !initialized && scrollTop === 0 && viewportHeight > 0) {
+        if (
+            mode === 'bottomToTop' &&
+            !heightManager.initialized &&
+            heightManager.scrollTop === 0 &&
+            viewportHeight > 0
+        ) {
             // Calculate what the correct scroll position should be
             const targetScrollTop = Math.max(0, totalHeight() - viewportHeight)
 
@@ -674,14 +711,15 @@
                 atBottom,
                 wasAtBottomBeforeHeightChange,
                 lastVisibleRange,
-                totalHeight()
+                totalHeight(),
+                heightManager.getHeightCache()
             )
 
             return lastVisibleRange
         }
 
         lastVisibleRange = calculateVisibleRange(
-            scrollTop,
+            heightManager.scrollTop,
             viewportHeight,
             heightManager.averageHeight,
             items.length,
@@ -690,7 +728,8 @@
             atBottom,
             wasAtBottomBeforeHeightChange,
             lastVisibleRange,
-            totalHeight()
+            totalHeight(),
+            heightManager.getHeightCache()
         )
 
         return lastVisibleRange
@@ -718,12 +757,12 @@
      * @returns {void}
      */
     const handleScroll = () => {
-        if (!BROWSER || !viewportElement) return
+        if (!BROWSER || !heightManager.viewportElement) return
 
         if (!isScrolling) {
             isScrolling = true
             rafSchedule(() => {
-                const current = viewportElement.scrollTop
+                const current = heightManager.viewport.scrollTop
                 if (mode === 'bottomToTop') {
                     const delta = lastScrollTopSnapshot - current
                     if (delta > 0.5) {
@@ -732,7 +771,19 @@
                     }
                 }
                 lastScrollTopSnapshot = current
-                scrollTop = current
+                heightManager.scrollTop = current
+                updateDebugTailDistance()
+                if (INTERNAL_DEBUG) {
+                    const vr = visibleItems()
+                    console.info('[SVL] onscroll', {
+                        mode,
+                        scrollTop: heightManager.scrollTop,
+                        height,
+                        totalHeight: totalHeight(),
+                        averageItemHeight: heightManager.averageHeight,
+                        visibleRange: vr
+                    })
+                }
                 isScrolling = false
             })
         }
@@ -753,37 +804,36 @@
      * @param immediate - Whether to skip the delay (used for resize events)
      */
     const updateHeightAndScroll = (immediate = false) => {
-        if (!initialized && mode === 'bottomToTop') {
+        if (!heightManager.initialized && mode === 'bottomToTop') {
             tick().then(() => {
-                if (containerElement) {
-                    const initialHeight = containerElement.getBoundingClientRect().height
+                if (heightManager.isReady) {
+                    const initialHeight = heightManager.container.getBoundingClientRect().height
                     height = initialHeight
 
                     tick().then(() => {
-                        if (containerElement && viewportElement) {
-                            const finalHeight = containerElement.getBoundingClientRect().height
+                        if (heightManager.isReady) {
+                            const finalHeight =
+                                heightManager.container.getBoundingClientRect().height
                             height = finalHeight
 
                             const targetScrollTop = calculateScrollPosition(
                                 items.length,
-                                calculatedItemHeight,
+                                heightManager.averageHeight,
                                 finalHeight
                             )
 
-                            void containerElement.offsetHeight
+                            void heightManager.container.offsetHeight
 
-                            viewportElement.scrollTop = targetScrollTop
-                            scrollTop = targetScrollTop
+                            heightManager.viewport.scrollTop = targetScrollTop
+                            heightManager.scrollTop = targetScrollTop
 
                             requestAnimationFrame(() => {
-                                if (viewportElement) {
-                                    const currentScroll = viewportElement.scrollTop
-                                    if (currentScroll !== scrollTop) {
-                                        viewportElement.scrollTop = targetScrollTop
-                                        scrollTop = targetScrollTop
-                                    }
-                                    initialized = true
+                                const currentScroll = heightManager.viewport.scrollTop
+                                if (currentScroll !== heightManager.scrollTop) {
+                                    heightManager.viewport.scrollTop = targetScrollTop
+                                    heightManager.scrollTop = targetScrollTop
                                 }
+                                heightManager.initialized = true
                             })
                         }
                     })
@@ -794,18 +844,18 @@
 
         utilsUpdateHeightAndScroll(
             {
-                initialized,
+                initialized: heightManager.initialized,
                 mode,
-                containerElement,
-                viewportElement,
-                calculatedItemHeight,
+                containerElement: heightManager.containerElement,
+                viewportElement: heightManager.viewportElement,
+                calculatedItemHeight: heightManager.averageHeight,
                 height,
-                scrollTop
+                scrollTop: heightManager.scrollTop
             },
             {
                 setHeight: (h) => (height = h),
-                setScrollTop: (st) => (scrollTop = st),
-                setInitialized: (i) => (initialized = i)
+                setScrollTop: (st) => (heightManager.scrollTop = st),
+                setInitialized: (i) => (heightManager.initialized = i)
             },
             immediate
         )
@@ -817,7 +867,7 @@
         itemResizeObserver = new ResizeObserver((entries) => {
             tick().then(() => {
                 let shouldRecalculate = false
-                const visibleRange = visibleItems() // Cache once to avoid reactive loops
+                void visibleItems() // Cache once to avoid reactive loops
 
                 for (const entry of entries) {
                     const element = entry.target as HTMLElement
@@ -830,7 +880,7 @@
                             const isSignificant = isSignificantHeightChange(
                                 actualIndex,
                                 currentHeight,
-                                heightCache
+                                heightManager.getHeightCache()
                             )
 
                             // Only mark as dirty if height change is significant
@@ -862,14 +912,18 @@
         if (BROWSER) {
             // Initial setup of heights and scroll position
             updateHeightAndScroll()
+            // Ensure one initial measurement pass even if no ResizeObserver fires
+            tick().then(() =>
+                requestAnimationFrame(() => requestAnimationFrame(() => updateHeight()))
+            )
 
             // Watch for container size changes
             resizeObserver = new ResizeObserver(() => {
                 updateHeightAndScroll(true)
             })
 
-            if (containerElement) {
-                resizeObserver.observe(containerElement)
+            if (heightManager.isReady) {
+                resizeObserver.observe(heightManager.container)
             }
 
             // Cleanup on component destruction
@@ -888,7 +942,7 @@
     $effect(() => {
         if (INTERNAL_DEBUG) {
             prevVisibleRange = visibleItems()
-            prevHeight = calculatedItemHeight
+            prevHeight = heightManager.averageHeight
         }
     })
 
@@ -970,9 +1024,9 @@
         }
 
         if (!items.length) return
-        if (!viewportElement) {
+        if (!heightManager.viewportElement) {
             tick().then(() => {
-                if (!viewportElement) return
+                if (!heightManager.viewportElement) return
                 scroll({ index, smoothScroll, shouldThrowOnBounds, align })
             })
             return
@@ -998,12 +1052,12 @@
             align: align || 'auto',
             targetIndex,
             itemsLength: items.length,
-            calculatedItemHeight: heightManager.averageHeight, // Use dynamic average from ReactiveHeightManager
+            calculatedItemHeight: heightManager.averageHeight, // Use dynamic average from ReactiveListManager
             height,
-            scrollTop,
+            scrollTop: heightManager.scrollTop,
             firstVisibleIndex,
             lastVisibleIndex,
-            heightCache
+            heightCache: heightManager.getHeightCache()
         })
 
         // Handle early return for 'nearest' alignment when item is already visible
@@ -1014,6 +1068,22 @@
         // Prevent bottom-anchoring logic from interfering with programmatic scroll
         programmaticScrollInProgress = true
 
+        if (INTERNAL_DEBUG && heightManager.viewportElement) {
+            const domMax = Math.max(
+                0,
+                heightManager.viewport.scrollHeight - heightManager.viewport.clientHeight
+            )
+            console.info('[SVL] scroll-intent', {
+                targetIndex,
+                align: align || 'auto',
+                firstVisibleIndex,
+                lastVisibleIndex,
+                currentScrollTop: heightManager.scrollTop,
+                scrollTarget,
+                domMaxScrollTop: domMax
+            })
+        }
+
         // CROSS-BROWSER COMPATIBILITY FIX:
         // All major browsers (Chrome, Firefox, Safari) have inconsistent behavior with scrollTo()
         // in bottomToTop mode when using smooth scrolling. Using scrollIntoView() on the highest
@@ -1021,7 +1091,7 @@
         // This approach works universally and maintains the user's expected smooth scroll experience.
         if (mode === 'bottomToTop' && smoothScroll) {
             // Find the element with the highest original-index in the current viewport
-            const visibleElements = viewportElement.querySelectorAll('[data-original-index]')
+            const visibleElements = heightManager.viewport.querySelectorAll('[data-original-index]')
             let maxIndex = -1
             let maxElement: HTMLElement | null = null
             for (const el of visibleElements) {
@@ -1040,16 +1110,28 @@
             await tick()
         }
 
-        viewportElement.scrollTo({
+        heightManager.viewport.scrollTo({
             top: scrollTarget,
             behavior: smoothScroll ? 'smooth' : 'auto'
         })
 
         // Update scrollTop state in next frame to avoid synchronous re-renders
         requestAnimationFrame(() => {
-            scrollTop = scrollTarget
+            heightManager.scrollTop = scrollTarget
+            if (INTERNAL_DEBUG && heightManager.viewportElement) {
+                const domMax = Math.max(
+                    0,
+                    heightManager.viewport.scrollHeight - heightManager.viewport.clientHeight
+                )
+                console.info('[SVL] scroll-after-call', {
+                    scrollTop: heightManager.scrollTop,
+                    domMaxScrollTop: domMax
+                })
+            }
         })
 
+        // No extra alignment step here; allow native smooth scroll to reach DOM max scrollTop
+
         // Clear the flag after scroll completes
         setTimeout(
             () => {
@@ -1092,14 +1174,14 @@
     id="virtual-list-container"
     {...testId ? { 'data-testid': `${testId}-container` } : {}}
     class={containerClass ?? 'virtual-list-container'}
-    bind:this={containerElement}
+    bind:this={heightManager.containerElement}
 >
     <!-- Viewport handles scrolling -->
     <div
         id="virtual-list-viewport"
         {...testId ? { 'data-testid': `${testId}-viewport` } : {}}
         class={viewportClass ?? 'virtual-list-viewport'}
-        bind:this={viewportElement}
+        bind:this={heightManager.viewportElement}
         onscroll={handleScroll}
     >
         <!-- Content provides full scrollable height -->
@@ -1107,10 +1189,7 @@
             id="virtual-list-content"
             {...testId ? { 'data-testid': `${testId}-content` } : {}}
             class={contentClass ?? 'virtual-list-content'}
-            style:height="{(() => {
-                // Use ReactiveHeightManager's accurate total height for better cross-browser compatibility
-                return Math.max(height, totalHeight())
-            })()}px"
+            style:height="{(() => Math.max(height, totalHeight()))()}px"
         >
             <!-- Items container is translated to show correct items -->
             <div
@@ -1119,52 +1198,39 @@
                 class={itemsClass ?? 'virtual-list-items'}
                 style:visibility={height === 0 && mode === 'bottomToTop' ? 'hidden' : 'visible'}
                 style:transform="translateY({(() => {
-                    const viewportHeight = height || 0
+                    const viewportHeight = height || measuredFallbackHeight || 0
                     const visibleRange = visibleItems()
 
-                    // For bottomToTop mode with few items, provide reasonable initial positioning
-                    // even when height is not yet measured to prevent flash
-                    let effectiveHeight = viewportHeight
-                    if (mode === 'bottomToTop' && viewportHeight === 0 && containerElement) {
-                        // Measure height synchronously if available
-                        effectiveHeight = containerElement.getBoundingClientRect().height || 400
-                    } else if (mode === 'bottomToTop' && viewportHeight === 0) {
-                        // Fallback to reasonable default height estimate for initial positioning
-                        effectiveHeight = 400
-                    }
+                    // Avoid synchronous DOM reads here; fall back once if height is 0
+                    const effectiveHeight = viewportHeight === 0 ? 400 : viewportHeight
 
-                    const transform = calculateTransformY(
-                        mode,
-                        items.length,
-                        visibleRange.end,
-                        visibleRange.start,
-                        heightManager.averageHeight,
-                        effectiveHeight,
-                        totalHeight() // Pass ReactiveHeightManager's accurate total height
+                    // Use precise offset for topToBottom using measured heights when available
+                    const transform = Math.round(
+                        calculateTransformY(
+                            mode,
+                            items.length,
+                            visibleRange.end,
+                            visibleRange.start,
+                            heightManager.averageHeight,
+                            effectiveHeight,
+                            totalHeight(),
+                            heightManager.getHeightCache(),
+                            measuredFallbackHeight
+                        )
                     )
 
                     return transform
                 })()}px)"
             >
-                {#each (() => {
-                    const visibleRange = visibleItems()
-                    const slice = mode === 'bottomToTop' ? items
-                                  .slice(visibleRange.start, visibleRange.end)
-                                  .reverse() : items.slice(visibleRange.start, visibleRange.end)
-
-                    // Map each item with its original index for proper DOM element tracking
-                    const itemsWithOriginalIndex = slice.map( (item, sliceIndex) => ({ item, originalIndex: mode === 'bottomToTop' ? visibleRange.end - 1 - sliceIndex : visibleRange.start + sliceIndex, sliceIndex }) )
-
-                    return itemsWithOriginalIndex
-                })() as currentItemWithIndex, i (currentItemWithIndex.originalIndex)}
+                {#each displayItems() as currentItemWithIndex, i (currentItemWithIndex.originalIndex)}
                     <!-- Only debug when visible range or average height changes -->
-                    {#if debug && i === 0 && shouldShowDebugInfo(prevVisibleRange, visibleItems(), prevHeight, calculatedItemHeight)}
+                    {#if debug && i === 0 && shouldShowDebugInfo(prevVisibleRange, visibleItems(), prevHeight, heightManager.averageHeight)}
                         {@const debugInfo = createDebugInfo(
                             visibleItems(),
                             items.length,
-                            Object.keys(heightCache).length,
-                            calculatedItemHeight,
-                            scrollTop,
+                            Object.keys(heightManager.getHeightCache()).length,
+                            heightManager.averageHeight,
+                            heightManager.scrollTop,
                             height || 0,
                             totalHeight()
                         )}
@@ -1177,6 +1243,11 @@
                         bind:this={itemElements[currentItemWithIndex.sliceIndex]}
                         use:autoObserveItemResize
                         data-original-index={currentItemWithIndex.originalIndex}
+                        {...testId
+                            ? {
+                                  'data-testid': `${testId}-item-${currentItemWithIndex.originalIndex}`
+                              }
+                            : {}}
                     >
                         {@render renderItem(
                             currentItemWithIndex.item,