@humanspeak/svelte-virtual-list 0.3.5 → 0.3.8

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

@@ -166,7 +166,9 @@
         calculateScrollPosition,
         calculateTransformY,
         calculateVisibleRange,
-        updateHeightAndScroll as utilsUpdateHeightAndScroll
+        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,108 @@
      */
 
     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 = Math.max(0, totalHeight() - (height || 0))
+        let targetTop: number
+        if (mode === 'bottomToTop') {
+            const distanceFromStart = Math.max(0, offsetToIndex + lastAnchorOffset)
+            targetTop = Math.max(
+                0,
+                Math.min(maxScrollTop, Math.round(maxScrollTop - distanceFromStart))
+            )
+        } else {
+            targetTop = Math.max(
+                0,
+                Math.min(maxScrollTop, Math.round(offsetToIndex + lastAnchorOffset))
+            )
+        }
+        if (Math.abs(heightManager.viewport.scrollTop - targetTop) >= 2) {
+            heightManager.viewport.scrollTop = targetTop
+            heightManager.scrollTop = 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
 
@@ -306,6 +426,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,7 +507,7 @@
 
             // 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 })
+            log('[SVL] b2t-correction-approx', { approximateScrollTop })
             heightManager.viewport.scrollTop = approximateScrollTop
             heightManager.scrollTop = approximateScrollTop
 
@@ -392,7 +531,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,7 +561,17 @@
         }
 
         // If there are height changes above the viewport, adjust scroll to maintain position
-        if (Math.abs(heightChangeAboveViewport) > 1) {
+        // 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 = Math.min(
                 maxScrollTop,
                 Math.max(0, currentScrollTop + heightChangeAboveViewport)
@@ -461,6 +610,22 @@
         heightManager.updateItemLength(items.length)
     })
 
