@humanspeak/svelte-virtual-list 0.3.8 → 0.3.10

package/dist/SvelteVirtualList.svelte

@@ -163,9 +163,9 @@
     import { createRafScheduler } from './utils/raf.js'
     import { isSignificantHeightChange } from './utils/heightChangeDetection.js'
     import {
-        calculateScrollPosition,
         calculateTransformY,
         calculateVisibleRange,
+        clampValue,
         updateHeightAndScroll as utilsUpdateHeightAndScroll,
         getScrollOffsetForIndex,
         buildBlockSums
@@ -290,23 +290,16 @@
             Math.max(0, lastAnchorIndex),
             blockSums
         )
-        const maxScrollTop = Math.max(0, totalHeight() - (height || 0))
+        const maxScrollTop = clampValue(totalHeight() - (height || 0), 0, Infinity)
         let targetTop: number
         if (mode === 'bottomToTop') {
-            const distanceFromStart = Math.max(0, offsetToIndex + lastAnchorOffset)
-            targetTop = Math.max(
-                0,
-                Math.min(maxScrollTop, Math.round(maxScrollTop - distanceFromStart))
-            )
+            const distanceFromStart = clampValue(offsetToIndex + lastAnchorOffset, 0, Infinity)
+            targetTop = clampValue(Math.round(maxScrollTop - distanceFromStart), 0, maxScrollTop)
         } else {
-            targetTop = Math.max(
-                0,
-                Math.min(maxScrollTop, Math.round(offsetToIndex + lastAnchorOffset))
-            )
+            targetTop = clampValue(Math.round(offsetToIndex + lastAnchorOffset), 0, maxScrollTop)
         }
         if (Math.abs(heightManager.viewport.scrollTop - targetTop) >= 2) {
-            heightManager.viewport.scrollTop = targetTop
-            heightManager.scrollTop = targetTop
+            syncScrollTop(targetTop)
         }
         pendingAnchorReconcile = false
     }
@@ -359,6 +352,8 @@
     let dirtyItemsCount = $state(0) // Reactive count of dirty items
     // Fallback measurement used only when height has not been established yet
     let measuredFallbackHeight = $state(0)
+    // Scroll delta threshold optimization - track last scroll position used for range calculation
+    let lastProcessedScrollTop = $state(0)
 
     let prevVisibleRange = $state<SvelteVirtualListPreviousVisibleRange | null>(null)
     let prevHeight = $state<number>(0)
@@ -387,6 +382,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)
 
@@ -508,8 +520,7 @@
             // Step 1: Scroll to approximate position to ensure Item 0 gets rendered in virtual viewport
             const approximateScrollTop = Math.max(0, totalHeight() - height)
             log('[SVL] b2t-correction-approx', { approximateScrollTop })
-            heightManager.viewport.scrollTop = approximateScrollTop
-            heightManager.scrollTop = approximateScrollTop
+            syncScrollTop(approximateScrollTop)
 
             // Step 2: Use native scrollIntoView for precise bottom-edge positioning after DOM updates
             tick().then(() => {
@@ -525,16 +536,13 @@
                         Math.abs(contRect.y + contRect.height - (itemRect.y + itemRect.height)) <=
                         tol
                     if (!aligned) {
-                        // 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
-                        })
-                        log('[SVL] b2t-correction-native', {
-                            containerBottom: contRect.y + contRect.height,
-                            itemBottom: itemRect.y + itemRect.height
-                        })
+                        // Use manual scrollTop instead of scrollIntoView to prevent parent scroll
+                        // (scrollIntoView scrolls all ancestor containers, not just the viewport)
+                        // Note: `container: 'nearest'` option could replace this once browser support improves
+                        const currentScrollTop = heightManager.viewport.scrollTop
+                        const offset = itemRect.bottom - contRect.bottom
+                        heightManager.viewport.scrollTop = currentScrollTop + offset
+                        log('[SVL] b2t-correction-manual', { offset })
                     }
                     // Sync our internal scroll state with actual DOM position
                     heightManager.scrollTop = heightManager.viewport.scrollTop
@@ -572,13 +580,12 @@
             }
         }
         if (Math.abs(heightChangeAboveViewport) > 2) {
-            const newScrollTop = Math.min(
-                maxScrollTop,
-                Math.max(0, currentScrollTop + heightChangeAboveViewport)
+            const newScrollTop = clampValue(
+                currentScrollTop + heightChangeAboveViewport,
+                0,
+                maxScrollTop
             )
-
-            heightManager.viewport.scrollTop = newScrollTop
-            heightManager.scrollTop = newScrollTop
+            syncScrollTop(newScrollTop)
         }
     }
 
