@humanspeak/svelte-virtual-list 0.3.9 → 0.3.11

package/dist/SvelteVirtualList.svelte

@@ -352,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)
@@ -534,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
@@ -990,6 +989,21 @@
             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,
@@ -1007,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.
      *
@@ -1057,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()
@@ -1138,10 +1193,14 @@
                                     ) as HTMLElement | null
 
                                     if (el && !userHasScrolled) {
-                                        el.scrollIntoView({
-                                            block: 'end',
-                                            inline: 'nearest'
-                                        })
+                                        // 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
                                     } else if (userHasScrolled) {
                                         // Sync internal state with current scroll
@@ -1288,6 +1347,38 @@
         }
     })
 
+    // Call debugFunction in an effect to avoid state_unsafe_mutation when
+    // the callback writes to $state (which is forbidden during render effects)
+    $effect(() => {
+        if (!debug) return
+        const currentVisibleRange = visibleItems()
+        if (
+            !shouldShowDebugInfo(
+                prevVisibleRange,
+                currentVisibleRange,
+                prevHeight,
+                heightManager.averageHeight
+            )
+        )
+            return
+
+        const info = createDebugInfo(
+            currentVisibleRange,
+            items.length,
+            Object.keys(heightManager.getHeightCache()).length,
+            heightManager.averageHeight,
+            heightManager.scrollTop,
+            height || 0,
+            totalHeight()
+        )
+
+        if (debugFunction) {
+            debugFunction(info)
+        } else {
+            console.info('Virtual List Debug:', info)
+        }
+    })
+
     /**
      * Scrolls the virtual list to the item at the given index.
      *
@@ -1531,54 +1622,16 @@
             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: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 -->
-                    {#if debug && i === 0 && shouldShowDebugInfo(prevVisibleRange, visibleItems(), prevHeight, heightManager.averageHeight)}
-                        {@const debugInfo = createDebugInfo(
-                            visibleItems(),
-                            items.length,
-                            Object.keys(heightManager.getHeightCache()).length,
-                            heightManager.averageHeight,
-                            heightManager.scrollTop,
-                            height || 0,
-                            totalHeight()
-                        )}
-                        {debugFunction
-                            ? debugFunction(debugInfo)
-                            : console.info('Virtual List Debug:', debugInfo)}
-                    {/if}
+                {#each displayItems() as currentItemWithIndex, _i (currentItemWithIndex.originalIndex)}
                     <!-- Render each visible item -->
                     <div
                         bind:this={itemElements[currentItemWithIndex.sliceIndex]}

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();
     }

package/dist/utils/perfMetrics.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Performance metrics utility for profiling virtual list operations.
+ *
+ * This lightweight profiling wrapper measures execution times for critical operations
+ * in the virtual list component. Enable by setting the environment variable:
+ * PUBLIC_SVELTE_VIRTUAL_LIST_PERF=true
+ *
+ * @example
+ * ```typescript
+ * import { perfMetrics, measureSync, measureAsync, isPerfEnabled } from './perfMetrics.js'
+ *
+ * // Measure synchronous operation
+ * const result = measureSync('visibleRange', () => calculateVisibleRange(...))
+ *
+ * // Get aggregated stats
+ * const stats = perfMetrics.getStats()
+ * console.log(stats.visibleRange.avg, stats.visibleRange.max)
+ * ```
+ */
+export type MetricName = 'scrollHandler' | 'visibleRange' | 'transformY' | 'heightBatch' | 'frameTime' | 'displayItems' | 'resizeObserver' | 'initialRender';
+export interface MetricEntry {
+    timestamp: number;
+    duration: number;
+}
+export interface MetricStats {
+    count: number;
+    total: number;
+    avg: number;
+    min: number;
+    max: number;
+    recent: number[];
+}
+export interface PerfMetrics {
+    scrollHandler: MetricEntry[];
+    visibleRange: MetricEntry[];
+    transformY: MetricEntry[];
+    heightBatch: MetricEntry[];
+    frameTime: MetricEntry[];
+    displayItems: MetricEntry[];
+    resizeObserver: MetricEntry[];
+    initialRender: MetricEntry[];
+}
+/**
+ * Check if performance profiling is enabled via environment variable
+ */
+export declare const isPerfEnabled: () => boolean;
+/**
+ * Measure a synchronous function's execution time
+ */
+export declare const measureSync: <T>(name: MetricName, fn: () => T) => T;
+/**
+ * Measure an async function's execution time
+ */
+export declare const measureAsync: <T>(name: MetricName, fn: () => Promise<T>) => Promise<T>;
+/**
+ * Start a manual timing measurement (for operations that span callbacks)
+ */
+export declare const startMeasure: () => (() => number);
+/**
+ * Record a pre-calculated duration
+ */
+export declare const recordDuration: (name: MetricName, duration: number) => void;
+/**
+ * Start FPS tracking during scroll
+ */
+export declare const startFpsTracking: () => void;
+/**
+ * Stop FPS tracking and return average FPS
+ */
+export declare const stopFpsTracking: () => number;
+/**
+ * Get current FPS (call during active tracking)
+ */
+export declare const getCurrentFps: () => number;
+/**
+ * Performance metrics interface with stats aggregation
+ */
+export declare const perfMetrics: {
+    /**
+     * Get aggregated stats for all metrics
+     */
+    getStats: () => Record<MetricName, MetricStats>;
+    /**
+     * Get stats for a single metric
+     */
+    getMetricStats: (name: MetricName) => MetricStats;
+    /**
+     * Get raw metric entries
+     */
+    getRawMetrics: () => PerfMetrics;
+    /**
+     * Reset all metrics
+     */
+    reset: () => void;
+    /**
+     * Get a summary report suitable for console output
+     */
+    getSummary: () => string;
+    /**
+     * Log summary to console
+     */
+    logSummary: () => void;
+};
+/**
+ * Memory tracking utilities
+ */
+export declare const getMemoryUsage: () => {
+    usedJSHeapSize: number;
+    totalJSHeapSize: number;
+} | null;
+/**
+ * Helper to format bytes to human-readable size
+ */
+export declare const formatBytes: (bytes: number) => string;

