@humanspeak/svelte-virtual-list 0.2.5 → 0.2.6-beta.1

package/dist/SvelteVirtualList.svelte.d.ts

@@ -76,53 +76,75 @@
      * - Height caching and estimation system
      * - Progressive size adjustment system
      */
-import type { SvelteVirtualListProps } from './types.js';
+import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from './types.js';
 /**
- * A high-performance virtualized list component that efficiently renders large datasets
- * by only mounting DOM nodes for visible items and a small buffer. Optimized for handling
- * lists of 10k+ items through chunked processing and progressive initialization.
+ * SvelteVirtualList
  *
- * Props:
- * - `items` - Array of items to render
- * - `defaultEstimatedItemHeight` - Initial height estimate for items (default: 40px)
- * - `mode` - Scroll direction: 'topToBottom' or 'bottomToTop' (default: 'topToBottom')
- * - `debug` - Enable debug logging (default: false)
- * - `bufferSize` - Number of items to render outside visible area (default: 20)
- * - `containerClass` - Custom class for container element
- * - `viewportClass` - Custom class for viewport element
- * - `contentClass` - Custom class for content wrapper
- * - `itemsClass` - Custom class for items wrapper
- * - `debugFunction` - Custom debug logging function
- * - `testId` - Base test ID for component elements
+ * A high-performance, memory-efficient virtualized list component for Svelte 5.
+ * Renders only visible items plus a buffer, supporting dynamic item heights,
+ * bi-directional (top-to-bottom and bottom-to-top) scrolling, and programmatic control.
  *
- * Usage:
+ * =============================
+ * ==  Key Features           ==
+ * =============================
+ * - Dynamic item height support (no fixed height required)
+ * - Top-to-bottom and bottom-to-top (chat-style) scrolling
+ * - Programmatic scrolling with flexible alignment (top, bottom, auto)
+ * - Smooth scrolling and buffer size configuration
+ * - SSR compatible and hydration-friendly
+ * - TypeScript and Svelte 5 runes/snippets support
+ * - Customizable styling via class props
+ * - Debug mode for development and testing
+ * - Optimized for large lists (10k+ items)
+ * - Comprehensive test coverage (unit and E2E)
+ *
+ * =============================
+ * ==  Usage Example          ==
+ * =============================
  * ```svelte
  * <SvelteVirtualList
  *     items={data}
- *     defaultEstimatedItemHeight={40}
- *     mode="topToBottom"
+ *     mode="bottomToTop"
+ *     bind:this={listRef}
  * >
- *     {#snippet renderItem(item, index)}
- *         <div class="item">{item.text}</div>
+ *     {#snippet renderItem(item)}
+ *         <div>{item.text}</div>
  *     {/snippet}
  * </SvelteVirtualList>
  * ```
  *
- * Features:
- * - Dynamic height calculation
- * - Bidirectional scrolling
- * - Configurable buffer size
- * - Debug mode
- * - Custom styling
- * - Progressive initialization for large datasets
- * - Memory-optimized for 10k+ items
- * - Chunked processing for smooth performance
- * - Progress tracking during initialization
+ * =============================
+ * ==  Architecture Notes      ==
+ * =============================
+ * - Uses a four-layer DOM structure for optimal performance
+ * - Only visible items + buffer are mounted in the DOM
+ * - Height caching and estimation for dynamic content
+ * - Handles resize events and dynamic content changes
+ * - Supports chunked initialization for very large lists
+ * - All scrolling logic is centralized in the scroll() method
+ * - Bi-directional support: mode="topToBottom" or "bottomToTop"
+ * - Designed for extensibility and easy debugging
+ *
+ * =============================
+ * ==  For Contributors        ==
+ * =============================
+ * - Please keep all scrolling logic in the scroll() method
+ * - Add new features behind feature flags or as optional props
+ * - Write tests for all new features (see /test and /tests/scroll)
+ * - Use TypeScript and Svelte 5 runes for all new code
+ * - Document all exported functions and props with JSDoc
+ * - See README.md for API and usage details
+ * - For questions, open an issue or discussion on GitHub
+ *
+ * MIT License © Humanspeak, Inc.
  */
 declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {
     /**
          * Scrolls the virtual list to the item at the given index.
          *
+         * @deprecated This function is deprecated and will be removed in a future version.
+         * Use the new scroll method from the component instance instead.
+         *
          * @function scrollToIndex
          * @param index The index of the item to scroll to.
          * @param smoothScroll (default: true) Whether to use smooth scrolling.
@@ -148,6 +170,31 @@ declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListPro
          * @returns {void}
          * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
          */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+    /**
+         * Scrolls the virtual list to the item at the given index using a type-based options approach.
+         *
+         * @function scroll
+         * @param options Configuration options for scrolling behavior.
+         *
+         * @example
+         * // Svelte usage:
+         * // In your <script> block:
+         *   import SvelteVirtualList from './index.js';
+         *   let virtualList;
+         *   const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+         *
+         * <button onclick={() => virtualList.scroll({ index: 5000 })}>
+         *   Scroll to 5000
+         * </button>
+         * <SvelteVirtualList {items} bind:this={virtualList}>
+         *   {#snippet renderItem(item)}
+         *     <div>{item.text}</div>
+         *   {/snippet}
+         * </SvelteVirtualList>
+         *
+         * @returns {void}
+         * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+         */ scroll: (options: SvelteVirtualListScrollOptions) => void;
 }, "">;
 type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
 export default SvelteVirtualList;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import SvelteVirtualList from './SvelteVirtualList.svelte';