@@ -613,6 +620,8 @@
     // 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
@@ -667,11 +676,12 @@
                         const isAtBottom = Math.abs(currentScrollTop - maxScrollTop) <= tolerance
                         if (isAtBottom) {
                             // Adjust scrollTop by total height delta to hold bottom anchor
-                            const adjusted = Math.round(
-                                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)
                         }
                     }
                 }
@@ -703,6 +713,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
@@ -794,9 +807,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
@@ -852,10 +863,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,
@@ -871,23 +884,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) >= 2) {
-                            const adjusted = Math.max(
-                                0,
-                                Math.min(reconciledNextMax, desiredRounded)
-                            )
-                            heightManager.viewport.scrollTop = adjusted
-                            heightManager.scrollTop = adjusted
+                            const adjusted = clampValue(desiredRounded, 0, reconciledNextMax)
+                            syncScrollTop(adjusted)
                             log('[SVL] items-length-change:reconciled', {
                                 instanceId,
                                 beforeReconcileScrollTop,
@@ -963,35 +973,37 @@
         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
         }
 
+        // Scroll delta threshold optimization: skip recalculation if scroll delta is less than
+        // half the average item height and we have a cached range. This reduces unnecessary
+        // calculations during smooth scrolling.
+        // Note: Only applied in topToBottom mode - bottomToTop has complex scroll correction
+        // logic that requires precise visible range calculations.
+        // Note: We use lastProcessedScrollTop read-only here; it's updated in the scroll handler
+        if (mode === 'topToBottom') {
+            const scrollDelta = Math.abs(heightManager.scrollTop - lastProcessedScrollTop)
+            const threshold = heightManager.averageHeight * 0.5
+            if (lastVisibleRange && scrollDelta < threshold && scrollDelta > 0) {
+                // Reuse cached range for small scroll movements
+                return lastVisibleRange
+            }
+        }
+
         lastVisibleRange = calculateVisibleRange(
             heightManager.scrollTop,
             viewportHeight,
@@ -1009,6 +1021,40 @@
         return lastVisibleRange
     })
 
+    /**
+     * Computed content height for the virtual list.
+     * Uses the maximum of container height and total content height to ensure
+     * proper scrolling behavior.
+     */
+    const contentHeight = $derived(() => Math.max(height, totalHeight()))
+
+    /**
+     * Computed transform Y value for positioning the visible items.
+     * Extracted from inline IIFE for better performance and readability.
+     */
+    const transformY = $derived(() => {
+        const viewportHeight = height || measuredFallbackHeight || 0
+        const visibleRange = visibleItems()
+
+        // Avoid synchronous DOM reads here; fall back once if height is 0
+        const effectiveHeight = viewportHeight === 0 ? 400 : viewportHeight
+
+        // Use precise offset for topToBottom using measured heights when available
+        return Math.round(
+            calculateTransformY(
+                mode,
+                items.length,
+                visibleRange.end,
+                visibleRange.start,
+                heightManager.averageHeight,
+                effectiveHeight,
+                totalHeight(),
+                heightManager.getHeightCache(),
+                measuredFallbackHeight
+            )
+        )
+    })
+
     /**
      * Handles scroll events in the viewport using requestAnimationFrame for performance.
      *
@@ -1059,6 +1105,13 @@
             }
             lastScrollTopSnapshot = current
             heightManager.scrollTop = current
+            // Update last processed scroll position for delta threshold optimization
+            // Only update when we actually process a scroll (i.e., recalculate visible range)
+            const scrollDelta = Math.abs(current - lastProcessedScrollTop)
+            const threshold = heightManager.averageHeight * 0.5
+            if (scrollDelta >= threshold || lastVisibleRange === null) {
+                lastProcessedScrollTop = current
+            }
             updateDebugTailDistance()
             if (anchorModeEnabled) {
                 captureAnchor()
@@ -1099,7 +1152,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(() => {
@@ -1107,11 +1161,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()
@@ -1121,32 +1171,52 @@
                         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' })
+
+                                    if (el && !userHasScrolled) {
+                                        // Use manual scrollTop instead of scrollIntoView to prevent parent scroll
+                                        // (scrollIntoView scrolls all ancestor containers, not just the viewport)
+                                        // Note: `container: 'nearest'` option could replace this once browser support improves
+                                        const viewportRect =
+                                            heightManager.viewport.getBoundingClientRect()
+                                        const elRect = el.getBoundingClientRect()
+                                        const offset = elRect.bottom - viewportRect.bottom
+                                        heightManager.viewport.scrollTop += offset
                                         heightManager.scrollTop = heightManager.viewport.scrollTop
-                                        log('b2t-init-native-fallback', {
-                                            containerBottom: cont.y + cont.height,
-                                            itemBottom: r.y + r.height
-                                        })
+                                    } 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)
@@ -1371,7 +1441,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)
             }
         }
 
@@ -1520,38 +1590,14 @@
             id="virtual-list-content"
             {...testId ? { 'data-testid': `${testId}-content` } : {}}
             class={contentClass ?? 'virtual-list-content'}
-            style:height="{(() => Math.max(height, totalHeight()))()}px"
+            style:height="{contentHeight()}px"
         >
             <!-- Items container is translated to show correct items -->
             <div
                 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()
-
-                    // Avoid synchronous DOM reads here; fall back once if height is 0
-                    const effectiveHeight = viewportHeight === 0 ? 400 : viewportHeight
-
-                    // Use precise offset for topToBottom using measured heights when available
-                    const transform = Math.round(
-                        calculateTransformY(
-                            mode,
-                            items.length,
-                            visibleRange.end,
-                            visibleRange.start,
-                            heightManager.averageHeight,
-                            effectiveHeight,
-                            totalHeight(),
-                            heightManager.getHeightCache(),
-                            measuredFallbackHeight
-                        )
-                    )
-
-                    return transform
-                })()}px)"
+                style:transform="translateY({transformY()}px)"
             >
                 {#each displayItems() as currentItemWithIndex, i (currentItemWithIndex.originalIndex)}
                     <!-- Only debug when visible range or average height changes -->

package/dist/index.d.ts

@@ -3,4 +3,6 @@ import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualLi
 export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions };
 export { ReactiveListManager } from './reactive-list-manager/index.js';
 export type { ListManagerConfig } from './reactive-list-manager/index.js';
+export { formatBytes, getCurrentFps, getMemoryUsage, isPerfEnabled, measureAsync, measureSync, perfMetrics, recordDuration, startFpsTracking, startMeasure, stopFpsTracking } from './utils/perfMetrics.js';
+export type { MetricEntry, MetricName, MetricStats, PerfMetrics } from './utils/perfMetrics.js';
 export default SvelteVirtualList;

package/dist/index.js

@@ -1,4 +1,6 @@
 import SvelteVirtualList from './SvelteVirtualList.svelte';
 // Re-export renamed manager from existing package location to avoid churn
 export { ReactiveListManager } from './reactive-list-manager/index.js';
+// Re-export performance metrics utilities
+export { formatBytes, getCurrentFps, getMemoryUsage, isPerfEnabled, measureAsync, measureSync, perfMetrics, recordDuration, startFpsTracking, startMeasure, stopFpsTracking } from './utils/perfMetrics.js';
 export default SvelteVirtualList;

package/dist/reactive-list-manager/ReactiveListManager.svelte.d.ts

@@ -46,6 +46,9 @@ export declare class ReactiveListManager {
     private _mutationObserver;
     private _heightCache;
     private _scheduler;
+    private _blockSums;
+    private _blockSumsValid;
+    private _blockSize;
     private recomputeDerivedHeights;
     private recomputeIsReady;
     private scheduleRecomputeDerivedHeights;
@@ -157,6 +160,30 @@ export declare class ReactiveListManager {
      * Read-only view of measured heights cache
      */
     getHeightCache(): Readonly<Record<number, number>>;
+    /**
+     * Invalidate block sums from a given index onwards.
+     * Call this when item heights change to ensure block sums are recalculated.
+     *
+     * @param index - The index from which to invalidate block sums
+     */
+    invalidateBlockSumsFrom(index: number): void;
+    /**
+     * Get the block sums array, rebuilding if necessary.
+     * Block sums enable O(blockSize) offset calculations instead of O(n).
+     *
+     * Each entry contains the cumulative height sum up to and including that block.
+     * For example, with blockSize=1000:
+     * - Entry 0: sum of heights for items 0-999
+     * - Entry 1: sum of heights for items 0-1999
+     *
+     * @returns Array of cumulative block sums
+     */
+    getBlockSums(): number[];
+    /**
+     * Build block prefix sums for efficient offset calculations.
+     * Uses the same algorithm as the utility function but leverages internal state.
+     */
+    private buildBlockSums;
     /**
      * Create a new ReactiveListManager instance
      *

package/dist/reactive-list-manager/ReactiveListManager.svelte.js

@@ -49,6 +49,10 @@ export class ReactiveListManager {
     _heightCache = {};
     // Recompute scheduling
     _scheduler = new RecomputeScheduler(() => this.recomputeDerivedHeights());
+    // Block sum caching for O(blockSize) offset calculations instead of O(n)
+    _blockSums = [];
+    _blockSumsValid = false;
+    _blockSize = 1000;
     recomputeDerivedHeights() {
         const average = this._measuredCount > 0
             ? this._totalMeasuredHeight / this._measuredCount
@@ -343,6 +347,57 @@ export class ReactiveListManager {
     getHeightCache() {
         return this._heightCache;
     }
+    /**
+     * Invalidate block sums from a given index onwards.
+     * Call this when item heights change to ensure block sums are recalculated.
+     *
+     * @param index - The index from which to invalidate block sums
+     */
+    invalidateBlockSumsFrom(index) {
+        const blockIndex = Math.floor(index / this._blockSize);
+        // Truncate to remove invalidated blocks
+        if (blockIndex < this._blockSums.length) {
+            this._blockSums.length = blockIndex;
+        }
+        this._blockSumsValid = false;
+    }
+    /**
+     * Get the block sums array, rebuilding if necessary.
+     * Block sums enable O(blockSize) offset calculations instead of O(n).
+     *
+     * Each entry contains the cumulative height sum up to and including that block.
+     * For example, with blockSize=1000:
+     * - Entry 0: sum of heights for items 0-999
+     * - Entry 1: sum of heights for items 0-1999
+     *
+     * @returns Array of cumulative block sums
+     */
+    getBlockSums() {
+        if (!this._blockSumsValid || this._blockSums.length === 0) {
+            this._blockSums = this.buildBlockSums();
+            this._blockSumsValid = true;
+        }
+        return this._blockSums;
+    }
+    /**
+     * Build block prefix sums for efficient offset calculations.
+     * Uses the same algorithm as the utility function but leverages internal state.
+     */
+    buildBlockSums() {
+        const blocks = Math.ceil(this._itemLength / this._blockSize);
+        const sums = new Array(Math.max(0, blocks - 1));
+        let running = 0;
+        for (let b = 0; b < blocks - 1; b++) {
+            const start = b * this._blockSize;
+            const end = start + this._blockSize;
+            for (let i = start; i < end; i++) {
+                const height = this._heightCache[i];
+                running += Number.isFinite(height) && height > 0 ? height : this._averageHeight;
+            }
+            sums[b] = running;
+        }
+        return sums;
+    }
     /**
      * Create a new ReactiveListManager instance
      *
@@ -372,8 +427,13 @@ export class ReactiveListManager {
         // Batch calculate changes to trigger reactivity only once
         let heightDelta = 0;
         let countDelta = 0;
+        let minChangedIndex = Infinity;
         for (const change of dirtyResults) {
             const { index, oldHeight, newHeight } = change;
+            // Track minimum changed index for block sum invalidation
+            if (index < minChangedIndex) {
+                minChangedIndex = index;
+            }
             // Remove old contribution if it existed
             if (oldHeight !== undefined) {
                 heightDelta -= oldHeight;
@@ -394,6 +454,10 @@ export class ReactiveListManager {
                 this._measuredFlags[index] = 1;
             }
         }
+        // Invalidate block sums from the minimum changed index
+        if (minChangedIndex < Infinity) {
+            this.invalidateBlockSumsFrom(minChangedIndex);
+        }
         // IDK... no one can explain it to me,.. but its here like this... it cannot be:
         //  if (heightDelta === 0 && countDelta === 0) return
         const isJsdom = typeof navigator !== 'undefined' && typeof navigator.userAgent === 'string'
@@ -421,6 +485,9 @@ export class ReactiveListManager {
     updateItemLength(newLength) {
         this._itemLength = newLength;
         this._measuredFlags = new Uint8Array(Math.max(0, newLength));
+        // Reset block sums since length changed
+        this._blockSums = [];
+        this._blockSumsValid = false;
         // Immediate recompute so new items become visible without delay
         this.recomputeDerivedHeights();
     }
@@ -450,6 +517,8 @@ export class ReactiveListManager {
         if (Number.isFinite(height) && height > 0) {
             this._heightCache[index] = height;
             this._totalMeasuredHeight += height;
+            // Invalidate block sums from this index
+            this.invalidateBlockSumsFrom(index);
             this.scheduleRecomputeDerivedHeights();
         }
     }
@@ -462,6 +531,9 @@ export class ReactiveListManager {
         this._totalMeasuredHeight = 0;
         this._measuredCount = 0;
         this._measuredFlags = this._itemLength > 0 ? new Uint8Array(this._itemLength) : null;
+        // Reset block sums
+        this._blockSums = [];
+        this._blockSumsValid = false;
         // Note: Don't reset _itemLength, _itemHeight as they represent configuration, not measured state
         this.scheduleRecomputeDerivedHeights();
     }