@humanspeak/svelte-virtual-list 0.3.13 → 0.4.1

package/README.md

@@ -31,108 +31,20 @@ A high-performance virtual list component for Svelte 5 applications that efficie
 - 🕹️ Programmatic scrolling with `scroll`
 - ♾️ Infinite scroll support with `onLoadMore`
 
-## scroll: Programmatic Scrolling
+## Requirements
 
-You can now programmatically scroll to any item in the list using the `scroll` method. This is useful for chat apps, jump-to-item navigation, and more. You can check the usage in `src/routes/tests/scroll`. Thank you for the feature request!
-
-### Usage Example
-
-```svelte
-<script lang="ts">
-    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
-    let listRef
-    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
-
-    function goToItem5000() {
-        // Scroll to item 5000 with smooth scrolling and auto alignment
-        listRef.scroll({ index: 5000, smoothScroll: true, align: 'auto' })
-    }
-</script>
-
-<button on:click={goToItem5000}> Scroll to item 5000 </button>
-<SvelteVirtualList {items} bind:this={listRef}>
-    {#snippet renderItem(item)}
-        <div>{item.text}</div>
-    {/snippet}
-</SvelteVirtualList>
-```
-
-### API
-
-- `scroll(options: { index: number; smoothScroll?: boolean; shouldThrowOnBounds?: boolean; align?: 'auto' | 'top' | 'bottom' | 'nearest' })`
-    - `index`: The item index to scroll to (0-based)
-    - `smoothScroll`: If true, uses smooth scrolling (default: true)
-    - `shouldThrowOnBounds`: If true, throws if index is out of bounds (default: true)
-    - `align`: Where to align the item in the viewport:
-        - `'auto'` (default): Only scroll if not visible, align to top or bottom as appropriate
-        - `'top'`: Always align to the top
-        - `'bottom'`: Always align to the bottom
-        - `'nearest'`: Scroll as little as possible to bring the item into view (like native scrollIntoView({ block: 'nearest' }))
-
-#### Usage Examples
-
-```svelte
-<button on:click={() => listRef.scroll({ index: 5000, align: 'nearest' })}>
-    Scroll to item 5000 (nearest)
-</button>
-```
-
-## Infinite Scroll
-
-Load more data automatically as users scroll near the end of the list. Perfect for paginated APIs, infinite feeds, and chat applications.
-
-```svelte
-<script lang="ts">
-    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
-
-    let items = $state([...initialItems])
-    let hasMore = $state(true)
-
-    async function loadMore() {
-        const newItems = await fetchMoreItems()
-        items = [...items, ...newItems]
-        if (newItems.length === 0) {
-            hasMore = false
-        }
-    }
-</script>
-
-<SvelteVirtualList {items} onLoadMore={loadMore} loadMoreThreshold={20} {hasMore}>
-    {#snippet renderItem(item)}
-        <div>{item.text}</div>
-    {/snippet}
-</SvelteVirtualList>
-```
-
-### Infinite Scroll Props
-
-| Prop                | Type                          | Default | Description                                          |
-| ------------------- | ----------------------------- | ------- | ---------------------------------------------------- |
-| `onLoadMore`        | `() => void \| Promise<void>` | -       | Callback when more data is needed (supports async)   |
-| `loadMoreThreshold` | `number`                      | `20`    | Number of items from the end to trigger `onLoadMore` |
-| `hasMore`           | `boolean`                     | `true`  | Set to `false` when all data has been loaded         |
-
-### Infinite Scroll Behavior
-
-- Triggers when scrolling near the end of the list
-- Automatically triggers on mount if initial items are below threshold
-- Prevents concurrent `onLoadMore` calls while loading
-- Works with both sync and async callbacks
-- Supports both `topToBottom` and `bottomToTop` modes
-
-### Integration Guides
-
-- [Infinite Scroll with Convex](documentation/CONVEX_INFINITE_SCROLL.md) - Real-time data + pagination with Convex backend
+- Svelte 5
+- Node.js 18+
 
 ## Installation
 
 ```bash
-# Using npm
-npm install @humanspeak/svelte-virtual-list
-
 # Using pnpm (recommended)
 pnpm add @humanspeak/svelte-virtual-list
 
+# Using npm
+npm install @humanspeak/svelte-virtual-list
+
 # Using yarn
 yarn add @humanspeak/svelte-virtual-list
 ```
