@humanspeak/svelte-virtual-list 0.3.6 → 0.3.9

package/README.md

@@ -29,6 +29,7 @@ A high-performance virtual list component for Svelte 5 applications that efficie
 - 🧪 Comprehensive test coverage (vitest and playwright)
 - 🚀 Progressive initialization for large datasets
 - 🕹️ Programmatic scrolling with `scroll`
+- ♾️ Infinite scroll support with `onLoadMore`
 
 ## scroll: Programmatic Scrolling
 
@@ -76,6 +77,53 @@ You can now programmatically scroll to any item in the list using the `scroll` m
 </button>
 ```
 
+## Infinite Scroll
+
+Load more data automatically as users scroll near the end of the list. Perfect for paginated APIs, infinite feeds, and chat applications.
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
+
+    let items = $state([...initialItems])
+    let hasMore = $state(true)
+
+    async function loadMore() {
+        const newItems = await fetchMoreItems()
+        items = [...items, ...newItems]
+        if (newItems.length === 0) {
+            hasMore = false
+        }
+    }
+</script>
+
+<SvelteVirtualList {items} onLoadMore={loadMore} loadMoreThreshold={20} {hasMore}>
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### Infinite Scroll Props
+
+| Prop                | Type                          | Default | Description                                          |
+| ------------------- | ----------------------------- | ------- | ---------------------------------------------------- |
+| `onLoadMore`        | `() => void \| Promise<void>` | -       | Callback when more data is needed (supports async)   |
+| `loadMoreThreshold` | `number`                      | `20`    | Number of items from the end to trigger `onLoadMore` |
+| `hasMore`           | `boolean`                     | `true`  | Set to `false` when all data has been loaded         |
+
+### Infinite Scroll Behavior
+
+- Triggers when scrolling near the end of the list
+- Automatically triggers on mount if initial items are below threshold
+- Prevents concurrent `onLoadMore` calls while loading
+- Works with both sync and async callbacks
+- Supports both `topToBottom` and `bottomToTop` modes
+
+### Integration Guides
+
+- [Infinite Scroll with Convex](documentation/CONVEX_INFINITE_SCROLL.md) - Real-time data + pagination with Convex backend
+
 ## Installation
 
 ```bash
@@ -174,6 +222,9 @@ Use `mode="bottomToTop"` for chat-like lists anchored to the bottom. Programmati
 | `contentClass`               | `string`                         | `''`            | Class for content wrapper                                                     |
 | `itemsClass`                 | `string`                         | `''`            | Class for items container                                                     |
 | `testId`                     | `string`                         | `''`            | Base test id used in internal test hooks (useful for E2E/tests and debugging) |
+| `onLoadMore`                 | `() => void \| Promise<void>`    | -               | Callback when more data is needed for infinite scroll                         |
+| `loadMoreThreshold`          | `number`                         | `20`            | Items from end to trigger `onLoadMore`                                        |
+| `hasMore`                    | `boolean`                        | `true`          | Set to `false` when all data has been loaded                                  |
 
 ## Testing
 

package/dist/SvelteVirtualList.svelte

@@ -163,10 +163,12 @@
     import { createRafScheduler } from './utils/raf.js'
     import { isSignificantHeightChange } from './utils/heightChangeDetection.js'
     import {
-        calculateScrollPosition,
         calculateTransformY,
         calculateVisibleRange,
-        updateHeightAndScroll as utilsUpdateHeightAndScroll
+        clampValue,
+        updateHeightAndScroll as utilsUpdateHeightAndScroll,
+        getScrollOffsetForIndex,
+        buildBlockSums
     } from './utils/virtualList.js'
     import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
     import { calculateScrollTarget } from './utils/scrollCalculation.js'
