@humanspeak/svelte-virtual-list 0.2.6-beta.5 → 0.2.6-beta.7

package/dist/SvelteVirtualList.svelte

@@ -161,6 +161,7 @@
     } from './types.js'
     import { calculateAverageHeightDebounced } from './utils/heightCalculation.js'
     import { createRafScheduler } from './utils/raf.js'
+    import { isSignificantHeightChange } from './utils/heightChangeDetection.js'
     import {
         calculateScrollPosition,
         calculateTransformY,
@@ -169,12 +170,16 @@
     } from './utils/virtualList.js'
     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 { BROWSER } from 'esm-env'
-    import { onMount, tick } from 'svelte'
+    import { onMount, tick, untrack } from 'svelte'
 
     const rafSchedule = createRafScheduler()
-    const INTERNAL_DEBUG = false
+    // Package-specific debug flag - safe for library distribution
+    // Enable with: NODE_ENV=development SVELTE_VIRTUAL_LIST_DEBUG=true
+    const INTERNAL_DEBUG =
+        import.meta.env.DEV && import.meta.env.VITE_SVELTE_VIRTUAL_LIST_DEBUG === 'true'
     /**
      * Core configuration props with default values
      * @type {SvelteVirtualListProps}
@@ -215,6 +220,7 @@
     let 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
 
     /**
      * Timers and Observers
@@ -228,15 +234,182 @@
      */
     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
+    let dirtyItemsCount = $state(0) // Reactive count of dirty items
 
     let prevVisibleRange = $state<SvelteVirtualListPreviousVisibleRange | null>(null)
     let prevHeight = $state<number>(0)
 