@@ -156,9 +68,27 @@ yarn add @humanspeak/svelte-virtual-list
 </SvelteVirtualList>
 ```
 
-## Advanced Features
+## Props
 
-### Chat Application Example
+| Prop                         | Type                             | Default         | Description                                                                   |
+| ---------------------------- | -------------------------------- | --------------- | ----------------------------------------------------------------------------- |
+| `items`                      | `T[]`                            | Required        | Array of items to render                                                      |
+| `defaultEstimatedItemHeight` | `number`                         | `40`            | Initial height estimate used until items are measured                         |
+| `mode`                       | `'topToBottom' \| 'bottomToTop'` | `'topToBottom'` | Scroll direction and anchoring behavior                                       |
+| `bufferSize`                 | `number`                         | `20`            | Number of items rendered outside the viewport                                 |
+| `debug`                      | `boolean`                        | `false`         | Enable debug logging and visualizations                                       |
+| `containerClass`             | `string`                         | `''`            | Class for outer container                                                     |
+| `viewportClass`              | `string`                         | `''`            | Class for scrollable viewport                                                 |
+| `contentClass`               | `string`                         | `''`            | Class for content wrapper                                                     |
+| `itemsClass`                 | `string`                         | `''`            | Class for items container                                                     |
+| `testId`                     | `string`                         | `''`            | Base test id used in internal test hooks (useful for E2E/tests and debugging) |
+| `onLoadMore`                 | `() => void \| Promise<void>`    | -               | Callback when more data is needed for infinite scroll                         |
+| `loadMoreThreshold`          | `number`                         | `20`            | Items from end to trigger `onLoadMore`                                        |
+| `hasMore`                    | `boolean`                        | `true`          | Set to `false` when all data has been loaded                                  |
+
+## Bottom-to-Top Mode
+
+Use `mode="bottomToTop"` for chat-like lists anchored to the bottom:
 
 ```svelte
 <script lang="ts">
@@ -178,7 +108,7 @@ yarn add @humanspeak/svelte-virtual-list
 </script>
 
 <div style="height: 500px;">
