@humanspeak/svelte-virtual-list 0.3.3 → 0.3.5

package/README.md

@@ -259,4 +259,4 @@ MIT © [Humanspeak, Inc.](LICENSE)
 
 ## Credits
 
-Made with ♥ by [Humanspeak](https://humanspeak.com)
+Made with ❤️ by [Humanspeak](https://humanspeak.com)

package/dist/SvelteVirtualList.svelte

@@ -176,6 +176,9 @@
     import { onMount, tick, untrack } from 'svelte'
 
     const rafSchedule = createRafScheduler()
+    // Per-instance correction guard to avoid same-frame tug-of-war per viewport
+    const GLOBAL_CORRECTION_COOLDOWN = 16
+    const lastCorrectionTimestampByViewport = new WeakMap<HTMLElement, number>()
     // Package-specific debug flag - safe for library distribution
     // Enable with: PUBLIC_SVELTE_VIRTUAL_LIST_DEBUG=true (preferred) or SVELTE_VIRTUAL_LIST_DEBUG=true
     // Avoid SvelteKit-only $env imports so library works in non-Kit/Vitest contexts
@@ -251,6 +254,18 @@
         itemHeight: defaultEstimatedItemHeight,
         internalDebug: INTERNAL_DEBUG
     })
+    const instanceId = Math.random().toString(36).slice(2, 7)
+
+    // Centralized debug logger gated by flags
+    const log = (tag: string, payload?: unknown) => {
+        if (!debug && !INTERNAL_DEBUG) return
+        try {
+            const ts = new Date().toISOString().split('T')[1]?.replace('Z', '')
+            console.info(`[SVL][${instanceId}] ${ts} ${tag}`, payload ?? '')
+        } catch {
+            // no-op
+        }
+    }
 
     // Dynamic update coordination to avoid UA scroll anchoring interference
     let suppressBottomAnchoringUntilMs = $state(0)
@@ -339,11 +354,21 @@
             mode === 'bottomToTop' &&
             wasAtBottomBeforeHeightChange &&
             !programmaticScrollInProgress &&
-            performance.now() >= suppressBottomAnchoringUntilMs &&
-            !heightManager.isDynamicUpdateInProgress
+            performance.now() >= suppressBottomAnchoringUntilMs
         ) {
+            // Prevent same-frame corrections; defer if this viewport just corrected
+            const now = performance.now()
+            const viewportEl = heightManager.viewport
+            const lastCorrectionMs = lastCorrectionTimestampByViewport.get(viewportEl) ?? 0
+            if (now - lastCorrectionMs < GLOBAL_CORRECTION_COOLDOWN) {
+                suppressBottomAnchoringUntilMs = now + 50
+                return
+            }
+            lastCorrectionTimestampByViewport.set(viewportEl, now)
+
             // Step 1: Scroll to approximate position to ensure Item 0 gets rendered in virtual viewport
             const approximateScrollTop = Math.max(0, totalHeight() - height)
+            log('b2t-correction-approx', { approximateScrollTop })
             heightManager.viewport.scrollTop = approximateScrollTop
             heightManager.scrollTop = approximateScrollTop
 
@@ -353,15 +378,29 @@
                     '[data-original-index="0"]'
                 )
                 if (item0Element) {
-                    // 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
-                    })
-
+                    // Verify alignment via rects; if off, perform one-time scrollIntoView
+                    const contRect = heightManager.viewport.getBoundingClientRect()
+                    const itemRect = (item0Element as HTMLElement).getBoundingClientRect()
+                    const tol = 4
+                    const aligned =
+                        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('b2t-correction-native', {
+                            containerBottom: contRect.y + contRect.height,
+                            itemBottom: itemRect.y + itemRect.height
+                        })
+                    }
                     // Sync our internal scroll state with actual DOM position
                     heightManager.scrollTop = heightManager.viewport.scrollTop