-    // Trigger height calculation when items are rendered
-    $effect(() => {
-        if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
-            updateHeight()
+    /**
+     * Reactive Height Manager - O(1) height calculation system
+     * Replaces O(n) totalHeight loop with incremental updates
+     */
+    let heightManager = new ReactiveHeightManager({
+        itemLength: items.length,
+        itemHeight: defaultEstimatedItemHeight
+    })
+
+    // 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')
+        }
+    }
+
+    /**
+     * Handles scroll position corrections when item heights change, ensuring proper positioning
+     * relative to the user's scroll context. This function calculates the cumulative impact of
+     * height changes above the current viewport and adjusts the scroll position accordingly.
+     *
+     * The correction logic considers:
+     * - Height changes occurring above the visible area (which would shift content)
+     * - The current scroll position and visible range
+     * - Whether height changes warrant a scroll adjustment
+     *
+     * This prevents jarring jumps when items resize, maintaining the user's visual context
+     * and where they are positioned relative to the current scroll position.
+     */
+    const handleHeightChangesScrollCorrection = (
+        heightChanges: Array<{ index: number; oldHeight: number; newHeight: number; delta: number }>
+    ) => {
+        if (!viewportElement || !initialized || userHasScrolledAway) {
+            return
+        }
+
+        /**
+         * CRITICAL: BottomToTop Mode Height Change Fix
+         * ============================================
+         *
+         * Problem: In bottomToTop mode, when items change height while user is at bottom,
+         * the list would jump to middle positions (e.g. items 1032-1096) instead of
+         * staying anchored at bottom showing Item 0.
+         *
+         * Root Cause: Height calculations using simple averages (items.length * calculatedItemHeight)
+         * were drastically skewed by single item changes. Example:
+         * - 1 item changes from 20px to 100px (+80px actual change)
+         * - Average jumps from 20px to 22.35px (+2.35px per item)
+         * - Across 10,000 items: 2.35px × 10,000 = 23,500px total height error!
+         * - This caused massive scroll position overshoots and incorrect positioning
+         *
+         * Solution: Two-step native scrollIntoView approach
+         * 1. Fixed skewed height calculations using actual heightCache measurements (see totalHeight)
+         * 2. When wasAtBottomBeforeHeightChange=true (captured before any height processing):
+         *    a) First scroll to approximate bottom position to render Item 0 in virtual viewport
+         *    b) Use native scrollIntoView() with block:'end' for precise bottom alignment
+         *
+         * Why This Works:
+         * - Uses browser's native scroll logic instead of error-prone manual calculations
+         * - Two-step ensures Item 0 exists in DOM before attempting to scroll to it
+         * - Native scrollIntoView handles all edge cases (subpixel precision, browser differences)
+         * - Eliminates complex math that was accumulating rounding errors
+         * - Smooth behavior provides better UX than instant jumps
+         *
+         * Dependencies:
+         * - wasAtBottomBeforeHeightChange: Set to true when first item marked dirty, prevents cascading corrections
+         * - totalHeight(): Uses actual heightCache measurements instead of skewed averages
+         * - Aggressive scroll correction: Blocked when wasAtBottomBeforeHeightChange=true
+         *
+         * ⚠️  DO NOT MODIFY WITHOUT EXTENSIVE TESTING ⚠️
+         * This fix resolves a complex interaction between:
+         * - Virtual list rendering (only ~20 items visible, rest virtualized)
+         * - Height change calculations (prone to average skewing with large datasets)
+         * - Multiple scroll correction mechanisms (specific vs aggressive)
+         * - Bottom anchor positioning in reversed list mode (bottomToTop)
+         *
+         * Test coverage: tests/bottomToTop/firstItemHeightChange.spec.ts (45 comprehensive tests)
+         * Related fixes: See aggressive scroll correction logic ~line 410 with !wasAtBottomBeforeHeightChange
+         */
+        if (
+            mode === 'bottomToTop' &&
+            wasAtBottomBeforeHeightChange &&
+            !programmaticScrollInProgress &&
+            performance.now() >= suppressBottomAnchoringUntilMs &&
+            !dynamicUpdateInProgress
+        ) {
+            // 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
+
+            // Step 2: Use native scrollIntoView for precise bottom-edge positioning after DOM updates
+            tick().then(() => {
+                const item0Element = viewportElement.querySelector('[data-original-index="0"]')
+                if (item0Element) {
+                    // Native browser API handles all positioning edge cases perfectly
+                    item0Element.scrollIntoView({
+                        block: 'end', // Align Item 0 to bottom edge of viewport
+                        behavior: 'smooth', // Smooth animation for better UX
+                        inline: 'nearest' // Minimal horizontal adjustment
+                    })
+
+                    // Sync our internal scroll state with actual DOM position
+                    scrollTop = viewportElement.scrollTop
+                }
+            })
+
+            return // Skip remaining scroll correction logic - we've handled bottomToTop case
+        }
+
+        const currentScrollTop = viewportElement.scrollTop
+        const maxScrollTop = Math.max(0, totalHeight() - height)
+
+        // Calculate total height change impact above current visible area
+        let heightChangeAboveViewport = 0
+        const currentVisibleRange = visibleItems()
+
+        for (const change of heightChanges) {
+            // Only consider items that are above the current visible range
+            if (change.index < currentVisibleRange.start) {
+                heightChangeAboveViewport += change.delta
+            }
+        }
+
+        // If there are height changes above the viewport, adjust scroll to maintain position
+        if (Math.abs(heightChangeAboveViewport) > 1) {
+            const newScrollTop = Math.min(
+                maxScrollTop,
+                Math.max(0, currentScrollTop + heightChangeAboveViewport)
+            )
+
+            viewportElement.scrollTop = newScrollTop
+            scrollTop = newScrollTop
+        }
+    }
+
+    // Height update function - removed throttling to fix race condition on initial load
+    // Create throttled height update function with trailing execution to ensure measurement always happens
+    const triggerHeightUpdate = createAdvancedThrottledCallback(
+        () => {
+            if (BROWSER && dirtyItemsCount > 0) {
+                // Capture bottom state before any height processing to prevent cascading corrections
+                wasAtBottomBeforeHeightChange = atBottom
+                beginDynamicUpdate()
+                updateHeight()
+            }
+        },
+        16,
+        {
+            leading: true, // Execute immediately for responsiveness
+            trailing: true // CRUCIAL: Execute the last call after delay to ensure measurement always happens
         }
+    )
+
+    // Trigger height calculation when dirty items are added
+    $effect(() => {
+        triggerHeightUpdate()
+    })
+
+    // Keep height manager synchronized with items length
+    $effect(() => {
+        heightManager.updateItemLength(items.length)
     })
 
     const updateHeight = () => {
@@ -247,44 +420,93 @@
             itemElements,
             heightCache,
             lastMeasuredIndex,
-            calculatedItemHeight,
+            heightManager.averageHeight,
             (result) => {
-                calculatedItemHeight = result.newHeight
+                // Critical updates that must trigger reactive effects immediately
+                heightManager.itemHeight = result.newHeight
                 lastMeasuredIndex = result.newLastMeasuredIndex
                 heightCache = result.updatedHeightCache
 
-                // Update running totals efficiently (O(1) instead of O(n)!)
-                totalMeasuredHeight = result.newTotalHeight
-                measuredCount = result.newValidCount
+                // Handle height changes for scroll correction (needs updated heightCache)
+                if (result.heightChanges.length > 0 && mode === 'bottomToTop') {
+                    handleHeightChangesScrollCorrection(result.heightChanges)
+                }
 
-                // Clear processed dirty items
-                result.clearedDirtyItems.forEach((index) => {
-                    dirtyItems.delete(index)
-                })
+                // 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)
+                    }
 
-                if (INTERNAL_DEBUG && result.clearedDirtyItems.size > 0) {
-                    console.log(
-                        `Cleared ${result.clearedDirtyItems.size} dirty items:`,
-                        Array.from(result.clearedDirtyItems)
-                    )
-                }
+                    // Clear processed dirty items (all dirty items were processed)
+                    dirtyItems.clear()
+                    dirtyItemsCount = 0
+
+                    // Reset bottom state flag
+                    wasAtBottomBeforeHeightChange = false
+                })
+                endDynamicUpdate()
             },
             100, // debounceTime
             dirtyItems, // Pass dirty items for processing