-import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps } from './types.js';
+import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions } from './types.js';
 export default SvelteVirtualList;
-export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps };
+export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions };

package/dist/types.d.ts

@@ -82,3 +82,33 @@ export type SvelteVirtualListDebugInfo = {
     processedItems: number;
     averageItemHeight: number;
 };
+/**
+ * Alignment options for programmatic scrolling.
+ */
+export type SvelteVirtualListScrollAlign = 'auto' | 'top' | 'bottom' | 'nearest';
+/**
+ * Options for scrolling to a specific index in the virtual list.
+ */
+export interface SvelteVirtualListScrollOptions {
+    /** The index of the item to scroll to. */
+    index: number;
+    /** Whether to use smooth scrolling animation. Default: true */
+    smoothScroll?: boolean;
+    /** Whether to throw an error if the index is out of bounds. Default: true */
+    shouldThrowOnBounds?: boolean;
+    /** Alignment for the scrolled item: 'auto', 'top', or 'bottom'. Default: 'auto' */
+    align?: SvelteVirtualListScrollAlign;
+}
+/**
+ * Default options for scrolling.
+ */
+export declare const DEFAULT_SCROLL_OPTIONS: Partial<SvelteVirtualListScrollOptions>;
+export type SvelteVirtualListHeightCacheItem = {
+    currentHeight: number;
+    dirty: boolean;
+};
+export type SvelteVirtualListHeightCache = Record<number, SvelteVirtualListHeightCacheItem>;
+export type SvelteVirtualListPreviousVisibleRange = {
+    start: number;
+    end: number;
+};

package/dist/types.js

@@ -1 +1,8 @@
-export {};
+/**
+ * Default options for scrolling.
+ */
+export const DEFAULT_SCROLL_OPTIONS = {
+    smoothScroll: true,
+    shouldThrowOnBounds: true,
+    align: 'auto'
+};

package/dist/utils/heightCalculation.d.ts

@@ -1,24 +1,23 @@
-import type { HeightCache } from './types.js';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
  * This function optimizes performance by:
  * - Debouncing calculations to prevent excessive DOM reads (200ms default)
- * - Caching item heights to minimize recalculations
+ * - Caching item heights with dirty tracking to minimize recalculations
  * - Only updating when significant changes are detected (>1px difference)
  * - Early returns to prevent unnecessary processing
  *
  * Implementation details:
  * - Uses a debounce timeout to batch height calculations
  * - Tracks calculation state to prevent concurrent updates
- * - Caches heights in heightCache for reuse
+ * - Caches heights in heightCache with currentHeight and dirty flags for reuse
  * - Validates browser environment and calculation state
  * - Checks for meaningful height changes before updates
  *
  * State interactions:
  * - Updates calculatedItemHeight when significant changes occur
  * - Updates lastMeasuredIndex to track progress