+                    // After peer correction, delay further corrections briefly
+                    suppressBottomAnchoringUntilMs = performance.now() + 200
                 }
             })
 
@@ -445,7 +484,9 @@
 
                 // Handle height changes for scroll correction (manager totals already updated)
                 if (result.heightChanges.length > 0 && mode === 'bottomToTop') {
-                    handleHeightChangesScrollCorrection(result.heightChanges)
+                    // Run correction after dynamic update finishes to avoid blocking conditions
+                    const changes = result.heightChanges
+                    queueMicrotask(() => handleHeightChangesScrollCorrection(changes))
                 }
 
                 // TopToBottom: maintain bottom anchoring when total height changes
@@ -770,7 +811,8 @@
                 if (mode === 'bottomToTop') {
                     const delta = lastScrollTopSnapshot - current
                     if (delta > 0.5) {
-                        suppressBottomAnchoringUntilMs = performance.now() + 300
+                        // Widen suppression to avoid fighting peer instance corrections
+                        suppressBottomAnchoringUntilMs = performance.now() + 450
                         userHasScrolledAway = true
                     }
                 }
@@ -779,7 +821,7 @@
                 updateDebugTailDistance()
                 if (INTERNAL_DEBUG) {
                     const vr = visibleItems()
-                    console.info('[SVL] onscroll', {
+                    log('scroll', {
                         mode,
                         scrollTop: heightManager.scrollTop,
                         height,
@@ -808,40 +850,65 @@
      * @param immediate - Whether to skip the delay (used for resize events)
      */
     const updateHeightAndScroll = (immediate = false) => {
+        log('updateHeightAndScroll-enter', {
+            immediate,
+            initialized: heightManager.initialized,
+            mode
+        })
         if (!heightManager.initialized && mode === 'bottomToTop') {
+            // Deterministic init order: double RAF + microtask, then apply bottom anchoring
             tick().then(() => {
-                if (heightManager.isReady) {
-                    const initialHeight = heightManager.container.getBoundingClientRect().height
-                    height = initialHeight
-
-                    tick().then(() => {
-                        if (heightManager.isReady) {
-                            const finalHeight =
-                                heightManager.container.getBoundingClientRect().height
-                            height = finalHeight
-
-                            const targetScrollTop = calculateScrollPosition(
-                                items.length,
-                                heightManager.averageHeight,
-                                finalHeight
-                            )
-
-                            void heightManager.container.offsetHeight
-
+                requestAnimationFrame(() => {
+                    requestAnimationFrame(() => {
+                        if (!heightManager.isReady) return
+                        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()
+                            .replace(/[^a-z0-9]/g, '')
+                        const suffix = cleanedId.slice(-4)
+                        const parsed = parseInt(suffix, 36)
+                        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
-
                             requestAnimationFrame(() => {
-                                const currentScroll = heightManager.viewport.scrollTop
-                                if (currentScroll !== heightManager.scrollTop) {
-                                    heightManager.viewport.scrollTop = targetScrollTop
-                                    heightManager.scrollTop = targetScrollTop
-                                }
-                                heightManager.initialized = true
+                                // 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(() => {
+                                    const el = heightManager.viewport.querySelector(
+                                        '[data-original-index="0"]'
+                                    ) as HTMLElement | null
+                                    if (!el) return
+                                    const cont = heightManager.viewport.getBoundingClientRect()
+                                    const r = el.getBoundingClientRect()
+                                    const tol = 4
+                                    const aligned =
+                                        Math.abs(cont.y + cont.height - (r.y + r.height)) <= tol
+                                    if (!aligned) {
+                                        el.scrollIntoView({ block: 'end', inline: 'nearest' })
+                                        heightManager.scrollTop = heightManager.viewport.scrollTop
+                                        log('b2t-init-native-fallback', {
+                                            containerBottom: cont.y + cont.height,
+                                            itemBottom: r.y + r.height
+                                        })
+                                    }
+                                })
                             })
-                        }
+                        }, jitterMs)
                     })
-                }
+                })
             })
             return
         }
@@ -859,17 +926,24 @@
             {
                 setHeight: (h) => (height = h),
                 setScrollTop: (st) => (heightManager.scrollTop = st),
-                setInitialized: (i) => (heightManager.initialized = i)
+                // Guard: respect invariant in ReactiveListManager; avoid re-setting true
+                setInitialized: (i) => {
+                    if (i && heightManager.initialized) return
+                    heightManager.initialized = i
+                }
             },
             immediate
         )
+        log('updateHeightAndScroll-exit', { immediate })
     }
 
     // Create itemResizeObserver immediately when in browser
     if (BROWSER) {
         // Watch for individual item size changes
         itemResizeObserver = new ResizeObserver((entries) => {
-            tick().then(() => {
+            // Batch via RAF to avoid thrash across instances
+            rafSchedule(() => {
+                log('item-resize-observer', { entries: entries.length })
                 let shouldRecalculate = false
                 void visibleItems() // Cache once to avoid reactive loops
 
@@ -903,9 +977,8 @@
                 }
 
                 if (shouldRecalculate) {
-                    rafSchedule(() => {
-                        updateHeight()
-                    })
+                    log('item-resize-recalc')
+                    updateHeight()
                 }
             })
         })
@@ -915,14 +988,25 @@
     onMount(() => {
         if (BROWSER) {
             // Initial setup of heights and scroll position
+            log('onMount-enter', { mode, items: items.length })
             updateHeightAndScroll()
             // Ensure one initial measurement pass even if no ResizeObserver fires
             tick().then(() =>
-                requestAnimationFrame(() => requestAnimationFrame(() => updateHeight()))
+                requestAnimationFrame(() =>
+                    requestAnimationFrame(() => {
+                        log('post-hydration-measure')
+                        updateHeight()
+                    })
+                )
             )
 
             // Watch for container size changes
             resizeObserver = new ResizeObserver(() => {
+                if (!heightManager.initialized) {
+                    log('container-resize-ignored', 'not-initialized')
+                    return
+                }
+                log('container-resize')
                 updateHeightAndScroll(true)
             })
 

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

@@ -4,6 +4,7 @@ export declare class RecomputeScheduler {
     private isPending;
     private blockDepth;
     private timeoutId;
+    private rafId;
     constructor(onRecompute: () => void);
     schedule: () => void;
     block: () => void;

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

@@ -1,12 +1,19 @@
+// RecomputeScheduler
+// -------------------
+// Coalesces recompute requests to the next animation frame in the browser.
+// Falls back to setTimeout(0) in non-browser/jsdom to preserve deterministic tests.
+// Supports temporary blocking to delay recomputation during critical sections.
 export class RecomputeScheduler {
     onRecompute;
     isScheduled = false;
     isPending = false;
     blockDepth = 0;
     timeoutId = null;
+    rafId = null;
     constructor(onRecompute) {
         this.onRecompute = onRecompute;
     }
+    // Request a recompute. If blocked, mark as pending; otherwise schedule for next frame.
     schedule = () => {
         if (this.blockDepth > 0) {
             this.isPending = true;
@@ -15,16 +22,30 @@ export class RecomputeScheduler {
         if (this.isScheduled)
             return;
         this.isScheduled = true;
-        if (this.timeoutId) {
-            clearTimeout(this.timeoutId);
-            this.timeoutId = null;
+        // In jsdom or non-browser, fall back to immediate execution for determinism
+        const isBrowser = typeof window !== 'undefined' && typeof requestAnimationFrame === 'function';
+        if (!isBrowser) {
+            if (this.timeoutId) {
+                clearTimeout(this.timeoutId);
+                this.timeoutId = null;
+            }
+            this.timeoutId = setTimeout(() => {
+                this.timeoutId = null;
+                this.isScheduled = false;
+                this.onRecompute();
+            }, 0);
+            return;
         }
-        this.timeoutId = setTimeout(() => {
-            this.timeoutId = null;
+        // Browser path: coalesce with RAF for visual stability across instances
+        if (this.rafId !== null)
+            cancelAnimationFrame(this.rafId);
+        this.rafId = requestAnimationFrame(() => {
+            this.rafId = null;
             this.isScheduled = false;
             this.onRecompute();
-        }, 0);
+        });
     };
+    // Temporarily block recomputes; any in-flight timers are canceled and a recompute is marked pending.
     block = () => {
         this.blockDepth += 1;
         if (this.timeoutId) {
@@ -33,7 +54,14 @@ export class RecomputeScheduler {
             this.isScheduled = false;
             this.isPending = true;
         }
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+            this.isScheduled = false;
+            this.isPending = true;
+        }
     };
+    // Unblock and run recompute immediately if one was pending.
     unblock = () => {
         if (this.blockDepth === 0)
             return;
@@ -43,11 +71,16 @@ export class RecomputeScheduler {
             this.onRecompute();
         }
     };
+    // Cancel any scheduled recompute and clear pending state.
     cancel = () => {
         if (this.timeoutId) {
             clearTimeout(this.timeoutId);
             this.timeoutId = null;
         }
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
         this.isScheduled = false;
         this.isPending = false;
     };

package/dist/utils/raf.d.ts

@@ -29,4 +29,4 @@
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  */
-export declare function createRafScheduler(): (fn: () => void) => void;
+export declare const createRafScheduler: () => ((_fn: () => void) => void);

package/dist/utils/raf.js

@@ -29,11 +29,11 @@
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  */
-export function createRafScheduler() {
+export const createRafScheduler = () => {
     let scheduled = false;
     let callback = null;
-    return (fn) => {
-        callback = fn;
+    return (_fn) => {
+        callback = _fn;
         if (!scheduled) {
             scheduled = true;
             requestAnimationFrame(() => {
@@ -45,4 +45,4 @@ export function createRafScheduler() {
             });
         }
     };
-}
+};

package/dist/utils/virtualListDebug.d.ts

@@ -28,13 +28,13 @@ import type { SvelteVirtualListDebugInfo } from '../types.js';
  *   120
  * );
  */
-export declare function shouldShowDebugInfo(prevRange: {
+export declare const shouldShowDebugInfo: (prevRange: {
     start: number;
     end: number;
 } | null, currentRange: {
     start: number;
     end: number;
-}, prevHeight: number, currentHeight: number): boolean;
+}, prevHeight: number, currentHeight: number) => boolean;
 /**
  * Creates a comprehensive debug information object for virtual list state analysis.
  *
@@ -71,7 +71,7 @@ export declare function shouldShowDebugInfo(prevRange: {
  *
  * @throws {Error} Will throw if end index is less than start index in visibleRange
  */
-export declare function createDebugInfo(visibleRange: {
+export declare const createDebugInfo: (visibleRange: {
     start: number;
     end: number;
-}, totalItems: number, processedItems: number, averageItemHeight: number, scrollTop: number, viewportHeight: number, totalHeight: number): SvelteVirtualListDebugInfo;
+}, totalItems: number, processedItems: number, averageItemHeight: number, scrollTop: number, viewportHeight: number, totalHeight: number) => SvelteVirtualListDebugInfo;

package/dist/utils/virtualListDebug.js

@@ -27,13 +27,13 @@
  *   120
  * );
  */
-export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, currentHeight) {
+export const shouldShowDebugInfo = (prevRange, currentRange, prevHeight, currentHeight) => {
     if (!prevRange)
         return true;
     return (prevRange.start !== currentRange.start ||
         prevRange.end !== currentRange.end ||
         prevHeight !== currentHeight);
-}
+};
 /**
  * Creates a comprehensive debug information object for virtual list state analysis.
  *
@@ -70,7 +70,7 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  *
  * @throws {Error} Will throw if end index is less than start index in visibleRange
  */
-export function createDebugInfo(visibleRange, totalItems, processedItems, averageItemHeight, scrollTop, viewportHeight, totalHeight) {
+export const createDebugInfo = (visibleRange, totalItems, processedItems, averageItemHeight, scrollTop, viewportHeight, totalHeight) => {
     const atTop = scrollTop <= 1; // Small tolerance for floating point precision
     const atBottom = scrollTop >= totalHeight - viewportHeight - 1; // Small tolerance
     return {
@@ -84,4 +84,4 @@ export function createDebugInfo(visibleRange, totalItems, processedItems, averag
         atBottom,
         totalHeight
     };
-}
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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",
@@ -60,23 +60,23 @@
   },
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
-    "@eslint/js": "^9.36.0",
+    "@eslint/js": "^9.37.0",
     "@faker-js/faker": "^10.0.0",
-    "@playwright/test": "^1.55.1",
-    "@sveltejs/adapter-auto": "^6.1.0",
-    "@sveltejs/kit": "^2.43.4",
+    "@playwright/test": "^1.56.0",
+    "@sveltejs/adapter-auto": "^6.1.1",
+    "@sveltejs/kit": "^2.46.4",
     "@sveltejs/package": "^2.5.4",
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
-    "@tailwindcss/vite": "^4.1.13",
-    "@testing-library/jest-dom": "^6.8.0",
+    "@tailwindcss/vite": "^4.1.14",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.2.8",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^24.5.2",
-    "@typescript-eslint/eslint-plugin": "^8.44.1",
-    "@typescript-eslint/parser": "^8.44.1",
+    "@types/node": "^24.7.1",
+    "@typescript-eslint/eslint-plugin": "^8.46.0",
+    "@typescript-eslint/parser": "^8.46.0",
     "@vitest/coverage-v8": "^3.2.4",
     "concurrently": "^9.2.1",
-    "eslint": "^9.36.0",
+    "eslint": "^9.37.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-svelte": "^3.12.4",
@@ -89,14 +89,14 @@
     "prettier-plugin-sort-json": "^4.1.1",
     "prettier-plugin-svelte": "^3.4.0",
     "prettier-plugin-tailwindcss": "^0.6.14",
-    "publint": "^0.3.13",
-    "svelte": "^5.39.6",
-    "svelte-check": "^4.3.2",
-    "tailwindcss": "^4.1.13",
+    "publint": "^0.3.14",
+    "svelte": "^5.39.11",
+    "svelte-check": "^4.3.3",
+    "tailwindcss": "^4.1.14",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.44.1",
-    "vite": "^7.1.7",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vite": "^7.1.9",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
@@ -123,7 +123,7 @@
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "dev": "vite dev",
-    "dev:all": "concurrently -k -n pkg,docs -c green,cyan \"pnpm -w -r --filter @humanspeak/svelte-virtual-list run dev:pkg\" \"pnpm --filter docs run dev\"",
+    "dev:all": "concurrently -k -n pkg,docs,sitemap -c green,cyan,magenta \"pnpm -w -r --filter @humanspeak/svelte-virtual-list run dev:pkg\" \"pnpm --filter docs run dev\" \"pnpm --filter docs run sitemap:watch\"",
     "dev:pkg": "svelte-kit sync && svelte-package --watch",
     "format": "prettier --write .",
     "lint": "prettier --check . && eslint .",
@@ -134,6 +134,7 @@
     "test:all": "pnpm run test && pnpm run test:e2e",
     "test:e2e": "playwright test",
     "test:e2e:debug": "playwright test --debug",
+    "test:e2e:ff": "playwright test --project=firefox",
     "test:e2e:report": "playwright show-report",
     "test:e2e:ui": "playwright test --ui",
     "test:only": "vitest run --",