-            totalMeasuredHeight, // Current running total height
-            measuredCount // Current running total count
+            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
+            mode // Pass mode for correct element indexing
         )
     }
 
     // Add new effect to handle height changes
     // Track if user has scrolled away from bottom to prevent snap-back
     let userHasScrolledAway = $state(false)
+    let programmaticScrollInProgress = $state(false) // Prevent bottom-anchoring during programmatic scrolls
     let lastCalculatedHeight = $state(0)
+    let lastItemsLength = $state(0)
+
+    /**
+     * CRITICAL: O(1) Reactive Total Height Calculation
+     * ===============================================
+     *
+     * Uses ReactiveHeightManager 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:
+     * - Looped through ALL items on every reactive update
+     * - Used simple: items.length * calculatedItemHeight
+     * - When 1 item changes from 20px to 100px in 10,000 items:
+     *   - calculatedItemHeight jumps from 20 to 22.35 (+2.35px)
+     *   - Total height jumps from 200,000px to 223,500px (+23,500px!)
+     *   - This 23,500px error caused massive scroll position overshoots
+     *
+     * Solution with ReactiveHeightManager:
+     * - 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
+     * - Processes only dirty/changed heights instead of all items
+     *
+     * Example with O(1) Approach:
+     * - 20 items measured: 19 × 20px + 1 × 100px = 460px measured
+     * - 9,980 unmeasured: 9,980 × 23px (avg of measured) = 229,540px estimated
+     * - Total: 460px + 229,540px = 230,000px (only +30,000px vs +23,500px error)
+     * - Much smaller error that doesn't cause massive scroll jumps
+     * - Updates incrementally using processDirtyHeights() instead of recalculating all
+     *
+     * 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)
+
+    let atTop = $derived(scrollTop <= 1)
+    let atBottom = $derived(scrollTop >= totalHeight() - height - 1)
+    let wasAtBottomBeforeHeightChange = false
+    let lastVisibleRange: SvelteVirtualListPreviousVisibleRange | null = null
+
+    $inspect('scrollState: atTop', atTop)
+    $inspect('scrollState: atBottom', atBottom)
 
     $effect(() => {
         if (BROWSER && initialized && mode === 'bottomToTop' && viewportElement) {
-            const totalHeight = Math.max(0, items.length * calculatedItemHeight)
-            const targetScrollTop = Math.max(0, totalHeight - height)
+            const targetScrollTop = Math.max(0, totalHeight() - height)
             const currentScrollTop = viewportElement.scrollTop
             const scrollDifference = Math.abs(currentScrollTop - targetScrollTop)
 
@@ -292,25 +514,26 @@
             // 1. Item height changed significantly (not just user scrolling)
             // 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 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 shouldCorrect =
-                heightChanged && !userHasScrolledAway && scrollDifference > calculatedItemHeight * 3
+                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
 
             if (shouldCorrect) {
-                if (INTERNAL_DEBUG) {
-                    console.log(
-                        '🔄 Correcting scroll position from',
-                        currentScrollTop,
-                        'to',
-                        targetScrollTop,
-                        'diff:',
-                        scrollDifference,
-                        'heightChanged:',
-                        heightChanged
-                    )
-                }
-                viewportElement.scrollTop = targetScrollTop
-                scrollTop = targetScrollTop
+                // Round to avoid subpixel positioning issues in bottomToTop mode
+                const roundedTargetScrollTop = Math.round(targetScrollTop)
+                viewportElement.scrollTop = roundedTargetScrollTop
+                scrollTop = roundedTargetScrollTop
             }
 
             // Track if user has scrolled significantly away from bottom
@@ -322,6 +545,56 @@
         }
     })
 
+    // Handle items being added/removed in bottomToTop mode
+    $effect(() => {
+        // Only track items.length to prevent re-runs on other reactive changes
+        const currentItemsLength = items.length
+
+        if (
+            BROWSER &&
+            initialized &&
+            mode === 'bottomToTop' &&
+            viewportElement &&
+            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 currentHeight = height
+                const currentTotalHeight = totalHeight()
+                const maxScrollTop = Math.max(0, currentTotalHeight - currentHeight)
+
+                // Check if user was at/near the bottom before items were added
+                const wasNearBottom =
+                    Math.abs(
+                        currentScrollTop -
+                            Math.max(
+                                0,
+                                lastItemsLength * currentCalculatedItemHeight - currentHeight
+                            )
+                    ) <
+                    currentCalculatedItemHeight * 2
+
+                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()
+                }
+            }
+        }
+
+        lastItemsLength = currentItemsLength
+    })
+
     // Update container height when element is mounted
     $effect(() => {
         if (BROWSER && containerElement) {
@@ -339,8 +612,7 @@
             items.length &&
             !initialized
         ) {
-            const totalHeight = Math.max(0, items.length * calculatedItemHeight)
-            const targetScrollTop = Math.max(0, totalHeight - height)
+            const targetScrollTop = Math.max(0, totalHeight() - height)
 
             // Add delay to ensure layout is complete
             tick().then(() => {
@@ -362,23 +634,6 @@
         }
     })
 
-    /**
-     * Calculate precise item height based on actual measurements when available
-     */
-    // Running totals for efficient precise height calculation
-    let totalMeasuredHeight = $state(0)
-    let measuredCount = $state(0)
-    const preciseItemHeight = $derived(() => {
-        if (measuredCount > 100) {
-            const avgHeight = totalMeasuredHeight / measuredCount
-            // Only use if the difference is significant (more than 0.5px)
-            if (Math.abs(avgHeight - calculatedItemHeight) > 0.5) {
-                return avgHeight
-            }
-        }
-        return calculatedItemHeight
-    })
-
     /**
      * Calculates the range of items that should be rendered based on current scroll position.
      *
@@ -406,32 +661,39 @@
         // This prevents showing wrong items when scrollTop starts at 0
         if (mode === 'bottomToTop' && !initialized && scrollTop === 0 && viewportHeight > 0) {
             // Calculate what the correct scroll position should be
-            const totalHeight = items.length * calculatedItemHeight
-            const targetScrollTop = Math.max(0, totalHeight - viewportHeight)
+            const targetScrollTop = Math.max(0, totalHeight() - viewportHeight)
 
             // Use the target scroll position for visible range calculation
-            const result = calculateVisibleRange(
+            lastVisibleRange = calculateVisibleRange(
                 targetScrollTop,
                 viewportHeight,
-                calculatedItemHeight,
+                heightManager.averageHeight,
                 items.length,
                 bufferSize,
-                mode
+                mode,
+                atBottom,
+                wasAtBottomBeforeHeightChange,
+                lastVisibleRange,
+                totalHeight()
             )
 
-            return result
+            return lastVisibleRange
         }
 
-        const result = calculateVisibleRange(
+        lastVisibleRange = calculateVisibleRange(
             scrollTop,
             viewportHeight,
-            calculatedItemHeight,
+            heightManager.averageHeight,
             items.length,
             bufferSize,
-            mode
+            mode,
+            atBottom,
+            wasAtBottomBeforeHeightChange,
+            lastVisibleRange,
+            totalHeight()
         )
 
-        return result
+        return lastVisibleRange
     })
 
     /**
@@ -461,7 +723,16 @@
         if (!isScrolling) {
             isScrolling = true
             rafSchedule(() => {
-                scrollTop = viewportElement.scrollTop
+                const current = viewportElement.scrollTop
+                if (mode === 'bottomToTop') {
+                    const delta = lastScrollTopSnapshot - current
+                    if (delta > 0.5) {
+                        suppressBottomAnchoringUntilMs = performance.now() + 300
+                        userHasScrolledAway = true
+                    }
+                }
+                lastScrollTopSnapshot = current
+                scrollTop = current
                 isScrolling = false
             })
         }
@@ -544,37 +815,45 @@
     if (BROWSER) {
         // Watch for individual item size changes
         itemResizeObserver = new ResizeObserver((entries) => {
-            let shouldRecalculate = false
-
-            if (INTERNAL_DEBUG) {
-                console.log(`ResizeObserver fired for ${entries.length} entries`)
-            }
-
-            for (const entry of entries) {
-                const element = entry.target as HTMLElement
-                const elementIndex = itemElements.indexOf(element)
-
-                if (elementIndex !== -1) {
-                    const actualIndex = visibleItems().start + elementIndex
+            tick().then(() => {
+                let shouldRecalculate = false
+                const visibleRange = visibleItems() // Cache once to avoid reactive loops
+
+                for (const entry of entries) {
+                    const element = entry.target as HTMLElement
+                    const elementIndex = itemElements.indexOf(element)
+                    const actualIndex = parseInt(element.dataset.originalIndex || '-1', 10)
+
+                    if (elementIndex !== -1) {
+                        if (actualIndex >= 0) {
+                            const currentHeight = element.getBoundingClientRect().height
+                            const isSignificant = isSignificantHeightChange(
+                                actualIndex,
+                                currentHeight,
+                                heightCache
+                            )
 
-                    // ResizeObserver fired = element resized, so add to dirty queue
-                    dirtyItems.add(actualIndex)
-                    shouldRecalculate = true
+                            // Only mark as dirty if height change is significant
+                            if (isSignificant) {
+                                // Capture bottom state when FIRST item gets marked dirty
+                                if (dirtyItemsCount === 0) {
+                                    wasAtBottomBeforeHeightChange = atBottom
+                                }
 
-                    if (INTERNAL_DEBUG) {
-                        console.log(
-                            `Item ${actualIndex} marked dirty (resized), queue size: ${dirtyItems.size}`
-                        )
+                                dirtyItems.add(actualIndex)
+                                dirtyItemsCount = dirtyItems.size
+                                shouldRecalculate = true
+                            }
+                        }
                     }
                 }
-            }
 
-            if (shouldRecalculate) {
-                // Trigger virtual list recalculation
-                rafSchedule(() => {
-                    updateHeight()
-                })
-            }
+                if (shouldRecalculate) {
+                    rafSchedule(() => {
+                        updateHeight()
+                    })
+                }
+            })
         })
     }
 
@@ -681,10 +960,10 @@
      *   {/snippet}
      * </SvelteVirtualList>
      *
-     * @returns {void}
+     * @returns {Promise<void>} Promise that resolves when scrolling is complete
      * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
      */