- * - Modifies heightCache to store measured heights
+ * - Modifies heightCache to store measured heights with dirty tracking
  * - Uses isCalculatingHeight flag for concurrency control
  *
  * Guard clauses:
@@ -54,13 +53,14 @@ import type { HeightCache } from './types.js';
  * - Enhanced debounce timing precision
  * - Added proper cleanup for timeouts
  * - Documented all edge cases and failure modes
+ * - Updated to work with new HeightCache structure with dirty tracking
  *
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
  * @param visibleItemsGetter - Function to get current visible range
  * @param itemElements - Array of DOM elements to measure
- * @param heightCache - Cache of previously measured heights
+ * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
  * @param calculatedItemHeight - Current average height
  * @param onUpdate - Callback for height updates
@@ -70,8 +70,9 @@ import type { HeightCache } from './types.js';
 export declare const calculateAverageHeightDebounced: (isCalculatingHeight: boolean, heightUpdateTimeout: ReturnType<typeof setTimeout> | null, visibleItemsGetter: () => {
     start: number;
     end: number;
-}, itemElements: HTMLElement[], heightCache: HeightCache, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
+}, itemElements: HTMLElement[], heightCache: Record<number, number>, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
     newHeight: number;
     newLastMeasuredIndex: number;
-    updatedHeightCache: HeightCache;
-}) => void, debounceTime?: number) => NodeJS.Timeout | null;
+    updatedHeightCache: Record<number, number>;
+    clearedDirtyItems: Set<number>;
+}) => void, debounceTime: number, dirtyItems: Set<number>) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -1,25 +1,25 @@
-import { BROWSER } from 'esm-env';
 import { calculateAverageHeight } from './virtualList.js';
+import { BROWSER } from 'esm-env';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
  * This function optimizes performance by:
  * - Debouncing calculations to prevent excessive DOM reads (200ms default)
- * - Caching item heights to minimize recalculations
+ * - Caching item heights with dirty tracking to minimize recalculations
  * - Only updating when significant changes are detected (>1px difference)
  * - Early returns to prevent unnecessary processing
  *
  * Implementation details:
  * - Uses a debounce timeout to batch height calculations
  * - Tracks calculation state to prevent concurrent updates
- * - Caches heights in heightCache for reuse
+ * - Caches heights in heightCache with currentHeight and dirty flags for reuse
  * - Validates browser environment and calculation state
  * - Checks for meaningful height changes before updates
  *
  * State interactions:
  * - Updates calculatedItemHeight when significant changes occur
  * - Updates lastMeasuredIndex to track progress
- * - Modifies heightCache to store measured heights
+ * - Modifies heightCache to store measured heights with dirty tracking
  * - Uses isCalculatingHeight flag for concurrency control
  *
  * Guard clauses:
@@ -55,13 +55,14 @@ import { calculateAverageHeight } from './virtualList.js';
  * - Enhanced debounce timing precision
  * - Added proper cleanup for timeouts
  * - Documented all edge cases and failure modes
+ * - Updated to work with new HeightCache structure with dirty tracking
  *
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
  * @param visibleItemsGetter - Function to get current visible range
  * @param itemElements - Array of DOM elements to measure
- * @param heightCache - Cache of previously measured heights
+ * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
  * @param calculatedItemHeight - Current average height
  * @param onUpdate - Callback for height updates
@@ -70,20 +71,23 @@ import { calculateAverageHeight } from './virtualList.js';
  */
 export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
 /* trunk-ignore(eslint/no-unused-vars) */
-onUpdate, debounceTime = 200) => {
-    if (!BROWSER || isCalculatingHeight || heightUpdateTimeout)
+onUpdate, debounceTime, dirtyItems) => {
+    if (!BROWSER || isCalculatingHeight)
         return null;
     const visibleRange = visibleItemsGetter();
     const currentIndex = visibleRange.start;
     if (currentIndex === lastMeasuredIndex)
         return null;
+    if (heightUpdateTimeout)
+        clearTimeout(heightUpdateTimeout);
     return setTimeout(() => {
-        const { newHeight, newLastMeasuredIndex, updatedHeightCache } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight);
-        if (Math.abs(newHeight - calculatedItemHeight) > 1) {
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems);
+        if (Math.abs(newHeight - calculatedItemHeight) > 1 || dirtyItems.size > 0) {
             onUpdate({
                 newHeight,
                 newLastMeasuredIndex,
-                updatedHeightCache
+                updatedHeightCache,
+                clearedDirtyItems
             });
         }
     }, debounceTime);