+    // Infinite scroll: trigger onLoadMore when approaching end of list
+    $effect(() => {
+        if (!BROWSER || !onLoadMore || !hasMore || isLoadingMore) 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,9 +667,8 @@
                         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 = Math.round(
+                                Math.min(maxScrollTop, Math.max(0, currentScrollTop + deltaTotal))
                             )
                             heightManager.viewport.scrollTop = adjusted
                             heightManager.scrollTop = adjusted
@@ -537,6 +701,8 @@
     let programmaticScrollInProgress = $state(false) // Prevent bottom-anchoring during programmatic scrolls
     let lastCalculatedHeight = $state(0)
     let lastItemsLength = $state(0)
+    // Track last observed total height to compute precise deltas on item count changes
+    let lastTotalHeightObserved = $state(0)
 
     /**
      * CRITICAL: O(1) Reactive Total Height Calculation
@@ -620,6 +786,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 &&
@@ -661,34 +828,96 @@
                 const currentCalculatedItemHeight = heightManager.averageHeight
                 const currentHeight = height
                 const currentTotalHeight = totalHeight()
-                const maxScrollTop = Math.max(0, currentTotalHeight - currentHeight)
+                const prevTotalHeight =
+                    lastTotalHeightObserved ||
+                    currentTotalHeight - itemsAdded * currentCalculatedItemHeight
+                const prevMaxScrollTop = Math.max(0, prevTotalHeight - currentHeight)
+                const nextMaxScrollTop = Math.max(0, currentTotalHeight - currentHeight)
+                const deltaMax = nextMaxScrollTop - prevMaxScrollTop
+                log('[SVL] items-length-change:before', {
+                    instanceId,
+                    itemsAdded,
+                    lastItemsLength,
+                    currentItemsLength,
+                    currentScrollTop,
+                    prevTotalHeight,
+                    currentTotalHeight,
+                    prevMaxScrollTop,
+                    nextMaxScrollTop,
+                    deltaMax,
+                    averageItemHeight: currentCalculatedItemHeight
+                })
+
+                // Maintain visual position for ALL cases by advancing scrollTop by deltaMax.
+                // 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
+                    log('[SVL] items-length-change:applied', {
+                        instanceId,
+                        previousScrollTop: currentScrollTop,
+                        appliedScrollTop: newScrollTop,
+                        prevMaxScrollTop,
+                        nextMaxScrollTop,
+                        deltaMax
+                    })
 
-                // Check if user was at/near the bottom before items were added
-                const wasNearBottom =
-                    Math.abs(
-                        currentScrollTop -
-                            Math.max(
+                    // We are explicitly managing position; consider this a programmatic action.
+                    // Do not flip userHasScrolledAway here; it should reflect user intent only.
+
+                    // Reconcile on next frame in case measured heights adjust totals
+                    requestAnimationFrame(() => {
+                        const beforeReconcileScrollTop = heightManager.viewport.scrollTop
+                        const reconciledNextMax = Math.max(0, totalHeight() - height)
+                        const reconciledDeltaMaxChange = reconciledNextMax - nextMaxScrollTop
+                        // Desired position is to maintain distance-from-end; equivalently keep (max - scrollTop) constant.
+                        const desiredScrollTop = Math.max(
+                            0,
+                            Math.min(reconciledNextMax, newScrollTop + reconciledDeltaMaxChange)
+                        )
+                        // 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) >= 2) {
+                            const adjusted = Math.max(
                                 0,
-                                lastItemsLength * currentCalculatedItemHeight - currentHeight
+                                Math.min(reconciledNextMax, desiredRounded)
                             )
-                    ) <
-                    currentCalculatedItemHeight * 2
-
-                if (wasNearBottom || currentScrollTop === 0) {
-                    // User was at bottom, keep them at bottom after new items are added
-                    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
+                            heightManager.viewport.scrollTop = adjusted
+                            heightManager.scrollTop = adjusted
+                            log('[SVL] items-length-change:reconciled', {
+                                instanceId,
+                                beforeReconcileScrollTop,
+                                adjustedScrollTop: adjusted,
+                                reconciledNextMax,
+                                reconciledDeltaMaxChange,
+                                desiredScrollTop,
+                                desiredRounded,
+                                diffToDesired
+                            })
+                        } else {
+                            log('[SVL] items-length-change:reconciled-skip', {
+                                instanceId,
+                                beforeReconcileScrollTop,
+                                reconciledNextMax,
+                                reconciledDeltaMaxChange,
+                                desiredScrollTop,
+                                desiredRounded,
+                                diffToDesired
+                            })
+                        }
+                        programmaticScrollInProgress = false
                     })
-                }
+                })
             }
         }
 
         lastItemsLength = currentItemsLength
+        // Update last observed total height at the end of the effect
+        lastTotalHeightObserved = totalHeight()
     })
 
     // Update container height continuously to reflect layout changes that
@@ -804,35 +1033,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
+        })
     }
 
     /**

package/dist/SvelteVirtualList.svelte.d.ts

@@ -92,6 +92,26 @@ import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from
 declare function $$render<TItem = unknown>(): {
     props: SvelteVirtualListProps<TItem>;
     exports: {
+        /**
+             * 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);
+             * });
+             * ```
+             */ runInBatch: (fn: () => void) => void;
         /**
              * Scrolls the virtual list to the item at the given index.
              *
@@ -159,6 +179,26 @@ declare class __sveltets_Render<TItem = unknown> {
     slots(): ReturnType<typeof $$render<TItem>>['slots'];
     bindings(): "";
     exports(): {
+        /**
+             * 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);
+             * });
+             * ```
+             */ runInBatch: (fn: () => void) => void;
         /**
              * Scrolls the virtual list to the item at the given index.
              *

package/dist/reactive-list-manager/RecomputeScheduler.d.ts

@@ -1,13 +1,91 @@
+/**
+ * Scheduler that coalesces recompute requests to the next animation frame.
+ *
+ * This class provides efficient batching of recompute operations by scheduling
+ * them to run on the next animation frame in browser environments. In non-browser
+ * or jsdom environments, it falls back to setTimeout(0) for deterministic testing.
+ *
+ * Key features:
+ * - Coalesces multiple schedule() calls into a single recompute
+ * - Supports temporary blocking during critical sections
+ * - Handles nested block/unblock calls with depth tracking
+ * - Environment-aware: uses RAF in browsers, setTimeout in tests
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new RecomputeScheduler(() => {
+ *     console.log('Recomputing derived state');
+ * });
+ *
+ * // Multiple calls within the same frame are coalesced
+ * scheduler.schedule();
+ * scheduler.schedule();
+ * scheduler.schedule(); // Only one recompute will run
+ *
+ * // Block during critical sections
+ * scheduler.block();
+ * scheduler.schedule(); // Marked as pending, won't run yet
+ * scheduler.unblock();  // Runs immediately if pending
+ * ```
+ *
+ * @class
+ */
 export declare class RecomputeScheduler {
+    /** Callback function to execute on recompute. */
     private onRecompute;
+    /** Whether a recompute is currently scheduled. */
     private isScheduled;
+    /** Whether a recompute is pending due to blocking. */
     private isPending;
+    /** Current nesting depth of block() calls. */
     private blockDepth;
+    /** ID of the pending setTimeout (non-browser fallback). */
     private timeoutId;
+    /** ID of the pending requestAnimationFrame. */
     private rafId;
+    /**
+     * Creates a new RecomputeScheduler instance.
+     *
+     * @param {() => void} onRecompute - Callback function to execute when recompute runs.
+     */
     constructor(onRecompute: () => void);
+    /**
+     * Schedules a recompute for the next animation frame.
+     *
+     * If the scheduler is blocked, the request is marked as pending and will
+     * execute when unblocked. Multiple calls while a recompute is already
+     * scheduled are coalesced into a single execution.
+     *
+     * @returns {void}
+     */
     schedule: () => void;
+    /**
+     * Temporarily blocks recompute execution.
+     *
+     * Cancels any in-flight timers and marks any pending recompute request.
+     * Block calls can be nested; the scheduler remains blocked until all
+     * corresponding unblock() calls are made.
+     *
+     * @returns {void}
+     */
     block: () => void;
+    /**
+     * Unblocks the scheduler and runs pending recompute if any.
+     *
+     * Decrements the block depth counter. When the depth reaches zero and
+     * a recompute was pending, it executes immediately (synchronously).
+     * Guards against underflow if unblock is called without matching block.
+     *
+     * @returns {void}
+     */
     unblock: () => void;
+    /**
+     * Cancels any scheduled or pending recompute.
+     *
+     * Clears all timers (setTimeout and RAF) and resets the scheduled
+     * and pending flags. Does not affect the block depth.
+     *
+     * @returns {void}
+     */
     cancel: () => void;
 }

package/dist/reactive-list-manager/RecomputeScheduler.js

@@ -1,19 +1,65 @@
-// RecomputeScheduler
-// -------------------
-// Coalesces recompute requests to the next animation frame in the browser.
-// Falls back to setTimeout(0) in non-browser/jsdom to preserve deterministic tests.
-// Supports temporary blocking to delay recomputation during critical sections.
+/**
+ * Scheduler that coalesces recompute requests to the next animation frame.
+ *
+ * This class provides efficient batching of recompute operations by scheduling
+ * them to run on the next animation frame in browser environments. In non-browser
+ * or jsdom environments, it falls back to setTimeout(0) for deterministic testing.
+ *
+ * Key features:
+ * - Coalesces multiple schedule() calls into a single recompute
+ * - Supports temporary blocking during critical sections
+ * - Handles nested block/unblock calls with depth tracking
+ * - Environment-aware: uses RAF in browsers, setTimeout in tests
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new RecomputeScheduler(() => {
+ *     console.log('Recomputing derived state');
+ * });
+ *
+ * // Multiple calls within the same frame are coalesced
+ * scheduler.schedule();
+ * scheduler.schedule();
+ * scheduler.schedule(); // Only one recompute will run
+ *
+ * // Block during critical sections
+ * scheduler.block();
+ * scheduler.schedule(); // Marked as pending, won't run yet
+ * scheduler.unblock();  // Runs immediately if pending
+ * ```
+ *
+ * @class
+ */
 export class RecomputeScheduler {
+    /** Callback function to execute on recompute. */
     onRecompute;
+    /** Whether a recompute is currently scheduled. */
     isScheduled = false;
+    /** Whether a recompute is pending due to blocking. */
     isPending = false;
+    /** Current nesting depth of block() calls. */
     blockDepth = 0;
+    /** ID of the pending setTimeout (non-browser fallback). */
     timeoutId = null;
+    /** ID of the pending requestAnimationFrame. */
     rafId = null;
+    /**
+     * Creates a new RecomputeScheduler instance.
+     *
+     * @param {() => void} onRecompute - Callback function to execute when recompute runs.
+     */
     constructor(onRecompute) {
         this.onRecompute = onRecompute;
     }
-    // Request a recompute. If blocked, mark as pending; otherwise schedule for next frame.
+    /**
+     * Schedules a recompute for the next animation frame.
+     *
+     * If the scheduler is blocked, the request is marked as pending and will
+     * execute when unblocked. Multiple calls while a recompute is already
+     * scheduled are coalesced into a single execution.
+     *
+     * @returns {void}
+     */
     schedule = () => {
         if (this.blockDepth > 0) {
             this.isPending = true;
@@ -45,7 +91,15 @@ export class RecomputeScheduler {
             this.onRecompute();
         });
     };
-    // Temporarily block recomputes; any in-flight timers are canceled and a recompute is marked pending.
+    /**
+     * Temporarily blocks recompute execution.
+     *
+     * Cancels any in-flight timers and marks any pending recompute request.
+     * Block calls can be nested; the scheduler remains blocked until all
+     * corresponding unblock() calls are made.
+     *
+     * @returns {void}
+     */
     block = () => {
         this.blockDepth += 1;
         if (this.timeoutId) {
@@ -61,7 +115,15 @@ export class RecomputeScheduler {
             this.isPending = true;
         }
     };
-    // Unblock and run recompute immediately if one was pending.
+    /**
+     * Unblocks the scheduler and runs pending recompute if any.
+     *
+     * Decrements the block depth counter. When the depth reaches zero and
+     * a recompute was pending, it executes immediately (synchronously).
+     * Guards against underflow if unblock is called without matching block.
+     *
+     * @returns {void}
+     */
     unblock = () => {
         if (this.blockDepth === 0)
             return;
@@ -71,7 +133,14 @@ export class RecomputeScheduler {
             this.onRecompute();
         }
     };
-    // Cancel any scheduled recompute and clear pending state.
+    /**
+     * Cancels any scheduled or pending recompute.
+     *
+     * Clears all timers (setTimeout and RAF) and resets the scheduled
+     * and pending flags. Does not affect the block depth.
+     *
+     * @returns {void}
+     */
     cancel = () => {
         if (this.timeoutId) {
             clearTimeout(this.timeoutId);

package/dist/types.d.ts

@@ -63,6 +63,21 @@ export type SvelteVirtualListProps<TItem = any> = {
      * CSS class to apply to the scrollable viewport element.
      */
     viewportClass?: string;
+    /**
+     * Callback when more data is needed. Supports sync and async functions.
+     * Called when the user scrolls near the end of the list (based on loadMoreThreshold).
+     */
+    onLoadMore?: () => void | Promise<void>;
+    /**
+     * Number of items from the end to trigger onLoadMore.
+     * @default 20
+     */
+    loadMoreThreshold?: number;
+    /**
+     * Set to false when all data has been loaded to stop triggering onLoadMore.
+     * @default true
+     */
+    hasMore?: boolean;
 };
 /**
  * Debug information provided by the virtual list during rendering.

package/dist/utils/heightChangeDetection.d.ts

@@ -1,12 +1,37 @@
 /**
- * Utility functions for detecting significant height changes in virtual list items
+ * Utility functions for detecting significant height changes in virtual list items.
+ *
+ * @fileoverview Provides height change detection utilities for virtual list optimization.
+ * These functions help determine when item height changes are significant enough to
+ * trigger recalculations, preventing unnecessary updates for sub-pixel variations.
  */
 /**
- * Checks if a height change is significant enough to warrant marking an item as dirty
- * @param itemIndex - The index of the item
- * @param newHeight - The new measured height
- * @param heightCache - Existing height cache to compare against
- * @param marginOfError - Height difference threshold (default: 1px)
- * @returns true if the height change is significant
+ * Checks if a height change is significant enough to warrant marking an item as dirty.
+ *
+ * This function compares the new measured height against the cached height for an item
+ * and determines if the difference exceeds the specified margin of error. Items with
+ * no previous measurement are always considered significant.
+ *
+ * @param {number} itemIndex - The index of the item in the virtual list.
+ * @param {number} newHeight - The new measured height in pixels.
+ * @param {Record<number, number>} heightCache - Cache of previously measured item heights.
+ * @param {number} [marginOfError=1] - Height difference threshold in pixels. Changes
+ *     smaller than this value are considered insignificant.
+ * @returns {boolean} Returns true if the height change exceeds the margin of error
+ *     or if this is the first measurement for the item.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50 };
+ *
+ * // First-time measurement (no cache entry)
+ * isSignificantHeightChange(2, 45, heightCache); // true
+ *
+ * // Significant change (exceeds 1px threshold)
+ * isSignificantHeightChange(0, 45, heightCache); // true
+ *
+ * // Insignificant change (within 1px threshold)
+ * isSignificantHeightChange(0, 40.5, heightCache); // false
+ * ```
  */
 export declare const isSignificantHeightChange: (itemIndex: number, newHeight: number, heightCache: Record<number, number>, marginOfError?: number) => boolean;

package/dist/utils/heightChangeDetection.js

@@ -1,13 +1,38 @@
 /**
- * Utility functions for detecting significant height changes in virtual list items
+ * Utility functions for detecting significant height changes in virtual list items.
+ *
+ * @fileoverview Provides height change detection utilities for virtual list optimization.
+ * These functions help determine when item height changes are significant enough to
+ * trigger recalculations, preventing unnecessary updates for sub-pixel variations.
  */
 /**
- * Checks if a height change is significant enough to warrant marking an item as dirty
- * @param itemIndex - The index of the item
- * @param newHeight - The new measured height
- * @param heightCache - Existing height cache to compare against
- * @param marginOfError - Height difference threshold (default: 1px)
- * @returns true if the height change is significant
+ * Checks if a height change is significant enough to warrant marking an item as dirty.
+ *
+ * This function compares the new measured height against the cached height for an item
+ * and determines if the difference exceeds the specified margin of error. Items with
+ * no previous measurement are always considered significant.
+ *
+ * @param {number} itemIndex - The index of the item in the virtual list.
+ * @param {number} newHeight - The new measured height in pixels.
+ * @param {Record<number, number>} heightCache - Cache of previously measured item heights.
+ * @param {number} [marginOfError=1] - Height difference threshold in pixels. Changes
+ *     smaller than this value are considered insignificant.
+ * @returns {boolean} Returns true if the height change exceeds the margin of error
+ *     or if this is the first measurement for the item.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50 };
+ *
+ * // First-time measurement (no cache entry)
+ * isSignificantHeightChange(2, 45, heightCache); // true
+ *
+ * // Significant change (exceeds 1px threshold)
+ * isSignificantHeightChange(0, 45, heightCache); // true
+ *
+ * // Insignificant change (within 1px threshold)
+ * isSignificantHeightChange(0, 40.5, heightCache); // false
+ * ```
  */
 export const isSignificantHeightChange = (itemIndex, newHeight, heightCache, marginOfError = 1) => {
     const previousHeight = heightCache[itemIndex];

package/dist/utils/scrollCalculation.js

@@ -58,7 +58,15 @@ export const calculateScrollTarget = (params) => {
     }
 };
 /**
- * Calculates scroll target for bottom-to-top mode
+ * Calculates the target scroll position for bottom-to-top mode.
+ *
+ * In bottom-to-top mode, items are rendered from the bottom of the viewport upward,
+ * which requires different scroll calculations than the standard top-to-bottom mode.
+ * This function handles the coordinate system translation and alignment logic.
+ *
+ * @param {BottomToTopScrollParams} params - Parameters for scroll calculation.
+ * @returns {number | null} The target scroll position in pixels, or null if no
+ *     scroll is needed (item already visible with 'nearest' alignment).
  */
 const calculateBottomToTopScrollTarget = (params) => {
     const { align, targetIndex, itemsLength, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
@@ -106,7 +114,15 @@ const calculateBottomToTopScrollTarget = (params) => {
     return null;
 };
 /**
- * Calculates scroll target for top-to-bottom mode
+ * Calculates the target scroll position for top-to-bottom mode.
+ *
+ * This is the standard scroll mode where items are rendered from the top of the
+ * viewport downward. The function calculates the optimal scroll position based
+ * on the alignment option and current viewport state.
+ *
+ * @param {TopToBottomScrollParams} params - Parameters for scroll calculation.
+ * @returns {number | null} The target scroll position in pixels, or null if no
+ *     scroll is needed (item already visible with 'nearest' alignment).
  */
 const calculateTopToBottomScrollTarget = (params) => {
     const { align, targetIndex, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;

package/dist/utils/virtualList.d.ts

@@ -151,3 +151,31 @@ onComplete: () => void) => Promise<void>;
  * const offset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, 12345, blockSums);
  */
 export declare const getScrollOffsetForIndex: (heightCache: Record<number, number>, calculatedItemHeight: number, idx: number, blockSums?: number[], blockSize?: number) => number;
+/**
+ * Builds block prefix sums for heightCache to accelerate offset queries.
+ *
+ * This function precomputes cumulative height sums for blocks of items, enabling
+ * O(blockSize) offset calculations instead of O(n). The returned array contains
+ * the total height of all items up to and including each completed block.
+ *
+ * For example, with blockSize=1000:
+ * - Entry 0: sum of heights for items 0-999
+ * - Entry 1: sum of heights for items 0-1999
+ * - Entry 2: sum of heights for items 0-2999
+ *
+ * @param {Record<number, number>} heightCache - Cache of measured item heights.
+ * @param {number} calculatedItemHeight - Estimated height for unmeasured items.
+ * @param {number} totalItems - Total number of items in the list.
+ * @param {number} [blockSize=1000] - Number of items per block for memoization.
+ * @returns {number[]} Array of cumulative height sums for each completed block.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50, 2: 45 };
+ * const blockSums = buildBlockSums(heightCache, 40, 5000, 1000);
+ *
+ * // Use with getScrollOffsetForIndex for efficient lookups
+ * const offset = getScrollOffsetForIndex(heightCache, 40, 2500, blockSums);
+ * ```
+ */
+export declare const buildBlockSums: (heightCache: Record<number, number>, calculatedItemHeight: number, totalItems: number, blockSize?: number) => number[];

package/dist/utils/virtualList.js

@@ -115,7 +115,8 @@ export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart,
         const basicTransform = (totalItems - visibleEnd) * itemHeight;
         // When content is smaller than viewport, push to bottom
         const bottomOffset = Math.max(0, effectiveViewport - actualTotalHeight);
-        return basicTransform + bottomOffset;
+        // Snap to integer pixels to avoid subpixel oscillation
+        return Math.round(basicTransform + bottomOffset);
     }
     else {
         // For topToBottom, prefer precise offset using measured heights when available
@@ -123,7 +124,7 @@ export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart,
             const offset = getScrollOffsetForIndex(heightCache, itemHeight, visibleStart);
             return Math.max(0, Math.round(offset));
         }
-        return visibleStart * itemHeight;
+        return Math.round(visibleStart * itemHeight);
     }
 };
 /**
@@ -386,3 +387,46 @@ export const getScrollOffsetForIndex = (heightCache, calculatedItemHeight, idx,
     }
     return offset;
 };
+/**
+ * Builds block prefix sums for heightCache to accelerate offset queries.
+ *
+ * This function precomputes cumulative height sums for blocks of items, enabling
+ * O(blockSize) offset calculations instead of O(n). The returned array contains
+ * the total height of all items up to and including each completed block.
+ *
+ * For example, with blockSize=1000:
+ * - Entry 0: sum of heights for items 0-999
+ * - Entry 1: sum of heights for items 0-1999
+ * - Entry 2: sum of heights for items 0-2999
+ *
+ * @param {Record<number, number>} heightCache - Cache of measured item heights.
+ * @param {number} calculatedItemHeight - Estimated height for unmeasured items.
+ * @param {number} totalItems - Total number of items in the list.
+ * @param {number} [blockSize=1000] - Number of items per block for memoization.
+ * @returns {number[]} Array of cumulative height sums for each completed block.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50, 2: 45 };
+ * const blockSums = buildBlockSums(heightCache, 40, 5000, 1000);
+ *
+ * // Use with getScrollOffsetForIndex for efficient lookups
+ * const offset = getScrollOffsetForIndex(heightCache, 40, 2500, blockSums);
+ * ```
+ */
+export const buildBlockSums = (heightCache, calculatedItemHeight, totalItems, blockSize = 1000) => {
+    const blocks = Math.ceil(totalItems / blockSize);
+    const sums = new Array(Math.max(0, blocks - 1));
+    let running = 0;
+    for (let b = 0; b < blocks - 1; b++) {
+        const start = b * blockSize;
+        const end = start + blockSize;
+        for (let i = start; i < end; i++) {
+            const raw = heightCache[i];
+            const h = Number.isFinite(raw) && raw > 0 ? raw : calculatedItemHeight;
+            running += h;
+        }
+        sums[b] = running;
+    }
+    return sums;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.3.5",
+  "version": "0.3.8",
   "description": "A lightweight, high-performance virtual list component for Svelte 5 that renders large datasets with minimal memory usage. Features include dynamic height support, smooth scrolling, TypeScript support, and efficient DOM recycling. Ideal for infinite scrolling lists, data tables, chat interfaces, and any application requiring the rendering of thousands of items without compromising performance. Zero dependencies and fully customizable.",
   "keywords": [
     "svelte",
@@ -59,51 +59,51 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@eslint/compat": "^1.4.0",
-    "@eslint/js": "^9.37.0",
-    "@faker-js/faker": "^10.0.0",
-    "@playwright/test": "^1.56.0",
-    "@sveltejs/adapter-auto": "^6.1.1",
-    "@sveltejs/kit": "^2.46.4",
-    "@sveltejs/package": "^2.5.4",
-    "@sveltejs/vite-plugin-svelte": "^6.2.1",
-    "@tailwindcss/vite": "^4.1.14",
+    "@eslint/compat": "^2.0.1",
+    "@eslint/js": "^9.39.2",
+    "@faker-js/faker": "^10.2.0",
+    "@playwright/test": "^1.58.0",
+    "@sveltejs/adapter-auto": "^7.0.0",
+    "@sveltejs/kit": "^2.50.1",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@tailwindcss/vite": "^4.1.18",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/svelte": "^5.2.8",
+    "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^24.7.1",
-    "@typescript-eslint/eslint-plugin": "^8.46.0",
-    "@typescript-eslint/parser": "^8.46.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "concurrently": "^9.2.1",
-    "eslint": "^9.37.0",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-svelte": "^3.12.4",
-    "eslint-plugin-unused-imports": "^4.2.0",
-    "globals": "^16.4.0",
+    "eslint-plugin-svelte": "^3.14.0",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "globals": "^17.2.0",
     "husky": "^9.1.7",
-    "jsdom": "^27.0.0",
-    "prettier": "^3.6.2",
+    "jsdom": "^27.4.0",
+    "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-sort-json": "^4.1.1",
-    "prettier-plugin-svelte": "^3.4.0",
-    "prettier-plugin-tailwindcss": "^0.6.14",
-    "publint": "^0.3.14",
-    "svelte": "^5.39.11",
-    "svelte-check": "^4.3.3",
-    "tailwindcss": "^4.1.14",
+    "prettier-plugin-sort-json": "^4.2.0",
+    "prettier-plugin-svelte": "^3.4.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "publint": "^0.3.17",
+    "svelte": "^5.48.5",
+    "svelte-check": "^4.3.5",
+    "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.0",
-    "vite": "^7.1.9",
-    "vitest": "^3.2.4"
+    "typescript-eslint": "^8.54.0",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "volta": {
-    "node": "22.18.0"
+    "node": "24.13.0"
   },
   "publishConfig": {
     "access": "public"
@@ -123,7 +123,7 @@
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "dev": "vite dev",
-    "dev:all": "concurrently -k -n pkg,docs,sitemap -c green,cyan,magenta \"pnpm -w -r --filter @humanspeak/svelte-virtual-list run dev:pkg\" \"pnpm --filter docs run dev\" \"pnpm --filter docs run sitemap:watch\"",
+    "dev:all": "concurrently -k -n pkg,docs,sitemap -c green,cyan,magenta \"pnpm -w -r --filter @humanspeak/svelte-virtual-list run dev\" \"pnpm --filter docs run dev\" \"pnpm --filter docs run sitemap:watch\"",
     "dev:pkg": "svelte-kit sync && svelte-package --watch",
     "format": "prettier --write .",
     "lint": "prettier --check . && eslint .",
@@ -138,6 +138,7 @@
     "test:e2e:report": "playwright show-report",
     "test:e2e:ui": "playwright test --ui",
     "test:only": "vitest run --",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest --"
   }
 }