@@ -184,8 +186,22 @@
     // Avoid SvelteKit-only $env imports so library works in non-Kit/Vitest contexts
     const INTERNAL_DEBUG = Boolean(
         typeof process !== 'undefined' &&
-            (process?.env?.PUBLIC_SVELTE_VIRTUAL_LIST_DEBUG === 'true' ||
-                process?.env?.SVELTE_VIRTUAL_LIST_DEBUG === 'true')
+        (process?.env?.PUBLIC_SVELTE_VIRTUAL_LIST_DEBUG === 'true' ||
+            process?.env?.SVELTE_VIRTUAL_LIST_DEBUG === 'true')
+    )
+    // Feature flags - default off; enable via env for incremental rollout
+    const anchorModeEnabled = Boolean(
+        typeof process !== 'undefined' &&
+        (process?.env?.PUBLIC_SVL_ANCHOR_MODE === 'true' ||
+            process?.env?.SVL_ANCHOR_MODE === 'true')
+    )
+    const idleCorrectionsOnly = Boolean(
+        typeof process !== 'undefined' &&
+        (process?.env?.PUBLIC_SVL_IDLE_ONLY === 'true' || process?.env?.SVL_IDLE_ONLY === 'true')
+    )
+    const batchUpdatesEnabled = Boolean(
+        typeof process !== 'undefined' &&
+        (process?.env?.PUBLIC_SVL_BATCH === 'true' || process?.env?.SVL_BATCH === 'true')
     )
     /**
      * Core configuration props with default values
@@ -203,7 +219,10 @@
         debugFunction, // Custom debug logging function
         mode = 'topToBottom', // Scroll direction mode
         bufferSize = 20, // Number of items to render outside visible area
-        testId // Base test ID for component elements (undefined = no data-testid attributes)
+        testId, // Base test ID for component elements (undefined = no data-testid attributes)
+        onLoadMore, // Callback when more data needed (supports sync and async)
+        loadMoreThreshold = 20, // Items from end to trigger load
+        hasMore = true // Set false when all data loaded
     }: SvelteVirtualListProps<TItem> = $props()
 
     /**
@@ -221,7 +240,101 @@
      */
 
     const isCalculatingHeight = $state(false) // Prevents concurrent height calculations
+    let isLoadingMore = $state(false) // Prevents concurrent onLoadMore calls
     let isScrolling = $state(false) // Tracks active scrolling state