-    <SvelteVirtualList items={messages} mode="bottomToTop" debug>
+    <SvelteVirtualList items={messages} mode="bottomToTop">
         {#snippet renderItem(message)}
             <div class="message-container">
                 <p>{message.text}</p>
@@ -191,40 +121,100 @@ yarn add @humanspeak/svelte-virtual-list
 </div>
 ```
 
-### Bottom-to-top mode
+## Programmatic Scrolling
 
-Use `mode="bottomToTop"` for chat-like lists anchored to the bottom. Programmatic scrolling uses the same API as top-to-bottom lists:
+Scroll to any item in the list using the `scroll` method. Useful for chat apps, jump-to-item navigation, and more.
 
 ```svelte
 <script lang="ts">
     import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
     let listRef
-    const messages = Array.from({ length: 2000 }, (_, i) => ({ id: i, text: `Msg ${i}` }))
+    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
+
+    function goToItem5000() {
+        listRef.scroll({ index: 5000, smoothScroll: true, align: 'auto' })
+    }
 </script>
 
+<button onclick={goToItem5000}> Scroll to item 5000 </button>
+<SvelteVirtualList {items} bind:this={listRef}>
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### scroll() Options
+
+| Option                | Type                                       | Default  | Description                             |
+| --------------------- | ------------------------------------------ | -------- | --------------------------------------- |
+| `index`               | `number`                                   | Required | The item index to scroll to (0-based)   |
+| `smoothScroll`        | `boolean`                                  | `true`   | Use smooth scrolling animation          |
+| `shouldThrowOnBounds` | `boolean`                                  | `true`   | Throw if index is out of bounds         |
+| `align`               | `'auto' \| 'top' \| 'bottom' \| 'nearest'` | `'auto'` | Where to align the item in the viewport |
+
+Alignment options:
+
+- `'auto'` - Only scroll if not visible, align to nearest edge
+- `'top'` - Always align to the top
+- `'bottom'` - Always align to the bottom
+- `'nearest'` - Scroll as little as possible to bring the item into view
+
+Works with both `topToBottom` and `bottomToTop` modes:
+
+```svelte
 <SvelteVirtualList items={messages} mode="bottomToTop" bind:this={listRef} />
-<button on:click={() => listRef.scroll({ index: messages.length - 1, align: 'bottom' })}>
+<button onclick={() => listRef.scroll({ index: messages.length - 1, align: 'bottom' })}>
     Jump to latest
 </button>
 ```
 
-## Props
+## Infinite Scroll
 
-| Prop                         | Type                             | Default         | Description                                                                   |
-| ---------------------------- | -------------------------------- | --------------- | ----------------------------------------------------------------------------- |
-| `items`                      | `T[]`                            | Required        | Array of items to render                                                      |
-| `defaultEstimatedItemHeight` | `number`                         | `40`            | Initial height estimate used until items are measured                         |
-| `mode`                       | `'topToBottom' \| 'bottomToTop'` | `'topToBottom'` | Scroll direction and anchoring behavior                                       |
-| `bufferSize`                 | `number`                         | `20`            | Number of items rendered outside the viewport                                 |
-| `debug`                      | `boolean`                        | `false`         | Enable debug logging and visualizations                                       |
-| `containerClass`             | `string`                         | `''`            | Class for outer container                                                     |
-| `viewportClass`              | `string`                         | `''`            | Class for scrollable viewport                                                 |
-| `contentClass`               | `string`                         | `''`            | Class for content wrapper                                                     |
-| `itemsClass`                 | `string`                         | `''`            | Class for items container                                                     |
-| `testId`                     | `string`                         | `''`            | Base test id used in internal test hooks (useful for E2E/tests and debugging) |
-| `onLoadMore`                 | `() => void \| Promise<void>`    | -               | Callback when more data is needed for infinite scroll                         |
-| `loadMoreThreshold`          | `number`                         | `20`            | Items from end to trigger `onLoadMore`                                        |
-| `hasMore`                    | `boolean`                        | `true`          | Set to `false` when all data has been loaded                                  |
+Load more data automatically as users scroll near the end of the list. Perfect for paginated APIs, infinite feeds, and chat applications.
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
+
+    let items = $state([...initialItems])
+    let hasMore = $state(true)
+
+    async function loadMore() {
+        const newItems = await fetchMoreItems()
+        items = [...items, ...newItems]
+        if (newItems.length === 0) {
+            hasMore = false
+        }
+    }
+</script>
+
+<SvelteVirtualList {items} onLoadMore={loadMore} loadMoreThreshold={20} {hasMore}>
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### Infinite Scroll Behavior
+
+- Triggers when scrolling near the end of the list
+- Automatically triggers on mount if initial items are below threshold
+- Prevents concurrent `onLoadMore` calls while loading
+- Works with both sync and async callbacks
+- Supports both `topToBottom` and `bottomToTop` modes
+
+### Integration Guides
+
+- [Infinite Scroll with Convex](documentation/CONVEX_INFINITE_SCROLL.md) - Real-time data + pagination with Convex backend
+
+## Performance Considerations
+
+- The `bufferSize` prop affects memory usage and scroll smoothness
+- Items are measured and cached for optimal performance
+- Dynamic height calculations happen automatically
+- Resize observers handle container/content changes
+- Virtual DOM updates are batched for efficiency
 
 ## Testing
 
@@ -254,33 +244,6 @@ npx playwright test tests/docs-visit.spec.ts --project=chromium
 npx playwright test --debug
 ```
 
-### Development Commands
-
-```bash
-# Start development server
-pnpm dev
-
-# Start both package and docs
-pnpm run dev:all
-
-# Check TypeScript/Svelte
-pnpm run check
-
-# Build package
-pnpm run build
-
-# Format and lint code
-pnpm run lint:fix
-```
-
-## Performance Considerations
-
-- The `bufferSize` prop affects memory usage and scroll smoothness
-- Items are measured and cached for optimal performance
-- Dynamic height calculations happen automatically
-- Resize observers handle container/content changes
-- Virtual DOM updates are batched for efficiency
-
 ## Project Structure
 
 This is a **PNPM workspace** with two packages:
@@ -288,22 +251,34 @@ This is a **PNPM workspace** with two packages:
 1. **`./`** - Main Svelte Virtual List component package
 2. **`./docs`** - Documentation site with live demos and examples
 
-### Development Workflow
+### Development Commands
 
 ```bash
 # Install dependencies for both packages
 pnpm install
 
-# Run development servers simultaneously
+# Start development server
+pnpm dev
+
+# Start both package and docs
 pnpm run dev:all
 
-# Build both packages
+# Build package
 pnpm run build
 
-# Run tests across the workspace
+# Check TypeScript/Svelte
+pnpm run check
+
+# Format and lint code (uses Trunk)
+trunk fmt
+trunk check
+
+# Run all tests
 pnpm test:all
 ```
 
+This project uses [Trunk](https://trunk.io) for formatting and linting. Trunk manages tool versions and runs checks automatically via pre-commit hooks.
+
 ## License
 
 MIT © [Humanspeak, Inc.](LICENSE)

package/dist/SvelteVirtualList.svelte

@@ -251,16 +251,16 @@
 
     const captureAnchor = () => {
         if (!heightManager.viewportElement) return
-        const vr = visibleItems()
+        const vr = visibleItems
         const anchorIndex = Math.max(0, vr.start)
         const cache = heightManager.getHeightCache()
         const est = heightManager.averageHeight
-        const maxScrollTop = Math.max(0, totalHeight() - (height || 0))
+        const maxScrollTop = Math.max(0, totalHeight - (height || 0))
         // Offset from start to anchored item
         const blockSums = buildBlockSums(cache, est, items.length)
         const offsetToIndex = getScrollOffsetForIndex(cache, est, anchorIndex, blockSums)
         const currentTop = heightManager.viewport.scrollTop
-        let offsetWithin = 0
+        let offsetWithin: number
         if (mode === 'bottomToTop') {
             // Convert distance-from-end to distance-from-start
             const distanceFromStart = maxScrollTop - currentTop
@@ -290,7 +290,7 @@
             Math.max(0, lastAnchorIndex),
             blockSums
         )
-        const maxScrollTop = clampValue(totalHeight() - (height || 0), 0, Infinity)
+        const maxScrollTop = clampValue(totalHeight - (height || 0), 0, Infinity)
         let targetTop: number
         if (mode === 'bottomToTop') {
             const distanceFromStart = clampValue(offsetToIndex + lastAnchorOffset, 0, Infinity)
@@ -402,23 +402,6 @@
     // Dynamic update coordination to avoid UA scroll anchoring interference
     let suppressBottomAnchoringUntilMs = $state(0)
 
-    const displayItems = $derived(() => {
-        const visibleRange = visibleItems()
-        const slice =
-            mode === 'bottomToTop'
-                ? items.slice(visibleRange.start, visibleRange.end).reverse()
-                : items.slice(visibleRange.start, visibleRange.end)
-
-        return slice.map((item, sliceIndex) => ({
-            item,
-            originalIndex:
-                mode === 'bottomToTop'
-                    ? visibleRange.end - 1 - sliceIndex
-                    : visibleRange.start + sliceIndex,
-            sliceIndex
-        }))
-    })
-
     /**
      * Handles scroll position corrections when item heights change, ensuring proper positioning
      * relative to the user's scroll context. This function calculates the cumulative impact of
@@ -442,7 +425,7 @@
         if (isScrolling) {
             // Accumulate net change above viewport and defer application
             let pending = 0
-            const currentVisibleRange = visibleItems()
+            const currentVisibleRange = visibleItems
             for (const change of heightChanges) {
                 if (change.index < currentVisibleRange.start) pending += change.delta
             }
@@ -488,7 +471,7 @@
          *
          * Dependencies:
          * - wasAtBottomBeforeHeightChange: Set to true when first item marked dirty, prevents cascading corrections
-         * - totalHeight(): Uses actual heightCache measurements instead of skewed averages
+         * - totalHeight: Uses actual heightCache measurements instead of skewed averages
          * - Aggressive scroll correction: Blocked when wasAtBottomBeforeHeightChange=true
          *
          * ⚠️  DO NOT MODIFY WITHOUT EXTENSIVE TESTING ⚠️
@@ -518,7 +501,7 @@
             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)
+            const approximateScrollTop = Math.max(0, totalHeight - height)
             log('[SVL] b2t-correction-approx', { approximateScrollTop })
             syncScrollTop(approximateScrollTop)
 
@@ -555,11 +538,11 @@
         }
 
         const currentScrollTop = heightManager.viewport.scrollTop
-        const maxScrollTop = Math.max(0, totalHeight() - height)
+        const maxScrollTop = Math.max(0, totalHeight - height)
 
         // Calculate total height change impact above current visible area
         let heightChangeAboveViewport = 0
-        const currentVisibleRange = visibleItems()
+        const currentVisibleRange = visibleItems
 
         for (const change of heightChanges) {
             // Only consider items that are above the current visible range
@@ -615,6 +598,7 @@
     // Keep height manager synchronized with items length
     $effect(() => {
         heightManager.updateItemLength(items.length)
+        stabilizedContentHeight = 0
     })
 
     // Infinite scroll: trigger onLoadMore when approaching end of list
@@ -623,7 +607,7 @@
         // Skip loading during bottomToTop initialization (init path renders all items artificially)
         if (mode === 'bottomToTop' && !bottomToTopScrollComplete) return
 
-        const range = visibleItems()
+        const range = visibleItems
         const atLoadingEdge = range.end >= items.length - loadMoreThreshold
         const insufficientItems = items.length < loadMoreThreshold && heightManager.initialized
 
@@ -755,9 +739,9 @@
      * This getter is reactive and updates whenever heightManager's internal state changes.
      * Used by: atBottom calculation, scroll corrections, maxScrollTop calculations
      */
-    const totalHeight = $derived(() => heightManager.totalHeight)
+    const totalHeight = $derived(heightManager.totalHeight)
 
-    const atBottom = $derived(heightManager.scrollTop >= totalHeight() - height - 1)
+    const atBottom = $derived(heightManager.scrollTop >= totalHeight - height - 1)
     let wasAtBottomBeforeHeightChange = false
     let lastVisibleRange: SvelteVirtualListPreviousVisibleRange | null = null
 
@@ -787,7 +771,7 @@
             mode === 'bottomToTop' &&
             heightManager.viewportElement
         ) {
-            const targetScrollTop = Math.max(0, totalHeight() - height)
+            const targetScrollTop = Math.max(0, totalHeight - height)
             const currentScrollTop = heightManager.viewport.scrollTop
             const scrollDifference = Math.abs(currentScrollTop - targetScrollTop)
 
@@ -797,7 +781,7 @@
             // 3. We're significantly off target
             // 4. We're not at the bottom (where height changes should be handled more carefully)
             const heightChanged = Math.abs(heightManager.averageHeight - lastCalculatedHeight) > 1
-            const maxScrollTop = Math.max(0, totalHeight() - height)
+            const maxScrollTop = Math.max(0, totalHeight - height)
 
             // In bottomToTop mode, we're "at bottom" when scroll is at max position
             const isAtBottom =
@@ -845,7 +829,7 @@
                 const currentScrollTop = heightManager.viewport.scrollTop
                 const currentCalculatedItemHeight = heightManager.averageHeight
                 const currentHeight = height
-                const currentTotalHeight = totalHeight()
+                const currentTotalHeight = totalHeight
                 const prevTotalHeight =
                     lastTotalHeightObserved ||
                     currentTotalHeight - itemsAdded * currentCalculatedItemHeight
@@ -891,7 +875,7 @@
                     // Reconcile on next frame in case measured heights adjust totals
                     requestAnimationFrame(() => {
                         const beforeReconcileScrollTop = heightManager.viewport.scrollTop
-                        const reconciledNextMax = clampValue(totalHeight() - height, 0, Infinity)
+                        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 = clampValue(
@@ -934,7 +918,7 @@
 
         lastItemsLength = currentItemsLength
         // Update last observed total height at the end of the effect
-        lastTotalHeightObserved = totalHeight()
+        lastTotalHeightObserved = totalHeight
     })
 
     // Update container height continuously to reflect layout changes that
@@ -970,13 +954,13 @@
      *
      * @example
      * ```typescript
-     * const range = visibleItems()
+     * const range = visibleItems
      * console.info(`Rendering items from ${range.start} to ${range.end}`)
      * ```
      *
      * @returns {SvelteVirtualListPreviousVisibleRange} Object containing start and end indices of visible items
      */
-    const visibleItems = $derived((): SvelteVirtualListPreviousVisibleRange => {
+    const visibleItems = $derived.by((): SvelteVirtualListPreviousVisibleRange => {
         if (!items.length) return { start: 0, end: 0 } as SvelteVirtualListPreviousVisibleRange
         const viewportHeight = height || 0
 
@@ -1021,7 +1005,7 @@
             atBottom,
             wasAtBottomBeforeHeightChange,
             lastVisibleRange,
-            totalHeight(),
+            totalHeight,
             heightManager.getHeightCache()
         )
 
@@ -1032,21 +1016,46 @@
      * Computed content height for the virtual list.
      * Uses the maximum of container height and total content height to ensure
      * proper scrolling behavior.
+     *
+     * In bottomToTop mode during active scroll, contentHeight is "ratcheted" —
+     * it can grow but never shrink. This prevents a feedback loop where
+     * averageHeight oscillation causes scrollHeight to bounce, triggering
+     * browser scrollTop adjustments that fire new scroll events.
+     * When scrolling stops (isScrolling goes false), it snaps to the true value.
      */
-    const contentHeight = $derived(() => Math.max(height, totalHeight()))
+    let stabilizedContentHeight = 0
+
+    const contentHeight = $derived.by(() => {
+        const raw = Math.max(height, totalHeight)
+
+        if (mode !== 'bottomToTop' || !isScrolling) {
+            stabilizedContentHeight = raw
+            return raw
+        }
+
+        // During active scroll in bottomToTop: only allow growth (ratchet)
+        // Prevents shrink → scrollTop adjust → new scroll event feedback loop
+        if (raw > stabilizedContentHeight) {
+            stabilizedContentHeight = raw
+        }
+
+        return stabilizedContentHeight
+    })
 
     /**
      * Computed transform Y value for positioning the visible items.
      * Extracted from inline IIFE for better performance and readability.
      */
-    const transformY = $derived(() => {
+    const transformY = $derived.by(() => {
         const viewportHeight = height || measuredFallbackHeight || 0
-        const visibleRange = visibleItems()
+        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
+        // Use precise offset using measured heights when available.
+        // For bottomToTop, pass ratcheted contentHeight so the transform stays
+        // stable while scrollHeight is stabilized (prevents visual shift).
         return Math.round(
             calculateTransformY(
                 mode,
@@ -1055,13 +1064,30 @@
                 visibleRange.start,
                 heightManager.averageHeight,
                 effectiveHeight,
-                totalHeight(),
+                mode === 'bottomToTop' ? contentHeight : totalHeight,
                 heightManager.getHeightCache(),
                 measuredFallbackHeight
             )
         )
     })
 
+    const displayItems = $derived.by(() => {
+        const visibleRange = visibleItems
+        const slice =
+            mode === 'bottomToTop'
+                ? items.slice(visibleRange.start, visibleRange.end).reverse()
+                : items.slice(visibleRange.start, visibleRange.end)
+
+        return slice.map((item, sliceIndex) => ({
+            item,
+            originalIndex:
+                mode === 'bottomToTop'
+                    ? visibleRange.end - 1 - sliceIndex
+                    : visibleRange.start + sliceIndex,
+            sliceIndex
+        }))
+    })
+
     /**
      * Handles scroll events in the viewport using requestAnimationFrame for performance.
      *
@@ -1124,12 +1150,12 @@
                 captureAnchor()
             }
             if (INTERNAL_DEBUG) {
-                const vr = visibleItems()
+                const vr = visibleItems
                 log('[SVL] scroll', {
                     mode,
                     scrollTop: heightManager.scrollTop,
                     height,
-                    totalHeight: totalHeight(),
+                    totalHeight: totalHeight,
                     averageItemHeight: heightManager.averageHeight,
                     visibleRange: vr
                 })
@@ -1160,7 +1186,7 @@
         })
         if (!heightManager.initialized && mode === 'bottomToTop') {
             // bottomToTop initialization: use scrollIntoView on Item 0 for precise positioning
-            // visibleItems() guarantees Item 0 is rendered during initialization
+            // visibleItems guarantees Item 0 is rendered during initialization
             tick().then(() => {
                 requestAnimationFrame(() => {
                     requestAnimationFrame(() => {
@@ -1181,7 +1207,7 @@
 
                         setTimeout(() => {
                             // Step 1: Set initialized (for other purposes like scroll event handling)
-                            // The init path in visibleItems() stays active until bottomToTopScrollComplete
+                            // The init path in visibleItems stays active until bottomToTopScrollComplete
                             if (!heightManager.initialized) {
                                 heightManager.initialized = true
                             }
@@ -1265,7 +1291,7 @@
             rafSchedule(() => {
                 log('item-resize-observer', { entries: entries.length })
                 let shouldRecalculate = false
-                void visibleItems() // Cache once to avoid reactive loops
+                void visibleItems // Cache once to avoid reactive loops
 
                 for (const entry of entries) {
                     const element = entry.target as HTMLElement
@@ -1349,7 +1375,7 @@
     // Add the effect in the script section
     $effect(() => {
         if (INTERNAL_DEBUG) {
-            prevVisibleRange = visibleItems()
+            prevVisibleRange = visibleItems
             prevHeight = heightManager.averageHeight
         }
     })
@@ -1358,7 +1384,7 @@
     // the callback writes to $state (which is forbidden during render effects)
     $effect(() => {
         if (!debug) return
-        const currentVisibleRange = visibleItems()
+        const currentVisibleRange = visibleItems
         if (
             !shouldShowDebugInfo(
                 prevVisibleRange,
@@ -1376,7 +1402,7 @@
             heightManager.averageHeight,
             heightManager.scrollTop,
             height || 0,
-            totalHeight()
+            totalHeight
         )
 
         if (debugFunction) {
@@ -1484,7 +1510,7 @@
             }
         }
 
-        const { start: firstVisibleIndex, end: lastVisibleIndex } = visibleItems()
+        const { start: firstVisibleIndex, end: lastVisibleIndex } = visibleItems
 
         // Use extracted scroll calculation utility
         const scrollTarget = calculateScrollTarget({
@@ -1630,16 +1656,16 @@
             id="virtual-list-content"
             {...testId ? { 'data-testid': `${testId}-content` } : {}}
             class={contentClass ?? 'virtual-list-content'}
-            style:height="{contentHeight()}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({transformY()}px)"
+                style:transform="translateY({transformY}px)"
             >
-                {#each displayItems() as currentItemWithIndex, _i (currentItemWithIndex.originalIndex)}
+                {#each displayItems as currentItemWithIndex, _i (currentItemWithIndex.originalIndex)}
                     <!-- Render each visible item -->
                     <div
                         bind:this={itemElements[currentItemWithIndex.sliceIndex]}

package/dist/reactive-list-manager/INTEGRATION_EXAMPLE.md

@@ -71,7 +71,7 @@ const updateHeight = () => {
 
 ```typescript
 // OLD: O(n) calculation every time
-// let totalHeight = $derived(() => {
+// let totalHeight = $derived.by(() => {
 //     let total = 0
 //     for (let i = 0; i < items.length; i++) {
 //         total += heightCache[i] || calculatedItemHeight
@@ -80,7 +80,7 @@ const updateHeight = () => {
 // })
 
 // NEW: O(1) reactive calculation 🚀
-let totalHeight = $derived(() => heightManager.totalHeight)
+let totalHeight = $derived(heightManager.totalHeight)
 ```
 
 ## Performance Benefits

package/dist/reactive-list-manager/README.md

@@ -32,7 +32,7 @@ ReactiveListManager processes only **dirty/changed items**:
 ```typescript
 // ✅ O(dirty items) - Fast and reactive
 manager.processDirtyHeights(changedItems)
-const totalHeight = manager.getDerivedTotalHeight()
+const totalHeight = manager.totalHeight
 ```
 
 ## 📦 Installation
@@ -82,7 +82,7 @@ new ReactiveListManager(config: ListManagerConfig)
 **Parameters:**
 
 - `config.itemLength` - Total number of items
-- `config.estimatedHeight` - Default height for unmeasured items
+- `config.itemHeight` - Default height for unmeasured items
 
 ### Core Methods
 
@@ -154,7 +154,7 @@ Check if manager has sufficient measurement data.
 // Create manager
 const heightManager = new ReactiveListManager({
     itemLength: items.length,
-    estimatedHeight: defaultEstimatedItemHeight
+    itemHeight: defaultEstimatedItemHeight
 })
 
 // Update on items change
@@ -182,7 +182,7 @@ $effect(() => {
 })
 
 // Reactive total height (automatically updates)
-let totalHeight = $derived(() => heightManager.totalHeight)
+let totalHeight = $derived(heightManager.totalHeight)
 ```
 
 ### Standalone Usage
@@ -190,7 +190,7 @@ let totalHeight = $derived(() => heightManager.totalHeight)
 ```typescript
 import { ReactiveListManager, benchmarkHeightManager } from './reactive-list-manager'
 
-const manager = new ReactiveListManager({ itemLength: 1000, estimatedHeight: 50 })
+const manager = new ReactiveListManager({ itemLength: 1000, itemHeight: 50 })
 
 // Performance monitoring
 const results = benchmarkHeightManager(10000, 1000, 100)
@@ -264,7 +264,7 @@ npm run test -- --grep "Performance Tests"
 
 ```text
 
-Height Changes → processDirtyHeights() → Update State → getDerivedTotalHeight() → Reactive UI
+Height Changes → processDirtyHeights() → Update State → totalHeight → Reactive UI
 
 ```
 
@@ -274,7 +274,7 @@ Height Changes → processDirtyHeights() → Update State → getDerivedTotalHei
 private _totalMeasuredHeight = $state(0)  // Sum of all measured heights
 private _measuredCount = $state(0)        // Count of measured items
 private _itemLength = $state(0)           // Total items
-private _estimatedHeight = $state(40)     // Default estimate
+private _itemHeight = $state(40)           // Default estimate
 ```
 
 ## 🔧 Types
@@ -288,7 +288,7 @@ interface HeightChange {
 
 interface ListManagerConfig {
     itemLength: number
-    estimatedHeight: number
+    itemHeight: number
 }
 
 interface ListManagerDebugInfo {
@@ -296,7 +296,7 @@ interface ListManagerDebugInfo {
     measuredCount: number
     itemLength: number
     coveragePercent: number
-    estimatedHeight: number
+    itemHeight: number
 }
 ```
 

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

@@ -10,7 +10,7 @@ import type { HeightChange, ListManagerConfig, ListManagerDebugInfo } from './ty
  *
  * @example
  * ```typescript
- * const manager = new ReactiveListManager({ itemLength: 10000, estimatedHeight: 40 })
+ * const manager = new ReactiveListManager({ itemLength: 10000, itemHeight: 40 })
  *
  * // Process height changes incrementally
  * manager.processDirtyHeights(dirtyResults)

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

@@ -10,7 +10,7 @@ import { RecomputeScheduler } from './RecomputeScheduler.js';
  *
  * @example
  * ```typescript
- * const manager = new ReactiveListManager({ itemLength: 10000, estimatedHeight: 40 })
+ * const manager = new ReactiveListManager({ itemLength: 10000, itemHeight: 40 })
  *
  * // Process height changes incrementally
  * manager.processDirtyHeights(dirtyResults)

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

@@ -23,7 +23,7 @@
  * manager.processDirtyHeights(heightChanges)
  *
  * // Get reactive total height
- * const totalHeight = manager.getDerivedTotalHeight(calculatedItemHeight)
+ * const totalHeight = manager.totalHeight
  * ```
  *
  * @example Performance Monitoring

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

@@ -23,7 +23,7 @@
  * manager.processDirtyHeights(heightChanges)
  *
  * // Get reactive total height
- * const totalHeight = manager.getDerivedTotalHeight(calculatedItemHeight)
+ * const totalHeight = manager.totalHeight
  * ```
  *
  * @example Performance Monitoring

package/dist/utils/heightCalculation.d.ts

@@ -35,7 +35,7 @@ import type { SvelteVirtualListMode } from '../types.js';
  *         calculateAverageHeightDebounced(
  *             false,
  *             null,
- *             () => getVisibleRange(),
+ *             visibleRange,
  *             itemElements,
  *             heightCache,
  *             lastMeasuredIndex,
@@ -59,7 +59,7 @@ import type { SvelteVirtualListMode } from '../types.js';
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
- * @param visibleItemsGetter - Function to get current visible range
+ * @param visibleItems - Current visible range
  * @param itemElements - Array of DOM elements to measure
  * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
@@ -68,7 +68,7 @@ import type { SvelteVirtualListMode } from '../types.js';
  * @param debounceTime - Time to wait between calculations (default: 200ms)
  * @returns Timeout object or null if calculation was skipped
  */
-export declare const calculateAverageHeightDebounced: (isCalculatingHeight: boolean, heightUpdateTimeout: ReturnType<typeof setTimeout> | null, visibleItemsGetter: () => {
+export declare const calculateAverageHeightDebounced: (isCalculatingHeight: boolean, heightUpdateTimeout: ReturnType<typeof setTimeout> | null, visibleItems: {
     start: number;
     end: number;
 }, itemElements: HTMLElement[], heightCache: Record<number, number>, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {

package/dist/utils/heightCalculation.js

@@ -36,7 +36,7 @@ import { BROWSER } from 'esm-env';
  *         calculateAverageHeightDebounced(
  *             false,
  *             null,
- *             () => getVisibleRange(),
+ *             visibleRange,
  *             itemElements,
  *             heightCache,
  *             lastMeasuredIndex,
@@ -60,7 +60,7 @@ import { BROWSER } from 'esm-env';
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
- * @param visibleItemsGetter - Function to get current visible range
+ * @param visibleItems - Current visible range
  * @param itemElements - Array of DOM elements to measure
  * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
@@ -69,19 +69,18 @@ import { BROWSER } from 'esm-env';
  * @param debounceTime - Time to wait between calculations (default: 200ms)
  * @returns Timeout object or null if calculation was skipped
  */
-export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
+export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItems, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
 /* trunk-ignore(eslint/no-unused-vars) */
 onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount = 0, mode = 'topToBottom') => {
     if (!BROWSER || isCalculatingHeight)
         return null;
-    const visibleRange = visibleItemsGetter();
-    const currentIndex = visibleRange.start;
+    const currentIndex = visibleItems.start;
     if (currentIndex === lastMeasuredIndex && dirtyItems.size === 0)
         return null;
     if (heightUpdateTimeout)
         clearTimeout(heightUpdateTimeout);
     return setTimeout(() => {
-        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount, heightChanges } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount, mode);
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount, heightChanges } = calculateAverageHeight(itemElements, visibleItems, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount, mode);
         if (Math.abs(newHeight - calculatedItemHeight) > 1 || dirtyItems.size > 0) {
             onUpdate({
                 newHeight,

package/dist/utils/virtualList.js

@@ -144,8 +144,17 @@ export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart,
     if (mode === 'bottomToTop') {
         // In bottomToTop mode, position items so they stack from bottom up
         const actualTotalHeight = totalContentHeight ?? totalItems * itemHeight;
-        // Calculate transform to position visible items correctly
-        const basicTransform = (totalItems - visibleEnd) * itemHeight;
+        // Calculate transform to position visible items correctly.
+        // Use measured heights when available to avoid oscillation caused by
+        // averageHeight changes shifting (totalItems - visibleEnd) * avg.
+        let basicTransform;
+        if (heightCache) {
+            const offsetToVisibleEnd = getScrollOffsetForIndex(heightCache, itemHeight, visibleEnd);
+            basicTransform = actualTotalHeight - offsetToVisibleEnd;
+        }
+        else {
+            basicTransform = (totalItems - visibleEnd) * itemHeight;
+        }
         // When content is smaller than viewport, push to bottom
         const bottomOffset = Math.max(0, effectiveViewport - actualTotalHeight);
         // Snap to integer pixels to avoid subpixel oscillation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.3.13",
+  "version": "0.4.1",
   "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",
@@ -91,7 +91,7 @@
     "prettier-plugin-svelte": "^3.4.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.17",
-    "svelte": "^5.51.2",
+    "svelte": "^5.51.3",
     "svelte-check": "^4.4.0",
     "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",