-    export const scroll = (options: SvelteVirtualListScrollOptions): void => {
+    export const scroll = async (options: SvelteVirtualListScrollOptions): Promise<void> => {
         const { index, smoothScroll, shouldThrowOnBounds, align } = {
             ...DEFAULT_SCROLL_OPTIONS,
             ...options
@@ -716,10 +995,10 @@
         // Use extracted scroll calculation utility
         const scrollTarget = calculateScrollTarget({
             mode,
-            align,
+            align: align || 'auto',
             targetIndex,
             itemsLength: items.length,
-            calculatedItemHeight,
+            calculatedItemHeight: heightManager.averageHeight, // Use dynamic average from ReactiveHeightManager
             height,
             scrollTop,
             firstVisibleIndex,
@@ -732,10 +1011,52 @@
             return
         }
 
+        // Prevent bottom-anchoring logic from interfering with programmatic scroll
+        programmaticScrollInProgress = true
+
+        // 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
+        // visible element provides consistent cross-browser smooth scrolling behavior.
+        // 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]')
+            let maxIndex = -1
+            let maxElement: HTMLElement | null = null
+            for (const el of visibleElements) {
+                const index = parseInt(el.getAttribute('data-original-index') || '-1')
+                if (index > maxIndex) {
+                    maxIndex = index
+                    maxElement = el as HTMLElement
+                }
+            }
+
+            maxElement?.scrollIntoView({
+                behavior: 'smooth'
+            })
+            await tick()
+            await new Promise((resolve) => setTimeout(resolve, 100))
+            await tick()
+        }
+
         viewportElement.scrollTo({
             top: scrollTarget,
             behavior: smoothScroll ? 'smooth' : 'auto'
         })
+
+        // Update scrollTop state in next frame to avoid synchronous re-renders
+        requestAnimationFrame(() => {
+            scrollTop = scrollTarget
+        })
+
+        // Clear the flag after scroll completes
+        setTimeout(
+            () => {
+                programmaticScrollInProgress = false
+            },
+            smoothScroll ? 500 : 100
+        )
     }
 
     /**
@@ -748,25 +1069,12 @@
     function autoObserveItemResize(element: HTMLElement) {
         if (itemResizeObserver) {
             itemResizeObserver.observe(element)
-            if (INTERNAL_DEBUG) {
-                console.log(
-                    'Started observing element:',
-                    element,
-                    'Current height:',
-                    element.getBoundingClientRect().height
-                )
-            }
-        } else if (INTERNAL_DEBUG) {
-            console.log('itemResizeObserver not available for element:', element)
         }
 
         return {
             destroy() {
                 if (itemResizeObserver) {
                     itemResizeObserver.unobserve(element)
-                    if (INTERNAL_DEBUG) {
-                        console.log('Stopped observing element:', element)
-                    }
                 }
             }
         }
@@ -800,9 +1108,8 @@
             {...testId ? { 'data-testid': `${testId}-content` } : {}}
             class={contentClass ?? 'virtual-list-content'}
             style:height="{(() => {
-                // Use precise height when available for better cross-browser compatibility
-                const totalActualHeight = items.length * preciseItemHeight()
-                return Math.max(height, totalActualHeight)
+                // Use ReactiveHeightManager's accurate total height for better cross-browser compatibility
+                return Math.max(height, totalHeight())
             })()}px"
         >
             <!-- Items container is translated to show correct items -->
@@ -810,25 +1117,46 @@
                 id="virtual-list-items"
                 {...testId ? { 'data-testid': `${testId}-items` } : {}}
                 class={itemsClass ?? 'virtual-list-items'}
+                style:visibility={height === 0 && mode === 'bottomToTop' ? 'hidden' : 'visible'}
                 style:transform="translateY({(() => {
+                    const viewportHeight = height || 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
+                    }
+
                     const transform = calculateTransformY(
                         mode,
                         items.length,
-                        visibleItems().end,
-                        visibleItems().start,
-                        calculatedItemHeight
+                        visibleRange.end,
+                        visibleRange.start,
+                        heightManager.averageHeight,
+                        effectiveHeight,
+                        totalHeight() // Pass ReactiveHeightManager's accurate total height
                     )
 
                     return transform
                 })()}px)"
             >
                 {#each (() => {
+                    const visibleRange = visibleItems()
                     const slice = mode === 'bottomToTop' ? items
-                                  .slice(visibleItems().start, visibleItems().end)
-                                  .reverse() : items.slice(visibleItems().start, visibleItems().end)
+                                  .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 slice
-                })() as currentItem, i (currentItem?.id ?? i)}
+                    return itemsWithOriginalIndex
+                })() as currentItemWithIndex, i (currentItemWithIndex.originalIndex)}
                     <!-- Only debug when visible range or average height changes -->
                     {#if debug && i === 0 && shouldShowDebugInfo(prevVisibleRange, visibleItems(), prevHeight, calculatedItemHeight)}
                         {@const debugInfo = createDebugInfo(
@@ -837,19 +1165,22 @@
                             Object.keys(heightCache).length,
                             calculatedItemHeight,
                             scrollTop,
-                            height || 0
+                            height || 0,
+                            totalHeight()
                         )}
                         {debugFunction
                             ? debugFunction(debugInfo)
                             : console.info('Virtual List Debug:', debugInfo)}
                     {/if}
                     <!-- Render each visible item -->
-                    <div bind:this={itemElements[i]} use:autoObserveItemResize>
+                    <div
+                        bind:this={itemElements[currentItemWithIndex.sliceIndex]}
+                        use:autoObserveItemResize
+                        data-original-index={currentItemWithIndex.originalIndex}
+                    >
                         {@render renderItem(
-                            currentItem,
-                            mode === 'bottomToTop'
-                                ? items.length - (visibleItems().start + i) - 1
-                                : visibleItems().start + i
+                            currentItemWithIndex.item,
+                            currentItemWithIndex.originalIndex
                         )}
                     </div>
                 {/each}