package/dist/utils/types.d.ts

@@ -39,9 +39,3 @@ export type VirtualListSetters = {
     setScrollTop: (scrollTop: number) => void;
     setInitialized: (initialized: boolean) => void;
 };
-/**
- * Cache for storing measured item heights
- * - Key: Item index in the list
- * - Value: Measured height in pixels
- */
-export type HeightCache = Record<number, number>;

package/dist/utils/virtualList.d.ts

@@ -1,4 +1,4 @@
-import type { SvelteVirtualListMode } from '../types.js';
+import type { SvelteVirtualListMode, SvelteVirtualListPreviousVisibleRange } from '../types.js';
 import type { VirtualListSetters, VirtualListState } from './types.js';
 /**
  * Calculates the maximum scroll position for a virtual list.
@@ -26,12 +26,9 @@ export declare const calculateScrollPosition: (totalItems: number, itemHeight: n
  * @param {number} totalItems - Total number of items in the list
  * @param {number} bufferSize - Number of items to render outside the visible area
  * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {{ start: number, end: number }} Range of indices to render
+ * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
-export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => {
-    start: number;
-    end: number;
-};
+export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => SvelteVirtualListPreviousVisibleRange;
 /**
  * Calculates the CSS transform value for positioning the virtual list items.
  *
@@ -64,19 +61,19 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  * Calculates the average height of visible items in a virtual list.
  *
  * This function optimizes performance by:
- * 1. Using a height cache to store measured item heights
+ * 1. Using a height cache to store measured item heights with dirty tracking
  * 2. Only measuring new items not in the cache
  * 3. Calculating a running average of all measured heights
  *
  * @param {HTMLElement[]} itemElements - Array of currently rendered item elements
  * @param {{ start: number }} visibleRange - Object containing the start index of visible items
- * @param {Record<number, number>} heightCache - Cache of previously measured item heights
+ * @param {HeightCache} heightCache - Cache of previously measured item heights with dirty tracking
  * @param {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
  *   newHeight: number,
  *   newLastMeasuredIndex: number,
- *   updatedHeightCache: Record<number, number>
+ *   updatedHeightCache: HeightCache
  * }} Object containing new calculated height, last measured index, and updated cache
  *
  * @example
@@ -89,10 +86,11 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  */
 export declare const calculateAverageHeight: (itemElements: HTMLElement[], visibleRange: {
     start: number;
-}, heightCache: Record<number, number>, currentItemHeight: number) => {
+}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>) => {
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
+    clearedDirtyItems: Set<number>;
 };
 /**
  * Processes large arrays in chunks to prevent UI blocking.
@@ -125,7 +123,7 @@ onComplete: () => void) => Promise<void>;
  * Builds a block sum array for fast offset calculation in large virtual lists.
  * Each entry in the array is the total height up to the end of that block (exclusive).
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} totalItems - Total number of items in the list
  * @param {number} blockSize - Number of items per block
@@ -141,7 +139,7 @@ export declare const buildBlockSums: (heightCache: Record<number, number>, calcu
  * - For indices >= blockSize, sums the block prefix, then only iterates the tail within the block.
  * - For small indices, falls back to the original logic.
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} idx - The index to scroll to (exclusive)
  * @param {number[]} [blockSums] - Optional precomputed block sums (for repeated queries)

package/dist/utils/virtualList.js

@@ -29,12 +29,23 @@ export const calculateScrollPosition = (totalItems, itemHeight, containerHeight)
  * @param {number} totalItems - Total number of items in the list
  * @param {number} bufferSize - Number of items to render outside the visible area
  * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {{ start: number, end: number }} Range of indices to render
+ * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
 export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode) => {
     if (mode === 'bottomToTop') {
         const visibleCount = Math.ceil(viewportHeight / itemHeight) + 1;
         const bottomIndex = totalItems - Math.floor(scrollTop / itemHeight);
+        // Safeguard: if bottomIndex is negative, it means scrollTop is too large for current itemHeight
+        // This can happen when itemHeight changes but scrollTop hasn't been corrected yet
+        if (bottomIndex < 0) {
+            // Calculate what scrollTop should be and use that for visible range
+            const totalHeight = totalItems * itemHeight;
+            const correctedScrollTop = Math.max(0, totalHeight - viewportHeight);
+            const correctedBottomIndex = totalItems - Math.floor(correctedScrollTop / itemHeight);
+            const start = Math.max(0, correctedBottomIndex - visibleCount - bufferSize);
+            const end = Math.min(totalItems, correctedBottomIndex + bufferSize);
+            return { start, end };
+        }
         // Add buffer to both ends
         const start = Math.max(0, bottomIndex - visibleCount - bufferSize);
         const end = Math.min(totalItems, bottomIndex + bufferSize);
@@ -43,6 +54,23 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
     else {
         const start = Math.floor(scrollTop / itemHeight);
         const end = Math.min(totalItems, start + Math.ceil(viewportHeight / itemHeight) + 1);
+        // Safeguard for topToBottom: ensure last item is fully visible when at max scroll
+        const totalHeight = totalItems * itemHeight;
+        const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
+        // Add dynamic tolerance based on item height for browser rendering precision
+        const tolerance = Math.max(itemHeight, 10); // At least one full item height or 10px minimum
+        const isAtBottom = Math.abs(scrollTop - maxScrollTop) <= tolerance;
+        if (isAtBottom) {
+            // When at the bottom, ensure we include all items up to the end
+            const adjustedEnd = totalItems;
+            const visibleItemCount = Math.ceil(viewportHeight / itemHeight) + bufferSize + 1;
+            const adjustedStart = Math.max(0, adjustedEnd - visibleItemCount);
+            // TopToBottom safeguard is now active
+            return {
+                start: adjustedStart,
+                end: adjustedEnd
+            };
+        }
         // Add buffer to both ends
         return {
             start: Math.max(0, start - bufferSize),
@@ -65,9 +93,15 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
  * @returns {number} The calculated transform Y value in pixels
  */
 export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart, itemHeight) => {
-    return mode === 'bottomToTop'
-        ? (totalItems - visibleEnd) * itemHeight
-        : visibleStart * itemHeight;
+    if (mode === 'bottomToTop') {
+        // In bottomToTop mode, we need to position the container so that
+        // the first visible item (visibleStart) aligns with its correct position
+        // from the bottom of the total content
+        return (totalItems - visibleEnd) * itemHeight;
+    }
+    else {
+        return visibleStart * itemHeight;
+    }
 };
 /**
  * Updates the virtual list's height and scroll position when necessary.
@@ -101,19 +135,19 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  * Calculates the average height of visible items in a virtual list.
  *
  * This function optimizes performance by:
- * 1. Using a height cache to store measured item heights
+ * 1. Using a height cache to store measured item heights with dirty tracking
  * 2. Only measuring new items not in the cache
  * 3. Calculating a running average of all measured heights
  *
  * @param {HTMLElement[]} itemElements - Array of currently rendered item elements
  * @param {{ start: number }} visibleRange - Object containing the start index of visible items
- * @param {Record<number, number>} heightCache - Cache of previously measured item heights
+ * @param {HeightCache} heightCache - Cache of previously measured item heights with dirty tracking
  * @param {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
  *   newHeight: number,
  *   newLastMeasuredIndex: number,
- *   updatedHeightCache: Record<number, number>
+ *   updatedHeightCache: HeightCache
  * }} Object containing new calculated height, last measured index, and updated cache
  *
  * @example
@@ -124,39 +158,89 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  *   40
  * )
  */