+    let scrollIdleTimer: number | null = null
+    // Anchor state (read-only capture; used when anchorModeEnabled)
+    let lastAnchorIndex = $state(0)
+    let lastAnchorOffset = $state(0) // offset within anchored item (px)
+    let pendingAnchorReconcile = $state(false)
+    let batchDepth = $state(0)
+
+    const captureAnchor = () => {
+        if (!heightManager.viewportElement) return
+        const vr = visibleItems()
+        const anchorIndex = Math.max(0, vr.start)
+        const cache = heightManager.getHeightCache()
+        const est = heightManager.averageHeight
+        const maxScrollTop = Math.max(0, totalHeight() - (height || 0))
+        // Offset from start to anchored item
+        const blockSums = buildBlockSums(cache, est, items.length)
+        const offsetToIndex = getScrollOffsetForIndex(cache, est, anchorIndex, blockSums)
+        const currentTop = heightManager.viewport.scrollTop
+        let offsetWithin = 0
+        if (mode === 'bottomToTop') {
+            // Convert distance-from-end to distance-from-start
+            const distanceFromStart = maxScrollTop - currentTop
+            offsetWithin = distanceFromStart - offsetToIndex
+        } else {
+            offsetWithin = currentTop - offsetToIndex
+        }
+        lastAnchorIndex = anchorIndex
+        lastAnchorOffset = Math.max(0, Math.round(offsetWithin))
+        // Expose for tests
+        ;(heightManager.viewport as unknown as Record<string, unknown>).__svlAnchor = {
+            index: lastAnchorIndex,
+            offset: lastAnchorOffset
+        }
+        pendingAnchorReconcile = true
+    }
+
+    const reconcileToAnchorIfEnabled = () => {
+        if (!anchorModeEnabled || !heightManager.viewportElement) return
+        if (!pendingAnchorReconcile) return
+        const cache = heightManager.getHeightCache()
+        const est = heightManager.averageHeight
+        const blockSums = buildBlockSums(cache, est, items.length)
+        const offsetToIndex = getScrollOffsetForIndex(
+            cache,
+            est,
+            Math.max(0, lastAnchorIndex),
+            blockSums
+        )
+        const maxScrollTop = clampValue(totalHeight() - (height || 0), 0, Infinity)
+        let targetTop: number
+        if (mode === 'bottomToTop') {
+            const distanceFromStart = clampValue(offsetToIndex + lastAnchorOffset, 0, Infinity)
+            targetTop = clampValue(Math.round(maxScrollTop - distanceFromStart), 0, maxScrollTop)
+        } else {
+            targetTop = clampValue(Math.round(offsetToIndex + lastAnchorOffset), 0, maxScrollTop)
+        }
+        if (Math.abs(heightManager.viewport.scrollTop - targetTop) >= 2) {
+            syncScrollTop(targetTop)
+        }
+        pendingAnchorReconcile = false
+    }
+
+    /**
+     * Runs a batch of updates with scroll corrections coalesced until the batch completes.
+     *
+     * Use this method when making multiple changes to the items array to prevent
+     * intermediate scroll corrections. The scroll position reconciliation is deferred
+     * until the batch exits, ensuring smooth visual updates.
+     *
+     * @param {() => void} fn - The function containing batch updates to execute.
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // Add multiple items without intermediate scroll corrections
+     * list.runInBatch(() => {
+     *     items.push(newItem1);
+     *     items.push(newItem2);
+     *     items.push(newItem3);
+     * });
+     * ```
+     */
+    export const runInBatch = (fn: () => void): void => {
+        batchDepth += 1
+        try {
+            fn()
+        } finally {
+            batchDepth = Math.max(0, batchDepth - 1)
+            if (batchUpdatesEnabled && batchDepth === 0) {
+                reconcileToAnchorIfEnabled()
+            }
+        }
+    }
     let lastMeasuredIndex = $state(-1) // Index of last measured item
     let lastScrollTopSnapshot = $state(0) // Previous scroll position snapshot
 
@@ -267,6 +380,23 @@
         }
     }
 
+    /**
+     * Synchronizes the scroll position between the viewport element and internal state.
+     *
+     * This helper consolidates the repeated pattern of updating both
+     * heightManager.viewport.scrollTop and heightManager.scrollTop together,
+     * ensuring they stay in sync.
+     *
+     * @param {number} value - The scroll position to set
+     * @param {boolean} round - Whether to round the value to the nearest integer (default: false)
+     */
+    const syncScrollTop = (value: number, round = false) => {
+        if (!heightManager.viewportElement) return
+        const scrollValue = round ? Math.round(value) : value
+        heightManager.viewport.scrollTop = scrollValue
+        heightManager.scrollTop = scrollValue
+    }
+
     // Dynamic update coordination to avoid UA scroll anchoring interference
     let suppressBottomAnchoringUntilMs = $state(0)
 
@@ -306,6 +436,25 @@
         if (!heightManager.viewportElement || !heightManager.initialized || userHasScrolledAway) {
             return
         }