package/dist/utils/perfMetrics.js

@@ -0,0 +1,252 @@
+/**
+ * Performance metrics utility for profiling virtual list operations.
+ *
+ * This lightweight profiling wrapper measures execution times for critical operations
+ * in the virtual list component. Enable by setting the environment variable:
+ * PUBLIC_SVELTE_VIRTUAL_LIST_PERF=true
+ *
+ * @example
+ * ```typescript
+ * import { perfMetrics, measureSync, measureAsync, isPerfEnabled } from './perfMetrics.js'
+ *
+ * // Measure synchronous operation
+ * const result = measureSync('visibleRange', () => calculateVisibleRange(...))
+ *
+ * // Get aggregated stats
+ * const stats = perfMetrics.getStats()
+ * console.log(stats.visibleRange.avg, stats.visibleRange.max)
+ * ```
+ */
+const MAX_SAMPLES = 1000; // Keep last N samples per metric
+const RECENT_WINDOW = 100; // Number of recent samples for stats
+/**
+ * Check if performance profiling is enabled via environment variable
+ */
+export const isPerfEnabled = () => {
+    if (typeof process === 'undefined')
+        return false;
+    return (process?.env?.PUBLIC_SVELTE_VIRTUAL_LIST_PERF === 'true' ||
+        process?.env?.SVELTE_VIRTUAL_LIST_PERF === 'true');
+};
+const createEmptyMetrics = () => ({
+    scrollHandler: [],
+    visibleRange: [],
+    transformY: [],
+    heightBatch: [],
+    frameTime: [],
+    displayItems: [],
+    resizeObserver: [],
+    initialRender: []
+});
+let metrics = createEmptyMetrics();
+/**
+ * Record a metric measurement
+ */
+const record = (name, duration) => {
+    if (!isPerfEnabled())
+        return;
+    const entry = {
+        timestamp: performance.now(),
+        duration
+    };
+    metrics[name].push(entry);
+    // Keep array bounded
+    if (metrics[name].length > MAX_SAMPLES) {
+        metrics[name] = metrics[name].slice(-MAX_SAMPLES);
+    }
+};
+/**
+ * Measure a synchronous function's execution time
+ */
+export const measureSync = (name, fn) => {
+    if (!isPerfEnabled()) {
+        return fn();
+    }
+    const start = performance.now();
+    try {
+        return fn();
+    }
+    finally {
+        const duration = performance.now() - start;
+        record(name, duration);
+    }
+};
+/**
+ * Measure an async function's execution time
+ */
+export const measureAsync = async (name, fn) => {
+    if (!isPerfEnabled()) {
+        return fn();
+    }
+    const start = performance.now();
+    try {
+        return await fn();
+    }
+    finally {
+        const duration = performance.now() - start;
+        record(name, duration);
+    }
+};
+/**
+ * Start a manual timing measurement (for operations that span callbacks)
+ */
+export const startMeasure = () => {
+    const start = performance.now();
+    return () => performance.now() - start;
+};
+/**
+ * Record a pre-calculated duration
+ */
+export const recordDuration = (name, duration) => {
+    record(name, duration);
+};
+/**
+ * Calculate stats for a single metric
+ */
+const calculateStats = (entries) => {
+    if (entries.length === 0) {
+        return { count: 0, total: 0, avg: 0, min: 0, max: 0, recent: [] };
+    }
+    const durations = entries.map((e) => e.duration);
+    const total = durations.reduce((a, b) => a + b, 0);
+    const recent = durations.slice(-RECENT_WINDOW);
+    return {
+        count: entries.length,
+        total,
+        avg: total / entries.length,
+        min: Math.min(...durations),
+        max: Math.max(...durations),
+        recent
+    };
+};
+/**
+ * Frame rate tracking for scroll performance
+ */
+let frameTimestamps = [];
+let rafId = null;
+/**
+ * Start FPS tracking during scroll
+ */
+export const startFpsTracking = () => {
+    if (!isPerfEnabled())
+        return;
+    if (rafId !== null)
+        return;
+    frameTimestamps = [];
+    const trackFrame = () => {
+        frameTimestamps.push(performance.now());
+        // Keep only last 2 seconds of frames
+        const cutoff = performance.now() - 2000;
+        frameTimestamps = frameTimestamps.filter((t) => t > cutoff);
+        rafId = requestAnimationFrame(trackFrame);
+    };
+    rafId = requestAnimationFrame(trackFrame);
+};
+/**
+ * Stop FPS tracking and return average FPS
+ */
+export const stopFpsTracking = () => {
+    if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+        rafId = null;
+    }
+    if (frameTimestamps.length < 2)
+        return 0;
+    const duration = frameTimestamps[frameTimestamps.length - 1] - frameTimestamps[0];
+    if (duration <= 0)
+        return 0;
+    return (frameTimestamps.length - 1) / (duration / 1000);
+};
+/**
+ * Get current FPS (call during active tracking)
+ */
+export const getCurrentFps = () => {
+    if (frameTimestamps.length < 2)
+        return 0;
+    const now = performance.now();
+    const recentFrames = frameTimestamps.filter((t) => now - t < 1000);
+    if (recentFrames.length < 2)
+        return 0;
+    const duration = recentFrames[recentFrames.length - 1] - recentFrames[0];
+    if (duration <= 0)
+        return 0;
+    return (recentFrames.length - 1) / (duration / 1000);
+};
+/**
+ * Performance metrics interface with stats aggregation
+ */
+export const perfMetrics = {
+    /**
+     * Get aggregated stats for all metrics
+     */
+    getStats: () => ({
+        scrollHandler: calculateStats(metrics.scrollHandler),
+        visibleRange: calculateStats(metrics.visibleRange),
+        transformY: calculateStats(metrics.transformY),
+        heightBatch: calculateStats(metrics.heightBatch),
+        frameTime: calculateStats(metrics.frameTime),
+        displayItems: calculateStats(metrics.displayItems),
+        resizeObserver: calculateStats(metrics.resizeObserver),
+        initialRender: calculateStats(metrics.initialRender)
+    }),
+    /**
+     * Get stats for a single metric
+     */
+    getMetricStats: (name) => calculateStats(metrics[name]),
+    /**
+     * Get raw metric entries
+     */
+    getRawMetrics: () => ({ ...metrics }),
+    /**
+     * Reset all metrics
+     */
+    reset: () => {
+        metrics = createEmptyMetrics();
+    },
+    /**
+     * Get a summary report suitable for console output
+     */
+    getSummary: () => {
+        const stats = perfMetrics.getStats();
+        const lines = ['=== Virtual List Performance Summary ==='];
+        for (const [name, stat] of Object.entries(stats)) {
+            if (stat.count > 0) {
+                lines.push(`${name}: avg=${stat.avg.toFixed(2)}ms, max=${stat.max.toFixed(2)}ms, count=${stat.count}`);
+            }
+        }
+        return lines.join('\n');
+    },
+    /**
+     * Log summary to console
+     */
+    logSummary: () => {
+        if (isPerfEnabled()) {
+            console.info(perfMetrics.getSummary());
+        }
+    }
+};
+/**
+ * Memory tracking utilities
+ */
+export const getMemoryUsage = () => {
+    if (typeof performance !== 'undefined' &&
+        'memory' in performance &&
+        performance.memory) {
+        const memory = performance.memory;
+        return {
+            usedJSHeapSize: memory.usedJSHeapSize,
+            totalJSHeapSize: memory.totalJSHeapSize
+        };
+    }
+    return null;
+};
+/**
+ * Helper to format bytes to human-readable size
+ */
+export const formatBytes = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "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,43 +59,43 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@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",
+    "@eslint/compat": "^2.0.2",
+    "@eslint/js": "^10.0.1",
+    "@faker-js/faker": "^10.3.0",
+    "@playwright/test": "^1.58.2",
+    "@sveltejs/adapter-auto": "^7.0.1",
+    "@sveltejs/kit": "^2.52.0",
     "@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.3.1",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
+    "@types/node": "^25.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
     "@vitest/coverage-v8": "^4.0.18",
     "concurrently": "^9.2.1",
-    "eslint": "^9.39.2",
+    "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-svelte": "^3.14.0",
-    "eslint-plugin-unused-imports": "^4.3.0",
-    "globals": "^17.2.0",
+    "eslint-plugin-svelte": "^3.15.0",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "globals": "^17.3.0",
     "husky": "^9.1.7",
-    "jsdom": "^27.4.0",
+    "jsdom": "^28.1.0",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "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",
+    "svelte": "^5.51.2",
+    "svelte-check": "^4.4.0",
     "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.54.0",
+    "typescript-eslint": "^8.55.0",
     "vite": "^7.3.1",
     "vitest": "^4.0.18"
   },