-export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight) => {
+export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems) => {
     const validElements = itemElements.filter((el) => el);
     if (validElements.length === 0) {
         return {
             newHeight: currentItemHeight,
             newLastMeasuredIndex: visibleRange.start,
-            updatedHeightCache: heightCache
+            updatedHeightCache: heightCache,
+            clearedDirtyItems: new Set()
         };
     }
     const newHeightCache = { ...heightCache };
-    // Cache heights for new items
-    validElements.forEach((el, i) => {
-        const itemIndex = visibleRange.start + i;
-        if (!newHeightCache[itemIndex]) {
-            try {
-                const height = el.getBoundingClientRect().height;
-                if (Number.isFinite(height) && height > 0) {
-                    newHeightCache[itemIndex] = height;
+    const clearedDirtyItems = new Set();
+    // Initialize running totals for O(1) average calculation
+    let totalValidHeight = 0;
+    let validHeightCount = 0;
+    // Calculate initial totals from existing cache
+    for (const height of Object.values(heightCache)) {
+        if (Number.isFinite(height) && height > 0) {
+            totalValidHeight += height;
+            validHeightCount++;
+        }
+    }
+    // Process only dirty items if they exist, otherwise process all visible items
+    if (dirtyItems.size > 0) {
+        // Process only dirty items
+        dirtyItems.forEach((itemIndex) => {
+            const elementIndex = itemIndex - visibleRange.start;
+            const element = validElements[elementIndex];
+            if (element && elementIndex >= 0 && elementIndex < validElements.length) {
+                try {
+                    const height = element.getBoundingClientRect().height;
+                    if (Number.isFinite(height) && height > 0) {
+                        const oldHeight = newHeightCache[itemIndex];
+                        // Only update if height actually changed (use smaller tolerance for precision)
+                        if (!oldHeight || Math.abs(oldHeight - height) >= 0.1) {
+                            // Update running totals
+                            if (oldHeight && Number.isFinite(oldHeight) && oldHeight > 0) {
+                                // Replace old height with new height in running total
+                                totalValidHeight = totalValidHeight - oldHeight + height;
+                            }
+                            else {
+                                // Add new height to running total
+                                totalValidHeight += height;
+                                validHeightCount++;
+                            }
+                            newHeightCache[itemIndex] = height;
+                        }
+                    }
+                    clearedDirtyItems.add(itemIndex);
+                }
+                catch {
+                    // Skip invalid measurements but still clear from dirty
+                    clearedDirtyItems.add(itemIndex);
                 }
             }
-            catch {
-                // Skip invalid measurements
+        });
+    }
+    else {
+        // Original behavior: process all visible items
+        validElements.forEach((el, i) => {
+            const itemIndex = visibleRange.start + i;
+            if (!newHeightCache[itemIndex]) {
+                try {
+                    const height = el.getBoundingClientRect().height;
+                    if (Number.isFinite(height) && height > 0) {
+                        // Add new height to running totals
+                        totalValidHeight += height;
+                        validHeightCount++;
+                        newHeightCache[itemIndex] = height;
+                    }
+                }
+                catch {
+                    // Skip invalid measurements
+                }
             }
-        }
-    });
-    // Calculate average from valid cached heights
-    const validHeights = Object.values(newHeightCache).filter((h) => Number.isFinite(h) && h > 0);
+        });
+    }
+    // O(1) average calculation using running totals!
     return {
-        newHeight: validHeights.length > 0
-            ? validHeights.reduce((sum, h) => sum + h, 0) / validHeights.length
-            : currentItemHeight,
+        newHeight: validHeightCount > 0 ? totalValidHeight / validHeightCount : currentItemHeight,
         newLastMeasuredIndex: visibleRange.start,
-        updatedHeightCache: newHeightCache
+        updatedHeightCache: newHeightCache,
+        clearedDirtyItems
     };
 };
 /**
@@ -206,7 +290,7 @@ onComplete) => {
  * Builds a block sum array for fast offset calculation in large virtual lists.
  * Each entry in the array is the total height up to the end of that block (exclusive).
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} totalItems - Total number of items in the list
  * @param {number} blockSize - Number of items per block
@@ -236,7 +320,7 @@ export const buildBlockSums = (heightCache, calculatedItemHeight, totalItems, bl
  * - For indices >= blockSize, sums the block prefix, then only iterates the tail within the block.
  * - For small indices, falls back to the original logic.
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} idx - The index to scroll to (exclusive)
  * @param {number[]} [blockSums] - Optional precomputed block sums (for repeated queries)