+        // Coalesce adjustments during active scroll; apply on idle
+        if (isScrolling) {
+            // Accumulate net change above viewport and defer application
+            let pending = 0
+            const currentVisibleRange = visibleItems()
+            for (const change of heightChanges) {
+                if (change.index < currentVisibleRange.start) pending += change.delta
+            }
+            if (pending !== 0) {
+                // Store on the viewport element to avoid extra module globals
+                const key = '__svl_pendingHeightAdj__' as unknown as keyof HTMLElement
+                const prev = (heightManager.viewport as unknown as Record<string, number>)[
+                    key as string
+                ] as number | undefined
+                ;(heightManager.viewport as unknown as Record<string, number>)[key as string] =
+                    (prev ?? 0) + pending
+            }
+            return
+        }
 
         /**
          * CRITICAL: BottomToTop Mode Height Change Fix
@@ -368,9 +517,8 @@
 
             // Step 1: Scroll to approximate position to ensure Item 0 gets rendered in virtual viewport
             const approximateScrollTop = Math.max(0, totalHeight() - height)
-            log('b2t-correction-approx', { approximateScrollTop })
-            heightManager.viewport.scrollTop = approximateScrollTop
-            heightManager.scrollTop = approximateScrollTop
+            log('[SVL] b2t-correction-approx', { approximateScrollTop })
+            syncScrollTop(approximateScrollTop)
 
             // Step 2: Use native scrollIntoView for precise bottom-edge positioning after DOM updates
             tick().then(() => {
@@ -392,7 +540,7 @@
                             behavior: 'smooth', // Smooth animation for better UX
                             inline: 'nearest' // Minimal horizontal adjustment
                         })
-                        log('b2t-correction-native', {
+                        log('[SVL] b2t-correction-native', {
                             containerBottom: contRect.y + contRect.height,
                             itemBottom: itemRect.y + itemRect.height
                         })
@@ -422,14 +570,23 @@
         }
 
         // 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)
+        // Include any pending coalesced delta (when scrolling)
+        {
+            const key = '__svl_pendingHeightAdj__' as unknown as keyof HTMLElement
+            const pending =
+                (heightManager.viewport as unknown as Record<string, number>)[key as string] ?? 0
+            if (pending) {
+                heightChangeAboveViewport += pending
+                ;(heightManager.viewport as unknown as Record<string, number>)[key as string] = 0
+            }
+        }
+        if (Math.abs(heightChangeAboveViewport) > 2) {
+            const newScrollTop = clampValue(
+                currentScrollTop + heightChangeAboveViewport,
+                0,
+                maxScrollTop
             )
-
-            heightManager.viewport.scrollTop = newScrollTop
-            heightManager.scrollTop = newScrollTop
+            syncScrollTop(newScrollTop)
         }
     }
 
@@ -461,6 +618,24 @@
         heightManager.updateItemLength(items.length)
     })
 
+    // Infinite scroll: trigger onLoadMore when approaching end of list
+    $effect(() => {
+        if (!BROWSER || !onLoadMore || !hasMore || isLoadingMore) return
+        // Skip loading during bottomToTop initialization (init path renders all items artificially)
+        if (mode === 'bottomToTop' && !bottomToTopScrollComplete) return
+
+        const range = visibleItems()
+        const atLoadingEdge = range.end >= items.length - loadMoreThreshold
+        const insufficientItems = items.length < loadMoreThreshold && heightManager.initialized
+
+        if (atLoadingEdge || insufficientItems) {
+            isLoadingMore = true
+            Promise.resolve(onLoadMore()).finally(() => {
+                isLoadingMore = false
+            })
+        }
+    })
+
     const updateHeight = () => {
         // Capture previous total height for scroll correction (topToBottom anchoring)
         prevTotalHeightForScrollCorrection = heightManager.totalHeight
@@ -502,12 +677,12 @@
                         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)
+                            const adjusted = clampValue(
+                                currentScrollTop + deltaTotal,
+                                0,
+                                maxScrollTop
                             )
-                            heightManager.viewport.scrollTop = adjusted
-                            heightManager.scrollTop = adjusted
+                            syncScrollTop(adjusted, true)
                         }
                     }
                 }
@@ -539,6 +714,9 @@
     let lastItemsLength = $state(0)
     // Track last observed total height to compute precise deltas on item count changes
     let lastTotalHeightObserved = $state(0)
+    // For bottomToTop mode: keep init path active until scroll positioning is complete
+    // This ensures Item 0 stays in the DOM throughout initialization
+    let bottomToTopScrollComplete = $state(false)
 
     /**
      * CRITICAL: O(1) Reactive Total Height Calculation
@@ -622,6 +800,7 @@
                 heightChanged &&
                 !userHasScrolledAway &&
                 !isAtBottom && // Don't apply aggressive correction when at bottom
+                !isScrolling && // Skip aggressive corrections during active scroll
                 !programmaticScrollInProgress && // Don't interfere with programmatic scrolls
                 performance.now() >= suppressBottomAnchoringUntilMs &&
                 !heightManager.isDynamicUpdateInProgress &&
@@ -629,9 +808,7 @@
 
             if (shouldCorrect) {
                 // Round to avoid subpixel positioning issues in bottomToTop mode
-                const roundedTargetScrollTop = Math.round(targetScrollTop)
-                heightManager.viewport.scrollTop = roundedTargetScrollTop
-                heightManager.scrollTop = roundedTargetScrollTop
+                syncScrollTop(targetScrollTop, true)
             }
 
             // Track if user has scrolled significantly away from bottom
@@ -687,10 +864,12 @@
                 // If near the bottom, this naturally pins to the new max; otherwise it preserves the current content.
                 programmaticScrollInProgress = true
                 void heightManager.runDynamicUpdate(() => {
-                    const unclamped = currentScrollTop + deltaMax
-                    const newScrollTop = Math.max(0, Math.min(nextMaxScrollTop, unclamped))
-                    heightManager.viewport.scrollTop = newScrollTop
-                    heightManager.scrollTop = newScrollTop
+                    const newScrollTop = clampValue(
+                        currentScrollTop + deltaMax,
+                        0,
+                        nextMaxScrollTop
+                    )
+                    syncScrollTop(newScrollTop)
                     log('[SVL] items-length-change:applied', {
                         instanceId,
                         previousScrollTop: currentScrollTop,
@@ -706,23 +885,20 @@
                     // Reconcile on next frame in case measured heights adjust totals
                     requestAnimationFrame(() => {
                         const beforeReconcileScrollTop = heightManager.viewport.scrollTop
-                        const reconciledNextMax = Math.max(0, totalHeight() - height)
+                        const reconciledNextMax = clampValue(totalHeight() - height, 0, Infinity)
                         const reconciledDeltaMaxChange = reconciledNextMax - nextMaxScrollTop
                         // Desired position is to maintain distance-from-end; equivalently keep (max - scrollTop) constant.
-                        const desiredScrollTop = Math.max(
+                        const desiredScrollTop = clampValue(
+                            newScrollTop + reconciledDeltaMaxChange,
                             0,
-                            Math.min(reconciledNextMax, newScrollTop + reconciledDeltaMaxChange)
+                            reconciledNextMax
                         )
                         // Snap to integer pixels to prevent oscillation due to subpixel rounding
                         const desiredRounded = Math.round(desiredScrollTop)
                         const diffToDesired = desiredRounded - heightManager.viewport.scrollTop
-                        if (Math.abs(diffToDesired) >= 1) {
-                            const adjusted = Math.max(
-                                0,
-                                Math.min(reconciledNextMax, desiredRounded)
-                            )
-                            heightManager.viewport.scrollTop = adjusted
-                            heightManager.scrollTop = adjusted
+                        if (Math.abs(diffToDesired) >= 2) {
+                            const adjusted = clampValue(desiredRounded, 0, reconciledNextMax)
+                            syncScrollTop(adjusted)
                             log('[SVL] items-length-change:reconciled', {
                                 instanceId,
                                 beforeReconcileScrollTop,
@@ -798,31 +974,18 @@
         if (!items.length) return { start: 0, end: 0 } as SvelteVirtualListPreviousVisibleRange
         const viewportHeight = height || 0
 
-        // For bottomToTop mode, don't calculate visible range until properly initialized
-        // This prevents showing wrong items when scrollTop starts at 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)
-
-            // Use the target scroll position for visible range calculation
-            lastVisibleRange = calculateVisibleRange(
-                targetScrollTop,
-                viewportHeight,
-                heightManager.averageHeight,
-                items.length,
-                bufferSize,
-                mode,
-                atBottom,
-                wasAtBottomBeforeHeightChange,
-                lastVisibleRange,
-                totalHeight(),
-                heightManager.getHeightCache()
-            )
+        // For bottomToTop mode, always render items starting from index 0 during initialization
+        // This ensures Item 0 is in the DOM so we can use scrollIntoView for precise positioning
+        // The scrollIntoView in updateHeightAndScroll will handle correct alignment after heights are measured
+        // Use bottomToTopScrollComplete (not just initialized) to keep init path active until scroll is done
+        if (mode === 'bottomToTop' && !bottomToTopScrollComplete) {
+            // Use a reasonable default if viewport height isn't measured yet
+            const effectiveViewport = viewportHeight || 400
+            const visibleCount = Math.ceil(effectiveViewport / heightManager.averageHeight) + 1
+            lastVisibleRange = {
+                start: 0,
+                end: Math.min(items.length, visibleCount + bufferSize * 2)
+            } as SvelteVirtualListPreviousVisibleRange
 
             return lastVisibleRange
         }
@@ -868,35 +1031,49 @@
     const handleScroll = () => {
         if (!BROWSER || !heightManager.viewportElement) return
 
-        if (!isScrolling) {
-            isScrolling = true
-            rafSchedule(() => {
-                const current = heightManager.viewport.scrollTop
-                if (mode === 'bottomToTop') {
-                    const delta = lastScrollTopSnapshot - current
-                    if (delta > 0.5) {
-                        // Widen suppression to avoid fighting peer instance corrections
-                        suppressBottomAnchoringUntilMs = performance.now() + 450
-                        userHasScrolledAway = true
-                    }
-                }
-                lastScrollTopSnapshot = current
-                heightManager.scrollTop = current
-                updateDebugTailDistance()
-                if (INTERNAL_DEBUG) {
-                    const vr = visibleItems()
-                    log('scroll', {
-                        mode,
-                        scrollTop: heightManager.scrollTop,
-                        height,
-                        totalHeight: totalHeight(),
-                        averageItemHeight: heightManager.averageHeight,
-                        visibleRange: vr
-                    })
-                }
-                isScrolling = false
-            })
+        // Mark active scrolling and debounce idle transition (~120ms)
+        isScrolling = true
+        if (scrollIdleTimer) {
+            clearTimeout(scrollIdleTimer)
+            scrollIdleTimer = null
         }
+        scrollIdleTimer = window.setTimeout(() => {
+            isScrolling = false
+            // Apply deferred anchor correction on idle
+            if (idleCorrectionsOnly || anchorModeEnabled) {
+                reconcileToAnchorIfEnabled()
+            }
+        }, 250)
+
+        rafSchedule(() => {
+            const current = heightManager.viewport.scrollTop
+            if (mode === 'bottomToTop') {
+                const delta = lastScrollTopSnapshot - current
+                if (delta > 0.5) {
+                    // Widen suppression to avoid fighting peer instance corrections
+                    suppressBottomAnchoringUntilMs = performance.now() + 450
+                    userHasScrolledAway = true
+                }
+            }
+            lastScrollTopSnapshot = current
+            heightManager.scrollTop = current
+            updateDebugTailDistance()
+            if (anchorModeEnabled) {
+                captureAnchor()
+            }
+            if (INTERNAL_DEBUG) {
+                const vr = visibleItems()
+                log('[SVL] scroll', {
+                    mode,
+                    scrollTop: heightManager.scrollTop,
+                    height,
+                    totalHeight: totalHeight(),
+                    averageItemHeight: heightManager.averageHeight,
+                    visibleRange: vr
+                })
+            }
+            // isScrolling cleared by idle timer
+        })
     }
 
     /**
@@ -920,7 +1097,8 @@
             mode
         })
         if (!heightManager.initialized && mode === 'bottomToTop') {
-            // Deterministic init order: double RAF + microtask, then apply bottom anchoring
+            // bottomToTop initialization: use scrollIntoView on Item 0 for precise positioning
+            // visibleItems() guarantees Item 0 is rendered during initialization
             tick().then(() => {
                 requestAnimationFrame(() => {
                     requestAnimationFrame(() => {
@@ -928,11 +1106,7 @@
                         const measuredHeight =
                             heightManager.container.getBoundingClientRect().height
                         height = measuredHeight
-                        const targetScrollTop = calculateScrollPosition(
-                            items.length,
-                            heightManager.averageHeight,
-                            measuredHeight
-                        )
+
                         // Instance jitter to avoid same-frame collisions when two lists init together
                         const cleanedId = String(instanceId)
                             .toLowerCase()
@@ -942,32 +1116,48 @@
                         const jitterMs = Number.isNaN(parsed)
                             ? Math.floor(Math.random() * 3)
                             : parsed % 3
-                        log('b2t-init', { measuredHeight, targetScrollTop, jitterMs })
+
                         setTimeout(() => {
-                            heightManager.viewport.scrollTop = targetScrollTop
-                            heightManager.scrollTop = targetScrollTop
+                            // Step 1: Set initialized (for other purposes like scroll event handling)
+                            // The init path in visibleItems() stays active until bottomToTopScrollComplete
+                            if (!heightManager.initialized) {
+                                heightManager.initialized = true
+                            }
+
+                            // Step 2: Use scrollIntoView on Item 0 for precise positioning
+                            // Use double RAF to ensure heights are measured and layout is stable
                             requestAnimationFrame(() => {
-                                // Guard: only transition false -> true to avoid invariant error
-                                if (!heightManager.initialized) heightManager.initialized = true
-                                // Post-init verification: ensure item 0 bottom aligns; fallback to native
-                                tick().then(() => {
+                                requestAnimationFrame(() => {
+                                    // Item 0 is guaranteed to be in DOM due to init path
+                                    // Skip if user has already scrolled (scrollTop significantly != 0)
+                                    const currentScroll = heightManager.viewport.scrollTop
+                                    const userHasScrolled =
+                                        currentScroll > heightManager.averageHeight
                                     const el = heightManager.viewport.querySelector(
                                         '[data-original-index="0"]'
                                     ) as HTMLElement | null
-                                    if (!el) return
-                                    const cont = heightManager.viewport.getBoundingClientRect()
-                                    const r = el.getBoundingClientRect()
-                                    const tol = 4
-                                    const aligned =
-                                        Math.abs(cont.y + cont.height - (r.y + r.height)) <= tol
-                                    if (!aligned) {
-                                        el.scrollIntoView({ block: 'end', inline: 'nearest' })
-                                        heightManager.scrollTop = heightManager.viewport.scrollTop
-                                        log('b2t-init-native-fallback', {
-                                            containerBottom: cont.y + cont.height,
-                                            itemBottom: r.y + r.height
+
+                                    if (el && !userHasScrolled) {
+                                        el.scrollIntoView({
+                                            block: 'end',
+                                            inline: 'nearest'
                                         })
+                                        heightManager.scrollTop = heightManager.viewport.scrollTop
+                                    } else if (userHasScrolled) {
+                                        // Sync internal state with current scroll
+                                        heightManager.scrollTop = currentScroll
                                     }
+
+                                    // Step 3: Mark scroll complete - switches visibleItems to normal mode
+                                    requestAnimationFrame(() => {
+                                        bottomToTopScrollComplete = true
+                                        // Reset bottom-anchoring flag to prevent stale state from init
+                                        // affecting later operations (e.g., adding items while scrolled away)
+                                        wasAtBottomBeforeHeightChange = false
+                                        // Suppress bottom-anchoring briefly to let heights stabilize
+                                        // after switching to normal mode
+                                        suppressBottomAnchoringUntilMs = performance.now() + 200
+                                    })
                                 })
                             })
                         }, jitterMs)
@@ -1192,7 +1382,7 @@
                     `scroll: index ${targetIndex} is out of bounds (0-${items.length - 1})`
                 )
             } else {
-                targetIndex = Math.max(0, Math.min(targetIndex, items.length - 1))
+                targetIndex = clampValue(targetIndex, 0, items.length - 1)
             }
         }
 
@@ -1348,7 +1538,6 @@
                 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 || measuredFallbackHeight || 0
                     const visibleRange = visibleItems()