@pdanpdan/virtual-scroll 0.3.0 → 0.5.0

package/src/composables/useVirtualScroll.test.ts

@@ -1,53 +1,85 @@
-/* global ScrollToOptions */
-import type { VirtualScrollProps } from './useVirtualScroll';
+/* global ScrollToOptions, ResizeObserverCallback */
+import type { VirtualScrollProps } from '../types';
 import type { Ref } from 'vue';
 
 import { mount } from '@vue/test-utils';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { defineComponent, nextTick, ref } from 'vue';
 
-import { getPaddingX, getPaddingY } from '../utils/scroll';
 import { useVirtualScroll } from './useVirtualScroll';
 
-type ResizeObserverCallback = (entries: ResizeObserverEntry[], observer: ResizeObserver) => void;
+// --- Mocks ---
 
-// Mock ResizeObserver
-interface ResizeObserverMock {
+interface ResizeObserverMock extends ResizeObserver {
   callback: ResizeObserverCallback;
   targets: Set<Element>;
-  trigger: (entries: Partial<ResizeObserverEntry>[]) => void;
 }
 
-globalThis.ResizeObserver = class {
+const observers: ResizeObserverMock[] = [];
+globalThis.ResizeObserver = class ResizeObserver {
   callback: ResizeObserverCallback;
-  static instances: ResizeObserverMock[] = [];
-  targets: Set<Element> = new Set();
-
+  targets = new Set<Element>();
   constructor(callback: ResizeObserverCallback) {
     this.callback = callback;
-    (this.constructor as unknown as { instances: ResizeObserverMock[]; }).instances.push(this as unknown as ResizeObserverMock);
+    observers.push(this as unknown as ResizeObserverMock);
   }
 
-  observe(target: Element) {
-    this.targets.add(target);
+  observe(el: Element) {
+    this.targets.add(el);
   }
 
-  unobserve(target: Element) {
-    this.targets.delete(target);
+  unobserve(el: Element) {
+    this.targets.delete(el);
   }
 
   disconnect() {
     this.targets.clear();
   }
+} as unknown as typeof ResizeObserver;
+
+function triggerResize(el: Element, width: number, height: number) {
+  const obs = observers.find((o) => o.targets.has(el));
+  if (obs) {
+    obs.callback([ {
+      borderBoxSize: [ { blockSize: height, inlineSize: width } ],
+      contentRect: {
+        bottom: height,
+        height,
+        left: 0,
+        right: width,
+        toJSON: () => '',
+        top: 0,
+        width,
+        x: 0,
+        y: 0,
+      },
+      target: el,
+    } as unknown as ResizeObserverEntry ], obs);
+  }
+}
+
+Object.defineProperty(HTMLElement.prototype, 'clientHeight', { configurable: true, value: 500 });
+Object.defineProperty(HTMLElement.prototype, 'clientWidth', { configurable: true, value: 500 });
+Object.defineProperty(document.documentElement, 'clientHeight', { configurable: true, value: 500 });
+Object.defineProperty(document.documentElement, 'clientWidth', { configurable: true, value: 500 });
+Object.defineProperty(window, 'innerHeight', { configurable: true, value: 500 });
+Object.defineProperty(window, 'innerWidth', { configurable: true, value: 500 });
 
-  trigger(entries: Partial<ResizeObserverEntry>[]) {
-    this.callback(entries as ResizeObserverEntry[], this as unknown as ResizeObserver);
+globalThis.window.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+  if (options.left !== undefined) {
+    Object.defineProperty(window, 'scrollX', { configurable: true, value: options.left, writable: true });
   }
-} as unknown as typeof ResizeObserver & { instances: ResizeObserverMock[]; };
+  if (options.top !== undefined) {
+    Object.defineProperty(window, 'scrollY', { configurable: true, value: options.top, writable: true });
+  }
+  document.dispatchEvent(new Event('scroll'));
+});
 
-globalThis.window.scrollTo = vi.fn();
+interface MockItem {
+  id: number;
+}
 
-// Helper to test composable within a component context
+// Helper to test composable
 function setup<T>(propsValue: VirtualScrollProps<T>) {
   const props = ref(propsValue) as Ref<VirtualScrollProps<T>>;
   let result: ReturnType<typeof useVirtualScroll<T>>;
@@ -59,1930 +91,1537 @@ function setup<T>(propsValue: VirtualScrollProps<T>) {
     },
   });
   const wrapper = mount(TestComponent);
-  return { result: result!, props, wrapper };
+  return { props, result: result!, wrapper };
 }
 
-const mockItems = Array.from({ length: 100 }, (_, i) => ({ id: i }));
-const defaultProps: VirtualScrollProps<{ id: number; }> = {
-  items: mockItems,
-  itemSize: 50,
-  direction: 'vertical' as const,
-  bufferBefore: 2,
-  bufferAfter: 2,
-  container: window,
-};
-
 describe('useVirtualScroll', () => {
+  const mockItems: MockItem[] = Array.from({ length: 100 }, (_, i) => ({ id: i }));
+
   beforeEach(() => {
-    window.scrollX = 0;
-    window.scrollY = 0;
-    Object.defineProperty(window, 'innerHeight', { configurable: true, value: 500 });
-    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 500 });
-    window.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
-      if (options.left !== undefined) {
-        window.scrollX = options.left;
-      }
-      if (options.top !== undefined) {
-        window.scrollY = options.top;
-      }
-      window.dispatchEvent(new Event('scroll'));
-    });
+    Object.defineProperty(window, 'scrollX', { configurable: true, value: 0, writable: true });
+    Object.defineProperty(window, 'scrollY', { configurable: true, value: 0, writable: true });
+    Object.defineProperty(document.documentElement, 'clientHeight', { configurable: true, value: 500 });
+    Object.defineProperty(document.documentElement, 'clientWidth', { configurable: true, value: 500 });
+  });
+
+  afterEach(() => {
     vi.clearAllMocks();
-    vi.useRealTimers();
   });
 
-  describe('initialization and dimensions', () => {
-    it('should initialize with correct total height', async () => {
-      const { result } = setup({ ...defaultProps });
-      expect(result.totalHeight.value).toBe(5000);
-    });
+  describe('core rendering & dimensions', () => {
+    it('calculates total dimensions correctly', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+      });
 
-    it('should update total size when items length changes', async () => {
-      const { result, props } = setup({ ...defaultProps });
       expect(result.totalHeight.value).toBe(5000);
-
-      props.value.items = Array.from({ length: 50 }, (_, i) => ({ id: i }));
-      await nextTick();
-      expect(result.totalHeight.value).toBe(2500);
+      expect(result.totalWidth.value).toBe(500);
+      wrapper.unmount();
     });
 
-    it('should recalculate totalHeight when itemSize changes', async () => {
-      const { result, props } = setup({ ...defaultProps });
-      expect(result.totalHeight.value).toBe(5000);
+    it('provides rendered items for the visible range', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+      });
 
-      props.value.itemSize = 100;
       await nextTick();
-      expect(result.totalHeight.value).toBe(10000);
-    });
-
-    it('should recalculate when gaps change', async () => {
-      const { result, props } = setup({ ...defaultProps, gap: 10 });
-      expect(result.totalHeight.value).toBe(5990); // 100 * (50 + 10) - 10
-
-      props.value.gap = 20;
       await nextTick();
-      expect(result.totalHeight.value).toBe(6980); // 100 * (50 + 20) - 20
-    });
 
-    it('should handle itemSize as a function', async () => {
-      const { result } = setup({
-        ...defaultProps,
-        itemSize: (_item: { id: number; }, index: number) => 50 + index,
-      });
-      // 50*100 + (0+99)*100/2 = 5000 + 4950 = 9950
-      // 9950 - gap(0) = 9950
-      expect(result.totalHeight.value).toBe(9950);
+      // viewport 500, item 50 => 10 items + buffer 5 = 15 items
+      expect(result.renderedItems.value.length).toBe(15);
+      expect(result.renderedItems.value[ 0 ]!.index).toBe(0);
+      wrapper.unmount();
     });
 
-    it('should handle direction both (grid mode)', async () => {
-      const { result } = setup({
-        ...defaultProps,
+    it('provides getRowHeight and getColumnWidth helpers', async () => {
+      const items: MockItem[] = [ { id: 1 }, { id: 2 } ];
+      const { result, wrapper } = setup({
         direction: 'both',
-        columnCount: 10,
-        columnWidth: 100,
+        itemSize: (item: MockItem) => (item.id === 1 ? 60 : 40),
+        columnWidth: [ 100, 200 ],
+        items,
+        gap: 10,
+        columnGap: 20,
       });
-      expect(result.totalWidth.value).toBe(1000); // 10 * 100 - 0
-      expect(result.totalHeight.value).toBe(5000); // 100 * 50 - 0
-    });
 
-    it('should handle horizontal direction', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'horizontal' });
-      expect(result.totalWidth.value).toBe(5000); // 100 * 50 - 0
-      expect(result.totalHeight.value).toBe(0);
-    });
+      await nextTick();
 
-    it('should cover default values for buffer and gap', async () => {
-      const { result } = setup({
-        items: mockItems,
-        itemSize: 50,
-      } as unknown as VirtualScrollProps<{ id: number; }>);
-      expect(result.renderedItems.value.length).toBeGreaterThan(0);
-    });
-  });
+      // getRowHeight returns item size WITHOUT gap
+      expect(result.getRowHeight(0)).toBe(60);
+      expect(result.getRowHeight(1)).toBe(40);
 
-  describe('range calculation', () => {
-    it('should calculate rendered items based on scroll position', async () => {
-      const { result } = setup({ ...defaultProps });
-      expect(result.renderedItems.value.length).toBeGreaterThan(0);
-      expect(result.scrollDetails.value.currentIndex).toBe(0);
-    });
+      // getColumnWidth returns col width WITHOUT gap
+      expect(result.getColumnWidth(0)).toBe(100);
+      expect(result.getColumnWidth(1)).toBe(200);
+      expect(result.getColumnWidth(2)).toBe(100); // cyclic for arrays
+      wrapper.unmount();
 
-    it('should handle horizontal direction in range/renderedItems', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'horizontal' });
-      expect(result.renderedItems.value.length).toBeGreaterThan(0);
-      expect(result.scrollDetails.value.currentIndex).toBe(0);
-    });
+      // Dynamic sizes
+      const { result: result2, wrapper: wrapper2 } = setup({
+        direction: 'vertical',
+        itemSize: 0,
+        items: [ { id: 1 } ],
+        defaultItemSize: 45,
+      });
 
-    it('should handle horizontal non-fixed size range', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientWidth', { value: 500 });
-      Object.defineProperty(container, 'clientHeight', { value: 500 });
-      const { result } = setup({ ...defaultProps, direction: 'horizontal', itemSize: undefined, container });
-      for (let i = 0; i < 20; i++) {
-        result.updateItemSize(i, 50, 50);
-      }
       await nextTick();
+      expect(result2.getRowHeight(0)).toBe(45); // default before measurement
 
-      container.scrollLeft = 100;
-      container.dispatchEvent(new Event('scroll'));
+      result2.updateItemSize(0, 100, 100);
       await nextTick();
-      expect(result.scrollDetails.value.currentIndex).toBeGreaterThan(0);
+      expect(result2.getRowHeight(0)).toBe(100);
+      wrapper2.unmount();
     });
-  });
 
-  describe('dynamic sizing', () => {
-    it('should handle columnCount fallback in updateItemSizes', async () => {
-      const { result, props } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 10,
-        columnWidth: undefined,
+    it('provides getItemSize helper with various direction and type branches', async () => {
+      const { result, wrapper } = setup({
+        direction: 'horizontal',
+        itemSize: 50,
+        items: mockItems,
+        columnGap: 10,
       });
       await nextTick();
+      expect(result.getItemSize(0)).toBe(50);
 
-      const cell = document.createElement('div');
-      cell.dataset.colIndex = '0';
+      await wrapper.unmount();
 
-      // Getter that returns 10 first time (for guard) and null second time (for fallback)
-      let count = 0;
-      Object.defineProperty(props.value, 'columnCount', {
-        get() {
-          count++;
-          return count === 1 ? 10 : null;
-        },
-        configurable: true,
+      const { result: res2, wrapper: w2 } = setup({
+        direction: 'vertical',
+        itemSize: (item: MockItem) => (item.id === 0 ? 100 : 40),
+        items: mockItems,
       });
-
-      result.updateItemSizes([ { index: 0, inlineSize: 200, blockSize: 50, element: cell } ]);
       await nextTick();
+      expect(res2.getItemSize(0)).toBe(100);
+      expect(res2.getItemSize(1)).toBe(40);
+      w2.unmount();
     });
 
-    it('should handle updateItemSizes with direct cell element', async () => {
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 2,
-        columnWidth: undefined,
+    it('getItemSize returns correct size based on direction and measurements', async () => {
+      const { result, wrapper } = setup({
+        direction: 'horizontal',
+        itemSize: 0,
+        items: mockItems,
+        columnGap: 10,
       });
       await nextTick();
-
-      const cell = document.createElement('div');
-      Object.defineProperty(cell, 'offsetWidth', { value: 200 });
-      cell.dataset.colIndex = '0';
-
-      result.updateItemSizes([ { index: 0, inlineSize: 200, blockSize: 50, element: cell } ]);
+      result.updateItemSize(0, 100, 100);
       await nextTick();
-      expect(result.getColumnWidth(0)).toBe(200);
-    });
+      // In horizontal, getItemSize uses itemSizesX - columnGap
+      expect(result.getItemSize(0)).toBe(100);
 
-    it('should handle updateItemSizes initial measurement even if smaller than estimate', async () => {
-      // Horizontal
-      const { result: rH } = setup({ ...defaultProps, direction: 'horizontal', itemSize: undefined });
-      await nextTick();
-      // Estimate is 40 (new DEFAULT_ITEM_SIZE). Update with 30.
-      rH.updateItemSizes([ { index: 0, inlineSize: 30, blockSize: 30 } ]);
-      await nextTick();
-      expect(rH.renderedItems.value[ 0 ]?.size.width).toBe(30);
+      // Test fallback to default when not measured yet
+      expect(result.getItemSize(1)).toBe(40);
 
-      // Subsequent update with smaller size should also be applied now
-      rH.updateItemSizes([ { index: 0, inlineSize: 25, blockSize: 25 } ]);
-      await nextTick();
-      expect(rH.renderedItems.value[ 0 ]?.size.width).toBe(25);
+      wrapper.unmount();
 
-      // Vertical
-      const { result: rV } = setup({ ...defaultProps, direction: 'vertical', itemSize: undefined });
+      const { result: res2, wrapper: w2 } = setup({
+        direction: 'vertical',
+        itemSize: 0,
+        items: mockItems,
+        gap: 10,
+      });
       await nextTick();
-      rV.updateItemSizes([ { index: 0, inlineSize: 30, blockSize: 30 } ]);
+      res2.updateItemSize(0, 100, 100);
       await nextTick();
-      expect(rV.renderedItems.value[ 0 ]?.size.height).toBe(30);
+      // In vertical, fallback uses itemSizesY - gap
+      expect(res2.getItemSize(0)).toBe(100);
+      w2.unmount();
+    });
+
+    it('supports getColumnWidth with various types', async () => {
+      const { result, wrapper } = setup({
+        columnCount: 10,
+        columnWidth: [ 100, 200 ],
+        direction: 'both',
+        items: mockItems,
+      });
 
-      // Subsequent update with smaller size should be applied
-      rV.updateItemSizes([ { index: 0, inlineSize: 20, blockSize: 20 } ]);
       await nextTick();
-      expect(rV.renderedItems.value[ 0 ]?.size.height).toBe(20);
+      expect(result.getColumnWidth(0)).toBe(100);
+      expect(result.getColumnWidth(1)).toBe(200);
+      expect(result.getColumnWidth(2)).toBe(100);
+      wrapper.unmount();
     });
 
-    it('should handle updateItemSize and trigger reactivity', async () => {
-      const { result } = setup({ ...defaultProps, itemSize: undefined });
-      expect(result.totalHeight.value).toBe(4000); // 100 * 40
+    it('skips invalid items in renderedItems', async () => {
+      const { result, props, wrapper } = setup({
+        direction: 'vertical',
+        itemSize: 50,
+        items: [ { id: 1 }, { id: 2 } ],
+      });
 
-      result.updateItemSize(0, 100, 100);
       await nextTick();
-      expect(result.totalHeight.value).toBe(4060); // 4000 - 40 + 100
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(100);
-    });
+      await nextTick();
 
-    it('should treat 0, null, undefined as dynamic itemSize', async () => {
-      for (const val of [ 0, null, undefined ]) {
-        const { result } = setup({ ...defaultProps, itemSize: val as unknown as undefined });
-        expect(result.totalHeight.value).toBe(4000);
-        result.updateItemSize(0, 100, 100);
-        await nextTick();
-        expect(result.totalHeight.value).toBe(4060);
-      }
+      // Manually force an out-of-bounds range or inconsistent state
+      props.value.items = [ { id: 1 } ];
+      // renderedItems will filter out index 1 if it's still in range.end
+      expect(result.renderedItems.value.length).toBe(1);
+      wrapper.unmount();
     });
 
-    it('should treat 0, null, undefined as dynamic columnWidth', async () => {
-      for (const val of [ 0, null, undefined ]) {
-        const { result } = setup({
-          ...defaultProps,
-          direction: 'both',
-          columnCount: 2,
-          columnWidth: val as unknown as undefined,
-        });
-        expect(result.getColumnWidth(0)).toBe(100); // DEFAULT_COLUMN_WIDTH
-        const parent = document.createElement('div');
-        const col0 = document.createElement('div');
-        Object.defineProperty(col0, 'offsetWidth', { value: 200, configurable: true });
-        col0.dataset.colIndex = '0';
-        parent.appendChild(col0);
-        result.updateItemSize(0, 200, 50, parent);
-        await nextTick();
-        expect(result.totalWidth.value).toBe(300); // 200 + 100
-      }
-    });
+    it('handles sparse items array', async () => {
+      const sparseItems: unknown[] = [];
+      sparseItems[ 0 ] = { id: 0 };
+      sparseItems[ 10 ] = { id: 10 }; // hole between 1 and 9
 
-    it('should handle dynamic column width with data-col-index', async () => {
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 2,
-        columnWidth: undefined,
+      const { result, wrapper } = setup({
+        direction: 'vertical',
+        itemSize: 50,
+        items: sparseItems,
       });
-      const parent = document.createElement('div');
-      const child1 = document.createElement('div');
-      Object.defineProperty(child1, 'offsetWidth', { value: 200 });
-      child1.dataset.colIndex = '0';
-      const child2 = document.createElement('div');
-      Object.defineProperty(child2, 'offsetWidth', { value: 300 });
-      child2.dataset.colIndex = '1';
-      parent.appendChild(child1);
-      parent.appendChild(child2);
-
-      result.updateItemSize(0, 500, 50, parent);
-      await nextTick();
-      expect(result.getColumnWidth(0)).toBe(200);
-      expect(result.getColumnWidth(1)).toBe(300);
-    });
 
-    it('should return early in updateItemSize if itemSize is fixed', async () => {
-      const { result } = setup({ ...defaultProps, itemSize: 50 });
-      result.updateItemSize(0, 100, 100);
-      expect(result.totalHeight.value).toBe(5000);
+      await nextTick();
+      await nextTick();
+
+      // Should only render the defined items
+      expect(result.renderedItems.value.length).toBeGreaterThan(0);
+      expect(result.renderedItems.value.every((i) => i.item !== undefined)).toBe(true);
+      wrapper.unmount();
     });
 
-    it('should use defaultItemSize and defaultColumnWidth when provided', () => {
-      const { result } = setup({
-        ...defaultProps,
-        itemSize: undefined,
-        columnWidth: undefined,
-        defaultItemSize: 100,
-        defaultColumnWidth: 200,
-        direction: 'both',
-        columnCount: 10,
+    it('uses sequential query optimization in renderedItems', async () => {
+      const { result, wrapper } = setup({
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+        bufferBefore: 0,
+        bufferAfter: 10,
       });
 
-      expect(result.totalHeight.value).toBe(100 * 100); // 100 items * 100 defaultItemSize
-      expect(result.totalWidth.value).toBe(10 * 200); // 10 columns * 200 defaultColumnWidth
-    });
-
-    it('should ignore small delta updates in updateItemSize only after first measurement', async () => {
-      const { result } = setup({ ...defaultProps, itemSize: undefined });
-      // Default is 40. 40.1 is < 0.5 delta.
-      // First measurement should be accepted even if small delta from estimate.
-      result.updateItemSize(0, 40.1, 40.1);
       await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(40.1);
-
-      // Second measurement with small delta from first should be ignored.
-      result.updateItemSize(0, 40.2, 40.2);
       await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(40.1);
-    });
 
-    it('should update item height in both mode now (allow decreases)', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'both', itemSize: undefined, columnCount: 2 });
-      result.updateItemSize(0, 100, 100);
-      await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(100);
+      // accessing renderedItems will trigger queryYCached sequentially
+      const items = result.renderedItems.value;
+      expect(items.length).toBeGreaterThan(5);
+      expect(items[ 0 ]!.index).toBe(0);
+      expect(items[ 1 ]!.index).toBe(1);
 
-      result.updateItemSize(0, 100, 80);
-      await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(80);
+      wrapper.unmount();
     });
 
-    it('should update item height in vertical mode', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'vertical', itemSize: undefined });
-      result.updateItemSize(0, 100, 100);
-      await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(100);
+    it('handles non-sequential prefix sum queries and sticky item queries', async () => {
+      const { result, wrapper } = setup({
+        direction: 'vertical',
+        items: mockItems,
+        itemSize: 50,
+        stickyIndices: [ 0, 50, 99 ],
+      });
 
-      result.updateItemSize(0, 100, 70);
       await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(70);
-    });
-
-    it('should handle updateItemSize for horizontal direction', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'horizontal', itemSize: undefined });
-      result.updateItemSize(0, 100, 50);
       await nextTick();
-      expect(result.totalWidth.value).toBe(4060); // 4000 - 40 + 100
-    });
 
-    it('should preserve measurements in initializeSizes when dynamic', async () => {
-      const { result, props } = setup({ ...defaultProps, itemSize: undefined });
-      result.updateItemSize(0, 100, 100);
+      // Scroll to end (4500)
+      result.scrollToOffset(null, 4500);
       await nextTick();
-      expect(result.totalHeight.value).toBe(4060);
-
-      // Trigger initializeSizes by changing length
-      props.value.items = Array.from({ length: 101 }, (_, i) => ({ id: i }));
       await nextTick();
-      // Should still be 100 for index 0, not reset to default 40
-      expect(result.totalHeight.value).toBe(4060 + 40);
+
+      // renderedItems will query indices around 99.
+      // Sticky logic will query index 50 non-sequentially.
+      expect(result.renderedItems.value.length).toBeGreaterThan(0);
+      wrapper.unmount();
     });
-  });
 
-  describe('scrolling and API', () => {
-    it('should handle scrollToIndex with horizontal direction and dynamic item size', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
-      const { result } = setup({ ...defaultProps, container, direction: 'horizontal', itemSize: undefined });
-      await nextTick();
+    it('calculates column range and offsets correctly during ssr', async () => {
+      const { result, wrapper } = setup({
+        direction: 'both',
+        items: mockItems,
+        columnCount: 10,
+        columnWidth: 100,
+        itemSize: 50,
+        ssrRange: { start: 10, end: 20, colStart: 2, colEnd: 5 },
+      });
 
-      // index 10. itemSize is 40 by default. totalWidth = 4000.
-      result.scrollToIndex(null, 10, { align: 'start', behavior: 'auto' });
-      await nextTick();
-      expect(result.scrollDetails.value.scrollOffset.x).toBe(400);
-    });
+      // isHydrated is false initially
+      expect(result.isHydrated.value).toBe(false);
 
-    it('should handle scrollToIndex with window fallback when container is missing', async () => {
-      const { result } = setup({ ...defaultProps, container: undefined });
-      await nextTick();
-      result.scrollToIndex(10, 0);
-      await nextTick();
-      expect(window.scrollTo).toHaveBeenCalled();
+      // columnRange during SSR
+      expect(result.columnRange.value.start).toBe(2);
+      expect(result.columnRange.value.end).toBe(5);
+      expect(result.columnRange.value.padStart).toBe(200);
+
+      // renderedItems offsets during SSR
+      // ssrOffsetY = 10 * 50 = 500. ssrOffsetX = columnSizes.query(2) = 200.
+      // Item (10, 2) is at VU(200, 500).
+      // offsetX = (originalX - ssrOffsetX) = (200 - 200) = 0
+      const item = result.renderedItems.value.find((i) => i.index === 10);
+      expect(item).toBeDefined();
+      expect(item?.offset.x).toBe(0);
+      expect(item?.offset.y).toBe(0);
+
+      wrapper.unmount();
     });
 
-    it('should handle scrollToIndex out of bounds', async () => {
-      const { result } = setup({ ...defaultProps });
-      // Row past end
-      result.scrollToIndex(mockItems.length + 10, 0);
-      await nextTick();
-      expect(window.scrollTo).toHaveBeenCalled();
+    it('supports refresh method', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+      });
 
-      // Col past end (in grid mode)
-      const { result: r_grid } = setup({ ...defaultProps, direction: 'both', columnCount: 5, columnWidth: 100 });
-      r_grid.scrollToIndex(0, 10);
       await nextTick();
-      expect(window.scrollTo).toHaveBeenCalled();
-
-      // Column past end in horizontal mode
-      const { result: r_horiz } = setup({ ...defaultProps, direction: 'horizontal' });
-      r_horiz.scrollToIndex(0, 200);
+      result.refresh();
       await nextTick();
+      expect(result.totalHeight.value).toBe(5000);
+      wrapper.unmount();
     });
 
-    it('should handle scrollToIndex auto alignment with padding', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500, configurable: true });
-      Object.defineProperty(container, 'scrollTop', { value: 200, writable: true, configurable: true });
+    it('cleans up observers on unmount', async () => {
+      const disconnectSpy = vi.fn();
+      const oldMutationObserver = globalThis.MutationObserver;
+      globalThis.MutationObserver = (class MutationObserver {
+        observe = vi.fn();
+        disconnect = disconnectSpy;
+      } as unknown) as typeof MutationObserver;
 
-      const { result } = setup({ ...defaultProps, container, itemSize: 50, scrollPaddingStart: 100 });
-      await nextTick();
+      const { wrapper } = setup({
+        container: document.createElement('div'),
+        items: mockItems,
+      });
 
-      // Current visible range: [scrollTop + paddingStart, scrollTop + viewport - paddingEnd] = [300, 700]
-      // Scroll to item at y=250. 250 < 300, so not visible.
-      // targetY < relativeScrollY + paddingStart (250 < 200 + 100)
-      result.scrollToIndex(5, null, 'auto');
       await nextTick();
+      wrapper.unmount();
+      expect(disconnectSpy).toHaveBeenCalled();
+      globalThis.MutationObserver = oldMutationObserver;
     });
+  });
+
+  describe('scroll management', () => {
+    it('updates when scroll position changes', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+      });
 
-    it('should hit scrollToIndex X calculation branches', async () => {
-      const { result: r_horiz } = setup({ ...defaultProps, direction: 'horizontal', itemSize: 100 });
       await nextTick();
-      // colIndex null
-      r_horiz.scrollToIndex(0, null);
-      // rowIndex null
-      r_horiz.scrollToIndex(null, 5);
       await nextTick();
-    });
-
-    it('should handle scrollToOffset with element container and scrollTo method', async () => {
-      const container = document.createElement('div');
-      container.scrollTo = vi.fn();
-      const { result } = setup({ ...defaultProps, container });
-      result.scrollToOffset(100, 200);
-      expect(container.scrollTo).toHaveBeenCalled();
-    });
 
-    it('should handle scrollToOffset with currentX/currentY fallbacks', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'scrollLeft', { value: 50, writable: true });
-      Object.defineProperty(container, 'scrollTop', { value: 60, writable: true });
+      Object.defineProperty(window, 'scrollY', { configurable: true, value: 500, writable: true });
+      document.dispatchEvent(new Event('scroll'));
 
-      const { result } = setup({ ...defaultProps, container });
       await nextTick();
-
-      // Pass null to x and y to trigger fallbacks to currentX and currentY
-      result.scrollToOffset(null, null);
       await nextTick();
 
-      // scrollOffset.x = targetX - hostOffset.x + (isHorizontal ? paddingStartX : 0)
-      // targetX = currentX = 50. hostOffset.x = 0. isHorizontal = false.
-      // So scrollOffset.x = 50.
-      expect(result.scrollDetails.value.scrollOffset.x).toBe(50);
-      expect(result.scrollDetails.value.scrollOffset.y).toBe(60);
+      // At 500px, start index is 500/50 = 10. With buffer 5, start is 5.
+      expect(result.scrollDetails.value.currentIndex).toBe(10);
+      expect(result.renderedItems.value[ 0 ]!.index).toBe(5);
+      wrapper.unmount();
     });
 
-    it('should handle scrollToOffset with restricted direction for padding fallback', async () => {
-      const container = document.createElement('div');
-      container.scrollTo = vi.fn();
+    it('supports programmatic scrolling', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+      });
 
-      // Horizontal direction: isVertical will be false, so targetY padding fallback will be 0
-      const { result } = setup({ ...defaultProps, container, direction: 'horizontal', scrollPaddingStart: 10 });
       await nextTick();
-
-      result.scrollToOffset(100, 100);
       await nextTick();
-      // targetY = 100 + hostOffset.y - (isVertical ? paddingStartY : 0)
-      // Since isVertical is false, it uses 0. hostOffset.y is 0 here.
-      expect(container.scrollTo).toHaveBeenCalledWith(expect.objectContaining({
-        top: 100,
-      }));
 
-      // Vertical direction: isHorizontal will be false, so targetX padding fallback will be 0
-      const { result: r2 } = setup({ ...defaultProps, container, direction: 'vertical', scrollPaddingStart: 10 });
-      await nextTick();
-      r2.scrollToOffset(100, 100);
-      await nextTick();
-      expect(container.scrollTo).toHaveBeenCalledWith(expect.objectContaining({
-        left: 100,
-      }));
-    });
+      result.scrollToIndex(20, 0, { align: 'start', behavior: 'auto' });
 
-    it('should handle scrollToOffset with window fallback when container is missing', async () => {
-      const { result } = setup({ ...defaultProps, container: undefined });
       await nextTick();
-      result.scrollToOffset(100, 200);
       await nextTick();
+
       expect(window.scrollTo).toHaveBeenCalled();
+      expect(result.scrollDetails.value.currentIndex).toBe(20);
+      wrapper.unmount();
     });
 
-    it('should handle scrollToIndex with null indices', async () => {
-      const { result } = setup({ ...defaultProps });
-      result.scrollToIndex(null, null);
-      await nextTick();
-      result.scrollToIndex(10, null);
+    it('clears pendingScroll when scrollToOffset is called', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+      });
+
       await nextTick();
-      result.scrollToIndex(null, 10);
       await nextTick();
-    });
-
-    it('should handle scrollToIndex auto alignment', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500, configurable: true });
-      Object.defineProperty(container, 'clientWidth', { value: 500, configurable: true });
 
-      const { result } = setup({ ...defaultProps, container, itemSize: 50 });
+      // Set a pending scroll
+      result.scrollToIndex(50, null, { align: 'start', behavior: 'smooth' });
       await nextTick();
 
-      // Scroll down so some items are above
-      result.scrollToIndex(20, 0, 'start');
+      // Call scrollToOffset
+      result.scrollToOffset(null, 100);
       await nextTick();
 
-      // Auto align: already visible
-      result.scrollToIndex(20, null, 'auto');
+      // Wait for scroll timeout (250ms)
+      await new Promise((resolve) => setTimeout(resolve, 300));
       await nextTick();
 
-      // Auto align: above viewport (scroll up)
-      result.scrollToIndex(5, null, 'auto');
-      await nextTick();
+      // The index 50 should NOT be corrected back because pendingScroll was cleared
+      expect(window.scrollY).toBe(100);
+      wrapper.unmount();
+    });
 
-      // Auto align: below viewport (scroll down)
-      result.scrollToIndex(50, null, 'auto');
-      await nextTick();
+    it('triggers correction when viewport dimensions change', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items: mockItems,
+      });
 
-      // Horizontal auto align
-      const { result: r_horiz } = setup({ ...defaultProps, direction: 'horizontal', container, itemSize: 100 });
       await nextTick();
-
-      r_horiz.scrollToIndex(0, 20, 'start');
       await nextTick();
 
-      r_horiz.scrollToIndex(null, 5, 'auto');
+      // Scroll to item 50 auto
+      result.scrollToIndex(50, null, { align: 'auto', behavior: 'auto' });
       await nextTick();
 
-      r_horiz.scrollToIndex(null, 50, 'auto');
-      await nextTick();
-    });
+      const initialScrollY = window.scrollY;
+      expect(initialScrollY).toBe(2050);
+
+      // Simulate viewport height decreasing
+      Object.defineProperty(document.documentElement, 'clientHeight', { configurable: true, value: 485 });
+      window.dispatchEvent(new Event('resize'));
 
-    it('should handle scrollToIndex with various alignments', async () => {
-      const { result } = setup({ ...defaultProps });
-      result.scrollToIndex(50, 0, 'center');
-      await nextTick();
-      result.scrollToIndex(50, 0, 'end');
       await nextTick();
-      result.scrollToIndex(50, 0, { x: 'center', y: 'end' });
       await nextTick();
+
+      // It should have corrected to: 2500 - (485 - 50) = 2065.
+      expect(window.scrollY).toBe(2065);
+      wrapper.unmount();
     });
 
-    it('should handle scrollToOffset with window container', async () => {
-      const { result } = setup({ ...defaultProps, container: window });
-      result.scrollToOffset(null, 100);
-      expect(window.scrollTo).toHaveBeenCalledWith(expect.objectContaining({ top: 100 }));
+    it('triggers correction when container dimensions change', async () => {
+      const container = document.createElement('div');
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 500, writable: true });
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500, writable: true });
 
-      result.scrollToOffset(null, 200, { behavior: 'smooth' });
-      expect(window.scrollTo).toHaveBeenCalledWith(expect.objectContaining({ top: 200, behavior: 'smooth' }));
-    });
+      const { result, wrapper } = setup({
+        container,
+        itemSize: 50,
+        items: mockItems,
+      });
 
-    it('should handle scrollToIndex with auto alignment and axis preservation', async () => {
-      const { result } = setup({ ...defaultProps });
-      // Axis preservation (null index)
-      result.scrollToIndex(10, null, 'auto');
       await nextTick();
-      result.scrollToIndex(null, 5, 'auto');
       await nextTick();
-    });
-
-    it('should handle scrollToOffset with nulls to keep current position', async () => {
-      const { result } = setup({ ...defaultProps, container: window });
-      window.scrollX = 50;
-      window.scrollY = 60;
 
-      // Pass null to keep current Y while updating X
-      result.scrollToOffset(100, null);
-      expect(window.scrollTo).toHaveBeenCalledWith(expect.objectContaining({ left: 100 }));
+      // Change dimensions
+      Object.defineProperty(container, 'clientHeight', { value: 800 });
+      Object.defineProperty(container, 'clientWidth', { value: 800 });
+      triggerResize(container, 800, 800);
 
-      // Pass null to keep current X while updating Y
-      result.scrollToOffset(null, 200);
-      expect(window.scrollTo).toHaveBeenCalledWith(expect.objectContaining({ top: 200 }));
-    });
+      await nextTick();
+      await nextTick();
 
-    it('should handle scrollToOffset with both axes', async () => {
-      const { result } = setup({ ...defaultProps });
-      result.scrollToOffset(100, 200);
-      expect(window.scrollTo).toHaveBeenCalledWith(expect.objectContaining({ left: 100, top: 200 }));
+      expect(result.scrollDetails.value.displayViewportSize.height).toBe(800);
+      wrapper.unmount();
     });
+  });
 
-    it('should handle scrollToOffset fallback when scrollTo is missing', async () => {
-      const container = document.createElement('div');
-      (container as unknown as { scrollTo: unknown; }).scrollTo = undefined;
-      const { result } = setup({ ...defaultProps, container });
-
-      result.scrollToOffset(100, 200);
-      expect(container.scrollTop).toBe(200);
-      expect(container.scrollLeft).toBe(100);
-
-      // X only
-      result.scrollToOffset(300, null);
-      expect(container.scrollLeft).toBe(300);
-
-      // Y only
-      result.scrollToOffset(null, 400);
-      expect(container.scrollTop).toBe(400);
-    });
+  describe('dynamic sizing & prepending', () => {
+    it('handles dynamic item sizes', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 0, // dynamic
+        items: mockItems,
+      });
 
-    it('should stop programmatic scroll', async () => {
-      const { result } = setup(defaultProps);
-      result.scrollToIndex(10, null, { behavior: 'smooth' });
-      expect(result.scrollDetails.value.isProgrammaticScroll).toBe(true);
+      await nextTick();
+      await nextTick();
 
-      result.stopProgrammaticScroll();
-      expect(result.scrollDetails.value.isProgrammaticScroll).toBe(false);
-    });
+      // Initial estimate 100 * 40 = 4000
+      expect(result.totalHeight.value).toBe(4000);
 
-    it('should handle scrollToIndex with element container having scrollTo', async () => {
-      const container = document.createElement('div');
-      container.scrollTo = vi.fn();
-      const { result } = setup({ ...defaultProps, container });
+      result.updateItemSize(0, 100, 100);
       await nextTick();
 
-      result.scrollToIndex(10, 0, { behavior: 'auto' });
-      await nextTick();
-      expect(container.scrollTo).toHaveBeenCalled();
+      // Now 1*100 + 99*40 = 4060
+      expect(result.totalHeight.value).toBe(4060);
+      wrapper.unmount();
     });
 
-    it('should handle scrollToIndex fallback when scrollTo is missing', async () => {
-      const container = document.createElement('div');
-      (container as unknown as { scrollTo: unknown; }).scrollTo = undefined;
-      const { result } = setup({ ...defaultProps, container });
-      await nextTick();
-
-      // row only
-      result.scrollToIndex(10, null, { behavior: 'auto' });
-      await nextTick();
-      expect(container.scrollTop).toBeGreaterThan(0);
+    it('updates item sizes and compensates scroll position', async () => {
+      const { result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 0,
+        items: mockItems,
+      });
 
-      // col only
-      const { result: resH } = setup({ ...defaultProps, container, direction: 'horizontal' });
       await nextTick();
-      resH.scrollToIndex(null, 10, { behavior: 'auto' });
       await nextTick();
-      expect(container.scrollLeft).toBeGreaterThan(0);
-    });
 
-    it('should skip undefined items in renderedItems', async () => {
-      const items = Array.from({ length: 10 }) as unknown[];
-      items[ 0 ] = { id: 0 };
-      // other indices are undefined
-      const { result } = setup({ ...defaultProps, items, itemSize: 50 });
+      // Scroll to item 10 (10 * 40 = 400px)
+      Object.defineProperty(window, 'scrollY', { configurable: true, value: 400, writable: true });
+      document.dispatchEvent(new Event('scroll'));
       await nextTick();
-      // only index 0 should be rendered
-      expect(result.renderedItems.value.length).toBe(1);
-      expect(result.renderedItems.value[ 0 ]?.index).toBe(0);
-    });
-  });
 
-  describe('event handling and viewport', () => {
-    it('should handle window scroll events', async () => {
-      setup({ ...defaultProps });
-      window.scrollX = 150;
-      window.scrollY = 250;
-      window.dispatchEvent(new Event('scroll'));
+      // Update item 0 (above viewport) from 40 to 100
+      result.updateItemSize(0, 100, 100);
       await nextTick();
-    });
 
-    it('should cover fallback branches for unknown targets and directions', async () => {
-      // 1. Unknown container type (hits 408, 445, 513, 718 else branches)
-      const unknownContainer = {
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-      } as unknown as HTMLElement;
+      // Scroll position should have been adjusted by 60px
+      expect(window.scrollY).toBe(460);
+      wrapper.unmount();
+    });
 
-      const { result } = setup({
-        ...defaultProps,
-        container: unknownContainer,
-        hostElement: document.createElement('div'),
+    it('supports batched updateItemSizes', async () => {
+      const { result, wrapper } = setup({
+        itemSize: 0,
+        items: mockItems,
       });
       await nextTick();
+      result.updateItemSizes([
+        { index: 0, inlineSize: 100, blockSize: 100 },
+        { index: 1, inlineSize: 100, blockSize: 100 },
+      ]);
+      await nextTick();
+      expect(result.getRowHeight(0)).toBe(100);
+      expect(result.getRowHeight(1)).toBe(100);
+      wrapper.unmount();
+    });
 
-      result.scrollToIndex(10, 0);
-      result.scrollToOffset(100, 100);
-      result.updateHostOffset();
-
-      // 2. Invalid direction (hits 958 else branch)
-      const { result: r2 } = setup({
-        ...defaultProps,
-        direction: undefined as unknown as 'vertical',
-        stickyIndices: [ 0 ],
+    it('ignores out of bounds updates in updateItemSize', async () => {
+      const { result, wrapper } = setup({
+        itemSize: 0,
+        items: mockItems,
       });
       await nextTick();
-      window.dispatchEvent(new Event('scroll'));
+      const initialHeight = result.scrollDetails.value.totalSize.height;
+      result.updateItemSize(1000, 100, 100); // Out of bounds
       await nextTick();
-      expect(r2.renderedItems.value.find((i) => i.index === 0)).toBeDefined();
-
-      // 3. Unknown target in handleScroll (hits 1100 else branch)
-      const container = document.createElement('div');
-      setup({ ...defaultProps, container });
-      const event = new Event('scroll');
-      Object.defineProperty(event, 'target', { value: { } });
-      container.dispatchEvent(event);
+      expect(result.scrollDetails.value.totalSize.height).toBe(initialHeight);
+      wrapper.unmount();
     });
 
-    it('should cleanup events and observers when container changes', async () => {
-      const container = document.createElement('div');
-      const removeSpy = vi.spyOn(container, 'removeEventListener');
-      const { props } = setup({ ...defaultProps, container });
-      await nextTick();
+    it('updates column sizes from row element children', async () => {
+      const { result, wrapper } = setup({
+        columnCount: 5,
+        columnWidth: 0,
+        direction: 'both',
+        items: mockItems,
+      });
 
-      // Change container to trigger cleanup of old one
-      props.value.container = document.createElement('div');
       await nextTick();
 
-      expect(removeSpy).toHaveBeenCalledWith('scroll', expect.any(Function));
-    });
+      const rowEl = document.createElement('div');
+      const cell0 = document.createElement('div');
+      cell0.dataset.colIndex = '0';
+      Object.defineProperty(cell0, 'getBoundingClientRect', {
+        value: () => ({ width: 120 }),
+      });
+      const cell1 = document.createElement('div');
+      cell1.dataset.colIndex = '1';
+      Object.defineProperty(cell1, 'getBoundingClientRect', {
+        value: () => ({ width: 180 }),
+      });
+      rowEl.appendChild(cell0);
+      rowEl.appendChild(cell1);
+
+      result.updateItemSizes([ {
+        blockSize: 50,
+        element: rowEl,
+        index: 0,
+        inlineSize: 0,
+      } ]);
 
-    it('should cleanup when unmounted and container is window', async () => {
-      const { wrapper } = setup({ ...defaultProps, container: window });
       await nextTick();
+      expect(result.getColumnWidth(0)).toBe(120);
+      expect(result.getColumnWidth(1)).toBe(180);
       wrapper.unmount();
     });
 
-    it('should cleanup when unmounted', async () => {
-      const container = document.createElement('div');
-      const removeSpy = vi.spyOn(container, 'removeEventListener');
-      const { wrapper } = setup({ ...defaultProps, container });
+    it('updates column sizes from row element', async () => {
+      const { result, wrapper } = setup({
+        columnCount: 5,
+        columnWidth: 0, // dynamic
+        direction: 'both',
+        items: mockItems,
+      });
+
       await nextTick();
 
-      wrapper.unmount();
-      expect(removeSpy).toHaveBeenCalledWith('scroll', expect.any(Function));
-    });
+      const rowEl = document.createElement('div');
+      const cell0 = document.createElement('div');
+      cell0.dataset.colIndex = '0';
+      Object.defineProperty(cell0, 'getBoundingClientRect', {
+        value: () => ({ width: 150 }),
+      });
+      rowEl.appendChild(cell0);
 
-    it('should handle document scroll events', async () => {
-      setup({ ...defaultProps });
-      document.dispatchEvent(new Event('scroll'));
-      await nextTick();
-    });
+      result.updateItemSizes([ {
+        blockSize: 100,
+        element: rowEl,
+        index: 0,
+        inlineSize: 0,
+      } ]);
 
-    it('should handle scroll events on container element', async () => {
-      const container = document.createElement('div');
-      setup({ ...defaultProps, container });
-      Object.defineProperty(container, 'scrollTop', { value: 100 });
-      container.dispatchEvent(new Event('scroll'));
       await nextTick();
+      expect(result.getColumnWidth(0)).toBe(150);
+      wrapper.unmount();
     });
 
-    it('should update viewport size on container resize', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientWidth', { value: 500, writable: true });
-      Object.defineProperty(container, 'clientHeight', { value: 500, writable: true });
-      const { result } = setup({ ...defaultProps, container });
-      await nextTick();
-      expect(result.scrollDetails.value.viewportSize.width).toBe(500);
+    it('restores scroll position when items are prepended', async () => {
+      const items = Array.from({ length: 20 }, (_, i) => ({ id: i }));
+      const { props, result, wrapper } = setup({
+        container: window,
+        direction: 'vertical',
+        itemSize: 50,
+        items,
+        restoreScrollOnPrepend: true,
+      });
 
-      Object.defineProperty(container, 'clientWidth', { value: 800 });
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(container));
-      if (observer) {
-        observer.trigger([ { target: container } ]);
-      }
       await nextTick();
-      expect(result.scrollDetails.value.viewportSize.width).toBe(800);
-    });
+      await nextTick();
 
-    it('should handle isScrolling timeout', async () => {
-      vi.useFakeTimers();
-      const container = document.createElement('div');
-      const { result } = setup({ ...defaultProps, container });
-      container.dispatchEvent(new Event('scroll'));
+      // Scroll to index 5 (250px)
+      result.scrollToOffset(0, 250, { behavior: 'auto' });
       await nextTick();
-      expect(result.scrollDetails.value.isScrolling).toBe(true);
-      vi.advanceTimersByTime(250);
       await nextTick();
-      expect(result.scrollDetails.value.isScrolling).toBe(false);
-      vi.useRealTimers();
-    });
 
-    it('should handle container change in mount watcher', async () => {
-      const { props } = setup({ ...defaultProps });
+      expect(window.scrollY).toBe(250);
+
+      // Prepend 2 items (100px)
+      props.value.items = [ { id: -1 }, { id: -2 }, ...items ];
+
       await nextTick();
-      props.value.container = null;
       await nextTick();
-      props.value.container = window;
       await nextTick();
-    });
 
-    it('should handle window resize events', async () => {
-      setup({ ...defaultProps, container: window });
-      Object.defineProperty(window, 'innerWidth', { configurable: true, value: 1200 });
-      window.dispatchEvent(new Event('resize'));
-      await nextTick();
+      // Scroll should be adjusted to 350
+      expect(window.scrollY).toBe(350);
+      wrapper.unmount();
     });
 
-    it('should cover handleScroll with document target', async () => {
-      setup({ ...defaultProps, container: window });
-      document.dispatchEvent(new Event('scroll'));
-      await nextTick();
-    });
+    it('restores horizontal scroll position when items are prepended', async () => {
+      const initialItems = Array.from({ length: 10 }, (_, i) => ({ id: i + 5 }));
+      const { result, props, wrapper } = setup({
+        direction: 'horizontal',
+        itemSize: 100,
+        items: initialItems,
+        restoreScrollOnPrepend: true,
+      });
 
-    it('should handle undefined window in handleScroll', async () => {
-      const originalWindow = globalThis.window;
-      const container = document.createElement('div');
-      setup({ ...defaultProps, container });
+      await nextTick();
+      result.scrollToOffset(200, null);
+      await nextTick();
 
-      try {
-        (globalThis as unknown as { window: unknown; }).window = undefined;
-        container.dispatchEvent(new Event('scroll'));
-        await nextTick();
-      } finally {
-        globalThis.window = originalWindow;
-      }
-    });
-  });
+      // Prepend 5 items
+      const newItems = [
+        ...Array.from({ length: 5 }, (_, i) => ({ id: i })),
+        ...initialItems,
+      ];
+      props.value.items = newItems;
 
-  describe('column widths and ranges', () => {
-    it('should handle columnWidth as an array', async () => {
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 4,
-        columnWidth: [ 100, 200 ],
-      });
-      expect(result.getColumnWidth(0)).toBe(100);
-      expect(result.getColumnWidth(1)).toBe(200);
-      expect(result.totalWidth.value).toBe(600);
-    });
+      await nextTick();
+      await nextTick();
 
-    it('should handle columnWidth array fallback for falsy values', async () => {
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 2,
-        columnWidth: [ 0 ] as unknown as number[],
-      });
-      expect(result.getColumnWidth(0)).toBe(100); // DEFAULT_COLUMN_WIDTH
+      // Should have added 5 * 100 = 500px to scroll position
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(700);
+      wrapper.unmount();
     });
 
-    it('should handle columnWidth as a function', async () => {
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 10,
-        columnWidth: (index: number) => (index % 2 === 0 ? 100 : 200),
+    it('handles horizontal dynamic item sizes', async () => {
+      const { result, wrapper } = setup({
+        direction: 'horizontal',
+        itemSize: 0, // dynamic
+        defaultItemSize: 100,
+        items: mockItems,
       });
-      expect(result.getColumnWidth(0)).toBe(100);
-      expect(result.totalWidth.value).toBe(1500); // 5*100 + 5*200 - 0
-    });
 
-    it('should handle getColumnWidth fallback when dynamic', async () => {
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 2,
-        columnWidth: undefined,
-      });
-      expect(result.getColumnWidth(0)).toBe(100);
-    });
+      await nextTick();
 
-    it('should handle columnRange while loop coverage', async () => {
-      const container = document.createElement('div');
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'both',
-        columnCount: 50,
-        columnWidth: undefined,
-        container,
-      });
-      // Initialize some column widths
-      for (let i = 0; i < 20; i++) {
-        const parent = document.createElement('div');
-        const child = document.createElement('div');
-        Object.defineProperty(child, 'offsetWidth', { value: 100 });
-        child.dataset.colIndex = String(i);
-        parent.appendChild(child);
-        result.updateItemSize(0, 100, 50, parent);
-      }
-      await nextTick();
-      expect(result.columnRange.value.end).toBeGreaterThan(result.columnRange.value.start);
-    });
+      // Initially estimated
+      expect(result.getItemSize(0)).toBe(100);
 
-    it('should handle zero column count', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'both', columnCount: 0 });
+      // Update size
+      result.updateItemSize(0, 150, 500);
       await nextTick();
-      expect(result.columnRange.value.end).toBe(0);
-    });
+      expect(result.getItemSize(0)).toBe(150);
+      expect(result.scrollDetails.value.totalSize.width).toBe(150 + 99 * 100);
 
-    it('should cover columnRange safeStart clamp', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'both', columnCount: 10, columnWidth: 100 });
-      await nextTick();
-      expect(result.columnRange.value.start).toBe(0);
+      wrapper.unmount();
     });
   });
 
-  describe('sticky and pushed items', () => {
-    it('should identify sticky items', async () => {
-      const { result } = setup({ ...defaultProps, stickyIndices: [ 0, 10 ] });
-      await nextTick();
+  describe('scroll correction & smooth scrolling', () => {
+    it('handles smooth scroll and waits for it to finish before correcting', async () => {
+      const container = document.createElement('div');
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 500 });
+      container.scrollTo = vi.fn();
 
-      const items = result.renderedItems.value;
-      const item0 = items.find((i) => i.index === 0);
-      const item10 = items.find((i) => i.index === 10);
-      expect(item0?.isSticky).toBe(true);
-      expect(item10?.isSticky).toBe(true);
-    });
+      const { result, wrapper } = setup({
+        container,
+        direction: 'vertical',
+        itemSize: 0,
+        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
+      });
 
-    it('should make sticky items active when scrolled past', async () => {
-      const { result } = setup({ ...defaultProps, stickyIndices: [ 0 ] });
       await nextTick();
-
-      result.scrollToOffset(0, 100);
       await nextTick();
 
-      const item0 = result.renderedItems.value.find((i) => i.index === 0);
-      expect(item0?.isStickyActive).toBe(true);
-    });
-
-    it('should include current sticky item in rendered items even if range is ahead', async () => {
-      const { result } = setup({ ...defaultProps, stickyIndices: [ 0 ], bufferBefore: 0 });
+      // Start a smooth scroll
+      result.scrollToIndex(50, null, { behavior: 'smooth' });
+      // Simulate scroll event to set isScrolling = true
+      container.dispatchEvent(new Event('scroll'));
       await nextTick();
 
-      // Scroll to index 20. Range starts at 20.
-      result.scrollToIndex(20, 0, { align: 'start', behavior: 'auto' });
+      // Simulate measurement update while scrolling
+      result.updateItemSize(0, 100, 100);
       await nextTick();
 
-      expect(result.scrollDetails.value.range.start).toBe(20);
-      const item0 = result.renderedItems.value.find((i) => i.index === 0);
-      expect(item0).toBeDefined();
-      expect(item0?.isStickyActive).toBe(true);
-    });
+      expect(container.scrollTo).toHaveBeenCalledTimes(1);
 
-    it('should push sticky item when next sticky item approaches (vertical)', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500 });
-      Object.defineProperty(container, 'scrollTop', { value: 480, writable: true });
-      const { result } = setup({ ...defaultProps, container, stickyIndices: [ 0, 10 ], itemSize: 50 });
-      // We need to trigger scroll to update scrollY
-      container.dispatchEvent(new Event('scroll'));
+      // End scroll by waiting for timeout (default 250ms)
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await nextTick();
 
-      const item0 = result.renderedItems.value.find((i) => i.index === 0);
-      expect(item0!.offset.y).toBeLessThanOrEqual(450);
+      // Now correction should trigger
+      expect(container.scrollTo).toHaveBeenCalledTimes(2);
+      wrapper.unmount();
     });
 
-    it('should push sticky item when next sticky item approaches (horizontal)', async () => {
+    it('performs scroll correction when item sizes change during/after scrollToIndex', async () => {
       const container = document.createElement('div');
-      Object.defineProperty(container, 'clientWidth', { value: 500 });
-      Object.defineProperty(container, 'scrollLeft', { value: 480, writable: true });
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 500 });
+      let scrollTop = 0;
+      Object.defineProperty(container, 'scrollTop', {
+        configurable: true,
+        get: () => scrollTop,
+        set: (val) => { scrollTop = val; },
+      });
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.top !== undefined) {
+          scrollTop = options.top;
+        }
+        container.dispatchEvent(new Event('scroll'));
+      });
 
-      const { result } = setup({
-        ...defaultProps,
-        direction: 'horizontal',
+      const { result, wrapper } = setup({
         container,
-        stickyIndices: [ 0, 10 ],
-        itemSize: 50,
-        columnGap: 0,
+        direction: 'vertical',
+        itemSize: 0,
+        items: mockItems,
+        defaultItemSize: 40,
       });
-      container.dispatchEvent(new Event('scroll'));
-
-      const item0 = result.renderedItems.value.find((i) => i.index === 0);
-      expect(item0!.offset.x).toBeLessThanOrEqual(450);
-    });
 
-    it('should handle dynamic sticky item pushing in vertical mode', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500 });
-      Object.defineProperty(container, 'scrollTop', { value: 380, writable: true });
+      await nextTick();
+      await nextTick();
 
-      const { result } = setup({
-        ...defaultProps,
-        container,
-        itemSize: undefined, // dynamic
-        stickyIndices: [ 0, 10 ],
-      });
-
-      // Item 0 is sticky. Item 10 is next sticky.
-      // Default size = 40.
-      // nextStickyY = itemSizesY.query(10) = 400.
-      // distance = 400 - 380 = 20.
-      // 20 < 40 (item 0 height), so it should be pushed.
-      // stickyOffset.y = -(40 - 20) = -20.
-      const stickyItem = result.renderedItems.value.find((i) => i.index === 0);
-      expect(stickyItem?.stickyOffset.y).toBe(-20);
-    });
+      result.scrollToIndex(50, null, { align: 'start', behavior: 'auto' });
+      await nextTick();
+      await nextTick();
 
-    it('should handle dynamic sticky item pushing in horizontal mode', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientWidth', { value: 500 });
-      Object.defineProperty(container, 'scrollLeft', { value: 380, writable: true });
+      expect(scrollTop).toBe(2000);
 
-      const { result } = setup({
-        ...defaultProps,
-        container,
-        direction: 'horizontal',
-        itemSize: undefined, // dynamic
-        stickyIndices: [ 0, 10 ],
-      });
+      // Update item 10 from 40 to 100. Shift item 50 down by 60px.
+      result.updateItemSize(10, 100, 100);
+      await nextTick();
+      await nextTick();
 
-      // nextStickyX = itemSizesX.query(10) = 400.
-      // distance = 400 - 380 = 20.
-      // 20 < 40, so stickyOffset.x = -20.
-      const stickyItem = result.renderedItems.value.find((i) => i.index === 0);
-      expect(stickyItem?.stickyOffset.x).toBe(-20);
+      expect(scrollTop).toBe(2060);
+      wrapper.unmount();
     });
-  });
 
-  describe('scroll restoration', () => {
-    it('should restore scroll position when items are prepended', async () => {
-      vi.useFakeTimers();
+    it('performs scroll correction for "end" alignment when item sizes change', async () => {
       const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500 });
-      Object.defineProperty(container, 'scrollTop', { value: 100, writable: true });
-      container.scrollTo = vi.fn().mockImplementation((options) => {
-        container.scrollTop = options.top;
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 500 });
+      let scrollTop = 0;
+      Object.defineProperty(container, 'scrollTop', {
+        configurable: true,
+        get: () => scrollTop,
+        set: (val) => { scrollTop = val; },
+      });
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.top !== undefined) {
+          scrollTop = options.top;
+        }
+        container.dispatchEvent(new Event('scroll'));
       });
 
-      const items = Array.from({ length: 50 }, (_, i) => ({ id: i }));
-      const { result, props } = setup({
-        ...defaultProps,
-        items,
+      const { result, wrapper } = setup({
         container,
-        itemSize: 50,
-        restoreScrollOnPrepend: true,
+        direction: 'vertical',
+        itemSize: 0,
+        items: mockItems,
+        defaultItemSize: 40,
       });
-      container.dispatchEvent(new Event('scroll'));
+
+      await nextTick();
+      await nextTick();
+
+      result.scrollToIndex(50, null, { align: 'end', behavior: 'auto' });
+      await nextTick();
       await nextTick();
 
-      expect(result.scrollDetails.value.scrollOffset.y).toBe(100);
+      expect(scrollTop).toBe(1540);
 
-      // Prepend 2 items
-      const newItems = [ { id: -1 }, { id: -2 }, ...items ];
-      props.value.items = newItems;
+      result.updateItemSize(50, 100, 100);
       await nextTick();
-      // Trigger initializeSizes
       await nextTick();
 
-      // Should have adjusted scroll by 2 * 50 = 100px. New scrollTop should be 200.
-      expect(container.scrollTop).toBe(200);
-      vi.useRealTimers();
+      expect(scrollTop).toBe(1600);
+      wrapper.unmount();
     });
 
-    it('should restore scroll position when items are prepended (horizontal)', async () => {
-      vi.useFakeTimers();
+    it('correctly scrolls to the end of a dynamic list with corrections', async () => {
       const container = document.createElement('div');
-      Object.defineProperty(container, 'clientWidth', { value: 500 });
-      Object.defineProperty(container, 'scrollLeft', { value: 100, writable: true });
-      container.scrollTo = vi.fn().mockImplementation((options) => {
-        container.scrollLeft = options.left;
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 500 });
+      let scrollTop = 0;
+      Object.defineProperty(container, 'scrollTop', {
+        configurable: true,
+        get: () => scrollTop,
+        set: (val) => { scrollTop = val; },
+      });
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.top !== undefined) {
+          scrollTop = options.top;
+        }
+        container.dispatchEvent(new Event('scroll'));
       });
 
-      const items = Array.from({ length: 50 }, (_, i) => ({ id: i }));
-      const { result, props } = setup({
-        ...defaultProps,
-        direction: 'horizontal',
-        items,
+      const { result, wrapper } = setup({
         container,
-        itemSize: 50,
-        restoreScrollOnPrepend: true,
+        direction: 'vertical',
+        itemSize: 0,
+        items: mockItems,
+        defaultItemSize: 40,
       });
-      container.dispatchEvent(new Event('scroll'));
+
+      await nextTick();
       await nextTick();
 
-      expect(result.scrollDetails.value.scrollOffset.x).toBe(100);
+      result.scrollToIndex(99, null, { align: 'end', behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+      expect(scrollTop).toBe(3500);
 
-      // Prepend 2 items
-      const newItems = [ { id: -1 }, { id: -2 }, ...items ];
-      props.value.items = newItems;
+      const updates = Array.from({ length: 90 }, (_, i) => ({ index: i, inlineSize: 100, blockSize: 50 }));
+      result.updateItemSizes(updates);
       await nextTick();
       await nextTick();
 
-      expect(container.scrollLeft).toBe(200);
-      vi.useRealTimers();
+      expect(scrollTop).toBe(4400);
+      wrapper.unmount();
     });
+  });
 
-    it('should restore scroll position with itemSize as function when prepending', async () => {
-      vi.useFakeTimers();
+  describe('sticky elements', () => {
+    it('renders sticky indices correctly using optimized search', async () => {
       const container = document.createElement('div');
-      Object.defineProperty(container, 'scrollTop', { value: 100, writable: true });
-      container.scrollTo = vi.fn().mockImplementation((options) => {
-        container.scrollTop = options.top;
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 200 });
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.left !== undefined) {
+          container.scrollLeft = options.left;
+        }
+        if (options.top !== undefined) {
+          container.scrollTop = options.top;
+        }
+        container.dispatchEvent(new Event('scroll'));
       });
 
-      const items = Array.from({ length: 50 }, (_, i) => ({ id: i }));
-      const { props } = setup({
-        ...defaultProps,
-        items,
+      const { result, wrapper } = setup({
         container,
-        itemSize: (item: { id: number; }) => (item.id < 0 ? 100 : 50),
-        restoreScrollOnPrepend: true,
+        direction: 'vertical',
+        itemSize: 50,
+        items: Array.from({ length: 20 }, (_, i) => ({ id: i })),
+        stickyIndices: [ 0, 10, 19 ],
+        bufferBefore: 0,
+        bufferAfter: 0,
       });
-      await nextTick();
 
-      // Prepend 1 item with id -1 (size 100)
-      const newItems = [ { id: -1 }, ...items ];
-      props.value.items = newItems;
       await nextTick();
       await nextTick();
 
-      // Should have adjusted scroll by 100px. New scrollTop should be 200.
-      expect(container.scrollTop).toBe(200);
-      vi.useRealTimers();
-    });
+      expect(result.renderedItems.value.map((i) => i.index)).toEqual([ 0, 1, 2, 3 ]);
 
-    it('should NOT restore scroll position when restoreScrollOnPrepend is false', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'scrollTop', { value: 100, writable: true });
-      const items = Array.from({ length: 50 }, (_, i) => ({ id: i }));
-      const { props } = setup({ ...defaultProps, items, container, restoreScrollOnPrepend: false });
+      container.scrollTop = 100;
+      container.dispatchEvent(new Event('scroll'));
       await nextTick();
-
-      const newItems = [ { id: -1 }, ...items ];
-      props.value.items = newItems;
       await nextTick();
-      await nextTick();
-      expect(container.scrollTop).toBe(100);
-    });
 
-    it('should NOT restore scroll position when first item does not match', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'scrollTop', { value: 100, writable: true });
-      const items = Array.from({ length: 50 }, (_, i) => ({ id: i }));
-      const { props } = setup({ ...defaultProps, items, container, restoreScrollOnPrepend: true });
-      await nextTick();
+      const indices2 = result.renderedItems.value.map((i) => i.index).sort((a, b) => a - b);
+      expect(indices2).toEqual([ 0, 2, 3, 4, 5 ]);
+      expect(result.renderedItems.value.find((i) => i.index === 0)?.isStickyActive).toBe(true);
 
-      const newItems = [ { id: -1 }, { id: 9999 } ];
-      props.value.items = newItems;
-      await nextTick();
+      container.scrollTop = 500;
+      container.dispatchEvent(new Event('scroll'));
       await nextTick();
-      expect(container.scrollTop).toBe(100);
-    });
-
-    it('should update pendingScroll rowIndex when items are prepended', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500, configurable: true });
-      Object.defineProperty(container, 'scrollHeight', { value: 5000, configurable: true });
-      const { result, props } = setup({ ...defaultProps, container, restoreScrollOnPrepend: true });
       await nextTick();
 
-      result.scrollToIndex(10, null, { behavior: 'smooth' });
-      props.value.items = [ { id: -1 }, ...props.value.items ];
-      await nextTick();
+      const indices3 = result.renderedItems.value.map((i) => i.index).sort((a, b) => a - b);
+      expect(indices3).toContain(0);
+      expect(indices3).toContain(10);
+      expect(indices3).toContain(11);
+      expect(indices3).toContain(12);
+      expect(indices3).toContain(13);
+      wrapper.unmount();
     });
-  });
 
-  describe('advanced logic and edge cases', () => {
-    it('should trigger scroll correction when isScrolling becomes false', async () => {
-      vi.useFakeTimers();
-      const { result } = setup({ ...defaultProps, container: window, itemSize: undefined });
-      await nextTick();
-      result.scrollToIndex(10, 0, 'start');
-      document.dispatchEvent(new Event('scroll'));
-      expect(result.scrollDetails.value.isScrolling).toBe(true);
-      vi.advanceTimersByTime(250);
-      await nextTick();
-      expect(result.scrollDetails.value.isScrolling).toBe(false);
-      vi.useRealTimers();
-    });
+    it('renders sticky items that are before the visible range', async () => {
+      const { result, wrapper } = setup({
+        direction: 'vertical',
+        itemSize: 100,
+        items: Array.from({ length: 50 }, (_, i) => ({ id: i })),
+        stickyIndices: [ 0 ],
+        bufferBefore: 0,
+        bufferAfter: 0,
+      });
 
-    it('should trigger scroll correction when treeUpdateFlag changes', async () => {
-      const { result } = setup({ ...defaultProps, itemSize: undefined });
       await nextTick();
-      result.scrollToIndex(10, 0, 'start');
-      // Trigger tree update
-      result.updateItemSize(5, 100, 100);
       await nextTick();
-    });
 
-    it('should cover updateHostOffset when container is window', async () => {
-      const { result, props } = setup({ ...defaultProps, container: window });
-      const host = document.createElement('div');
-      props.value.hostElement = host;
+      result.scrollToOffset(null, 1000, { behavior: 'auto' });
       await nextTick();
-      result.updateHostOffset();
-    });
-
-    it('should cover updateHostOffset when container is hostElement', async () => {
-      const host = document.createElement('div');
-      const { result } = setup({ ...defaultProps, container: host, hostElement: host });
       await nextTick();
-      result.updateHostOffset();
-    });
 
-    it('should handle updateHostOffset with window fallback when container is missing', async () => {
-      const { result, props } = setup({ ...defaultProps, container: undefined });
-      const host = document.createElement('div');
-      props.value.hostElement = host;
-      await nextTick();
-      result.updateHostOffset();
+      const renderedIndices = result.renderedItems.value.map((i) => i.index);
+      expect(renderedIndices).toContain(0);
+      expect(result.renderedItems.value.find((i) => i.index === 0)?.isStickyActive).toBe(true);
+      wrapper.unmount();
     });
 
-    it('should correctly calculate hostOffset when container is an HTMLElement', async () => {
-      const container = document.createElement('div');
-      const hostElement = document.createElement('div');
-
-      container.getBoundingClientRect = vi.fn(() => ({ top: 100, left: 100, bottom: 200, right: 200, width: 100, height: 100, x: 100, y: 100, toJSON: () => '' }));
-      hostElement.getBoundingClientRect = vi.fn(() => ({ top: 150, left: 150, bottom: 200, right: 200, width: 50, height: 50, x: 150, y: 150, toJSON: () => '' }));
-      Object.defineProperty(container, 'scrollTop', { value: 50, writable: true, configurable: true });
+    it('handles horizontal sticky items', async () => {
+      const { result, wrapper } = setup({
+        direction: 'horizontal',
+        itemSize: 100,
+        stickyIndices: [ 0 ],
+        items: mockItems,
+      });
 
-      const { result } = setup({ ...defaultProps, container, hostElement });
       await nextTick();
-      result.updateHostOffset();
-      expect(result.scrollDetails.value.scrollOffset.y).toBeDefined();
-    });
 
-    it('should cover refresh method', async () => {
-      const { result } = setup({ ...defaultProps, itemSize: 0 });
-      result.updateItemSize(0, 100, 100);
+      result.scrollToOffset(200, null);
       await nextTick();
-      expect(result.totalHeight.value).toBe(4060);
 
-      result.refresh();
-      await nextTick();
-      expect(result.totalHeight.value).toBe(4000);
+      const item0 = result.renderedItems.value.find((i) => i.index === 0);
+      expect(item0?.isStickyActive).toBe(true);
+
+      wrapper.unmount();
     });
 
-    it('should trigger scroll correction on tree update with string alignment', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500, configurable: true });
-      Object.defineProperty(container, 'scrollHeight', { value: 5000, configurable: true });
-      const { result } = setup({ ...defaultProps, container, itemSize: undefined });
-      // Set a pending scroll with string alignment
-      result.scrollToIndex(10, null, 'start');
+    describe('sticky footer & header scrollToIndex', () => {
+      const stickyMockItems = Array.from({ length: 10 }, (_, i) => ({ id: i }));
+
+      it('scrolls to the last item correctly with sticky footer and hostOffset', async () => {
+        const hostRef = document.createElement('div');
+        const hostElement = document.createElement('div');
+        vi.spyOn(hostRef, 'getBoundingClientRect').mockReturnValue({
+          top: 0,
+          left: 0,
+          bottom: 500,
+          right: 500,
+          width: 500,
+          height: 500,
+        } as DOMRect);
+        vi.spyOn(hostElement, 'getBoundingClientRect').mockReturnValue({
+          top: 50,
+          left: 0,
+          bottom: 550,
+          right: 500,
+          width: 500,
+          height: 500,
+        } as DOMRect);
+
+        const { result, wrapper } = setup({
+          container: hostRef,
+          hostRef,
+          hostElement,
+          direction: 'vertical',
+          itemSize: 50,
+          items: stickyMockItems,
+          stickyStart: { y: 50 }, // 50px sticky header
+          stickyEnd: { y: 50 }, // 50px sticky footer
+        });
 
-      // Trigger tree update
-      result.updateItemSize(0, 100, 100);
-      await nextTick();
-    });
+        await nextTick();
+        await nextTick();
+        result.updateHostOffset();
 
-    it('should trigger scroll correction on tree update with pending scroll', async () => {
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500, configurable: true });
-      Object.defineProperty(container, 'scrollHeight', { value: 5000, configurable: true });
-      const { result } = setup({ ...defaultProps, container, itemSize: undefined });
-      // Set a pending scroll
-      result.scrollToIndex(10, null, { behavior: 'smooth' });
+        expect(result.totalHeight.value).toBe(600);
 
-      // Trigger tree update
-      result.updateItemSize(0, 100, 100);
-      await nextTick();
-    });
+        result.scrollToIndex(9, 0, { align: 'end', behavior: 'auto' });
 
-    it('should trigger scroll correction when scrolling stops with pending scroll', async () => {
-      vi.useFakeTimers();
-      const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500, configurable: true });
-      Object.defineProperty(container, 'scrollHeight', { value: 5000, configurable: true });
-      const { result } = setup({ ...defaultProps, container, itemSize: undefined });
-      result.scrollToIndex(10, null, { behavior: 'smooth' });
+        await nextTick();
+        await nextTick();
 
-      // Start scrolling
-      container.dispatchEvent(new Event('scroll'));
-      await nextTick();
-      expect(result.scrollDetails.value.isScrolling).toBe(true);
+        expect(hostRef.scrollTop).toBe(100);
+        expect(result.renderedItems.value.map((i) => i.index)).toContain(9);
 
-      // Wait for scroll timeout
-      vi.advanceTimersByTime(250);
-      await nextTick();
-      expect(result.scrollDetails.value.isScrolling).toBe(false);
-      vi.useRealTimers();
-    });
+        wrapper.unmount();
+      });
 
-    it('should update totals when function-based itemSize dependencies change and refresh is called', async () => {
-      const defaultHeight = ref(50);
-      const getRowHeight = () => defaultHeight.value;
+      it('renders the last item when scrolled to the end with sticky footer', async () => {
+        const { result, wrapper } = setup({
+          container: window,
+          direction: 'vertical',
+          itemSize: 50,
+          items: stickyMockItems,
+          stickyEnd: { y: 50 },
+        });
 
-      const propsValue = ref({
-        items: mockItems,
-        direction: 'vertical' as const,
-        itemSize: getRowHeight,
-      }) as Ref<VirtualScrollProps<unknown>>;
+        await nextTick();
+        await nextTick();
 
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalHeight.value).toBe(5000); // 100 * 50
+        window.scrollTo({ top: 50 });
+        await nextTick();
+        await nextTick();
 
-      defaultHeight.value = 60;
-      // Total height should still be 5000 because getRowHeight reference didn't change
-      // and initializeSizes hasn't been called automatically.
-      expect(result.totalHeight.value).toBe(5000);
+        expect(result.renderedItems.value.map((i) => i.index)).toContain(9);
 
-      result.refresh();
-      await nextTick();
-      expect(result.totalHeight.value).toBe(6000);
+        wrapper.unmount();
+      });
     });
+  });
 
-    it('should update totals via measurements even if itemSize is a function', async () => {
-      const getRowHeight = () => 50;
+  describe('rtl support', () => {
+    it('detects RTL mode and handles scroll position accordingly', async () => {
+      const container = document.createElement('div');
+      container.setAttribute('dir', 'rtl');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      let scrollLeft = 0;
+      Object.defineProperty(container, 'scrollLeft', {
+        configurable: true,
+        get: () => scrollLeft,
+        set: (val) => { scrollLeft = val; },
+      });
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.left !== undefined) {
+          scrollLeft = options.left;
+        }
+        if (options.top !== undefined) {
+          container.scrollTop = options.top;
+        }
+        container.dispatchEvent(new Event('scroll'));
+      });
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => {
+        const dir = el === container ? 'rtl' : 'ltr';
+        return {
+          get direction() { return dir; },
+        } as unknown as CSSStyleDeclaration;
+      });
 
-      const propsValue = ref({
+      const { result, wrapper } = setup({
+        container,
+        direction: 'horizontal',
+        itemSize: 100,
         items: mockItems,
-        direction: 'vertical' as const,
-        itemSize: getRowHeight,
-      }) as Ref<VirtualScrollProps<unknown>>;
+      });
 
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalHeight.value).toBe(5000);
+      await nextTick();
+      await nextTick();
 
-      // Simulate ResizeObserver measurement
-      result.updateItemSizes([ { index: 0, inlineSize: 100, blockSize: 70 } ]);
+      expect(result.isRtl.value).toBe(true);
+
+      container.scrollLeft = -100;
+      container.dispatchEvent(new Event('scroll'));
       await nextTick();
 
-      // Item 0 is now 70 instead of 50. Total: 50 * 99 + 70 = 4950 + 70 = 5020.
-      expect(result.totalHeight.value).toBe(5020);
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(100);
+
+      result.scrollToIndex(null, 2, { align: 'start', behavior: 'auto' });
+      expect(container.scrollLeft).toBe(-200);
+      wrapper.unmount();
+      styleSpy.mockRestore();
     });
 
-    it('should update totals via measurements even if columnWidth is a function', async () => {
-      const getColWidth = () => 100;
+    it('detects RTL mode change on a parent element', async () => {
+      const parent = document.createElement('div');
+      const container = document.createElement('div');
+      parent.appendChild(container);
+
+      vi.useFakeTimers();
+
+      const spy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => ({
+        get direction() {
+          let current: HTMLElement | null = el as HTMLElement;
+          while (current) {
+            if (current.getAttribute('dir') === 'rtl') {
+              return 'rtl';
+            }
+            current = current.parentElement;
+          }
+          return 'ltr';
+        },
+      } as unknown as CSSStyleDeclaration));
 
-      const propsValue = ref({
+      const { result, wrapper } = setup({
+        container,
+        direction: 'horizontal',
         items: mockItems,
-        direction: 'both' as const,
-        columnCount: 5,
-        columnWidth: getColWidth,
-        itemSize: 50,
-      }) as Ref<VirtualScrollProps<unknown>>;
+      });
 
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalWidth.value).toBe(500);
+      await nextTick();
+      await nextTick();
+
+      expect(result.isRtl.value).toBe(false);
 
-      // Simulate ResizeObserver measurement on a cell
-      // We need to provide an element with data-col-index
-      const element = document.createElement('div');
-      const cell = document.createElement('div');
-      cell.dataset.colIndex = '0';
-      Object.defineProperty(cell, 'offsetWidth', { value: 120 });
-      element.appendChild(cell);
+      parent.setAttribute('dir', 'rtl');
 
-      result.updateItemSizes([ { index: 0, inlineSize: 120, blockSize: 50, element } ]);
+      vi.advanceTimersByTime(1000);
       await nextTick();
 
-      // Column 0 is now 120 instead of 100. Total: 100 * 4 + 120 = 520.
-      expect(result.totalWidth.value).toBe(520);
+      expect(result.isRtl.value).toBe(true);
+
+      wrapper.unmount();
+      spy.mockRestore();
+      vi.useRealTimers();
     });
-  });
 
-  // eslint-disable-next-line test/prefer-lowercase-title
-  describe('SSR support', () => {
-    it('should handle colBuffer when ssrRange is present and not scrolling', async () => {
-      vi.useFakeTimers();
+    it('updates host offset and direction reactively', async () => {
       const container = document.createElement('div');
-      Object.defineProperty(container, 'clientWidth', { value: 500, configurable: true });
-      Object.defineProperty(container, 'scrollLeft', { value: 0, writable: true, configurable: true });
-      container.scrollTo = vi.fn().mockImplementation((options) => {
-        if (options.left !== undefined) {
-          Object.defineProperty(container, 'scrollLeft', { value: options.left, writable: true, configurable: true });
-        }
-      });
+      const hostRef = document.createElement('div');
+      const hostElement = document.createElement('div');
 
-      const { result } = setup({
-        ...defaultProps,
-        container,
-        direction: 'both',
-        columnCount: 20,
-        columnWidth: 100,
-        ssrRange: { start: 0, end: 10, colStart: 1, colEnd: 2 },
-        initialScrollIndex: 0,
-      });
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 500 });
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
 
-      await nextTick(); // onMounted schedules hydration
-      await nextTick(); // hydration tick 1
-      await nextTick(); // hydration tick 2 (isHydrating = false)
+      let currentDir = 'ltr';
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation(() => ({
+        get direction() { return currentDir; },
+      } as unknown as CSSStyleDeclaration));
 
-      expect(result.isHydrated.value).toBe(true);
+      const { result, wrapper } = setup({
+        container,
+        hostRef,
+        hostElement,
+        items: mockItems,
+        itemSize: 50,
+      });
 
-      // Scroll to col 5 (offset 500)
-      result.scrollToIndex(null, 5, { align: 'start', behavior: 'auto' });
       await nextTick();
-
-      vi.runAllTimers(); // Clear isScrolling timeout
       await nextTick();
 
-      // start = findLowerBound(500) = 5.
-      // colBuffer should be 0 because ssrRange is present and isScrolling is false.
-      expect(result.columnRange.value.start).toBe(5);
+      vi.spyOn(hostRef, 'getBoundingClientRect').mockReturnValue({
+        left: 10,
+        top: 20,
+        toJSON: () => {},
+      } as DOMRect);
+      vi.spyOn(hostElement, 'getBoundingClientRect').mockReturnValue({
+        left: 15,
+        top: 25,
+        toJSON: () => {},
+      } as DOMRect);
+      vi.spyOn(container, 'getBoundingClientRect').mockReturnValue({
+        left: 0,
+        top: 0,
+        toJSON: () => {},
+      } as DOMRect);
 
-      // Now trigger a scroll to make isScrolling true
-      container.dispatchEvent(new Event('scroll'));
+      result.updateHostOffset();
       await nextTick();
-      // isScrolling is now true. colBuffer should be 2.
-      expect(result.columnRange.value.start).toBe(3);
-      vi.useRealTimers();
+
+      expect(result.scrollDetails.value.displayScrollOffset.x).toBe(0);
+
+      currentDir = 'rtl';
+      result.updateDirection();
+      expect(result.isRtl.value).toBe(true);
+      wrapper.unmount();
+      styleSpy.mockRestore();
     });
 
-    it('should handle bufferBefore when ssrRange is present and not scrolling', async () => {
-      vi.useFakeTimers();
+    it('updates host offset but not scroll logical position when RTL changes in vertical mode', async () => {
       const container = document.createElement('div');
-      Object.defineProperty(container, 'clientHeight', { value: 500 });
-      Object.defineProperty(container, 'scrollTop', { value: 0, writable: true, configurable: true });
-      container.scrollTo = vi.fn().mockImplementation((options) => {
-        if (options.top !== undefined) {
-          Object.defineProperty(container, 'scrollTop', { value: options.top, writable: true, configurable: true });
-        }
-      });
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 1000 });
 
-      const { result } = setup({
-        ...defaultProps,
+      vi.spyOn(container, 'getBoundingClientRect').mockReturnValue({
+        left: 0,
+        right: 1000,
+        top: 0,
+        bottom: 500,
+        width: 1000,
+        height: 500,
+      } as DOMRect);
+
+      const hostElement = document.createElement('div');
+      vi.spyOn(hostElement, 'getBoundingClientRect').mockReturnValue({
+        left: 100,
+        right: 200,
+        top: 0,
+        bottom: 50,
+        width: 100,
+        height: 50,
+      } as DOMRect);
+
+      let currentDir = 'ltr';
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation(() => ({
+        get direction() { return currentDir; },
+      } as unknown as CSSStyleDeclaration));
+
+      const { result, wrapper } = setup({
         container,
+        hostElement,
+        direction: 'vertical',
+        items: mockItems,
         itemSize: 50,
-        bufferBefore: 5,
-        ssrRange: { start: 0, end: 10 },
-        initialScrollIndex: 10,
       });
 
-      await nextTick(); // schedules hydration
-      await nextTick(); // hydration tick scrolls to 10
       await nextTick();
+      expect(result.componentOffset.x).toBe(100);
 
-      vi.runAllTimers(); // Clear isScrolling timeout
+      currentDir = 'rtl';
+      result.updateDirection();
       await nextTick();
 
-      expect(result.isHydrated.value).toBe(true);
-      // start = floor(500 / 50) = 10.
-      // Since ssrRange is present and isScrolling is false, bufferBefore should be 0.
-      expect(result.renderedItems.value[ 0 ]?.index).toBe(10);
+      expect(result.isRtl.value).toBe(true);
+      expect(result.componentOffset.x).toBe(800);
 
-      // Now trigger a scroll to make isScrolling true
-      container.dispatchEvent(new Event('scroll'));
-      await nextTick();
-      // isScrolling is now true. bufferBefore should be 5.
-      expect(result.renderedItems.value[ 0 ]?.index).toBe(5);
-      vi.useRealTimers();
+      wrapper.unmount();
+      styleSpy.mockRestore();
     });
 
-    it('should handle SSR range in range calculation', () => {
-      const props = ref({
-        items: mockItems,
-        ssrRange: { start: 0, end: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.renderedItems.value.length).toBe(10);
-    });
+    it('calculates host offset correctly in RTL mode', async () => {
+      const container = document.createElement('div');
+      container.setAttribute('dir', 'rtl');
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.left !== undefined) {
+          Object.defineProperty(container, 'scrollLeft', { configurable: true, value: options.left, writable: true });
+        }
+        container.dispatchEvent(new Event('scroll'));
+      });
+      const hostElement = document.createElement('div');
+      container.appendChild(hostElement);
 
-    it('should handle SSR range in columnRange calculation', () => {
-      const props = ref({
-        items: mockItems,
-        columnCount: 10,
-        ssrRange: { start: 0, end: 10, colStart: 0, colEnd: 5 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.columnRange.value.end).toBe(5);
-    });
+      Object.defineProperty(container, 'clientHeight', { configurable: true, value: 500 });
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 1000 });
 
-    it('should handle SSR range with colEnd fallback in columnRange calculation', () => {
-      const props = ref({
-        items: mockItems,
-        columnCount: 10,
-        ssrRange: { start: 0, end: 10, colStart: 0, colEnd: 0 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      // colEnd is 0, so it should use columnCount (10)
-      expect(result.columnRange.value.end).toBe(10);
-    });
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => {
+        const dir = el === container ? 'rtl' : 'ltr';
+        return {
+          get direction() { return dir; },
+        } as unknown as CSSStyleDeclaration;
+      });
 
-    it('should handle SSR range with both directions for total sizes', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'both',
-        columnCount: 10,
-        columnWidth: 100,
+      const { result, wrapper } = setup({
+        container,
+        hostElement,
+        items: mockItems,
         itemSize: 50,
-        ssrRange: { start: 10, end: 20, colStart: 2, colEnd: 5 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(300); // (5-2) * 100 - gap(0)
-      expect(result.totalHeight.value).toBe(500); // (20-10) * 50 - gap(0)
-    });
-
-    it('should handle SSR range with horizontal direction for total sizes', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
         direction: 'horizontal',
-        itemSize: 50,
-        ssrRange: { start: 10, end: 20 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(500); // (20-10) * 50 - gap(0)
-    });
-
-    it('should handle SSR range with vertical offset in renderedItems', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'vertical',
-        itemSize: 50,
-        ssrRange: { start: 10, end: 20 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.renderedItems.value[ 0 ]?.offset.y).toBe(0);
-    });
+      });
 
-    it('should handle SSR range with dynamic horizontal offsets in renderedItems', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'horizontal',
-        itemSize: undefined, // dynamic
-        ssrRange: { start: 10, end: 20 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      // ssrOffsetX = itemSizesX.query(10) = 10 * 40 = 400
-      expect(result.renderedItems.value[ 0 ]?.offset.x).toBe(400);
-    });
+      await nextTick();
+      await nextTick();
 
-    it('should handle SSR range with dynamic sizes for total sizes', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'vertical',
-        itemSize: 0,
-        ssrRange: { start: 10, end: 20 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalHeight.value).toBe(400); // (20-10) * 40 - gap(0)
-    });
+      expect(result.isRtl.value).toBe(true);
 
-    it('should handle SSR range with dynamic horizontal sizes for total sizes', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'horizontal',
-        itemSize: 0,
-        ssrRange: { start: 10, end: 20 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(400); // (20-10) * 40 - 0 gap
-    });
+      vi.spyOn(container, 'getBoundingClientRect').mockReturnValue({
+        left: 0,
+        right: 1000,
+        width: 1000,
+        toJSON: () => {},
+      } as DOMRect);
+      vi.spyOn(hostElement, 'getBoundingClientRect').mockReturnValue({
+        left: 200,
+        right: 700,
+        width: 500,
+        toJSON: () => {},
+      } as DOMRect);
 
-    it('should handle SSR range with both directions and dynamic offsets', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'both',
-        columnCount: 10,
-        itemSize: 0,
-        ssrRange: { start: 10, end: 20, colStart: 2, colEnd: 5 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(300); // (5-2) * 100
-      expect(result.totalHeight.value).toBe(400); // (20-10) * 40
-    });
+      Object.defineProperty(container, 'scrollLeft', { configurable: true, value: 0, writable: true });
 
-    it('should scroll to ssrRange on mount', async () => {
-      setup({ ...defaultProps, ssrRange: { start: 50, end: 60 } });
+      result.updateHostOffset();
       await nextTick();
-      expect(window.scrollTo).toHaveBeenCalled();
-    });
 
-    it('should handle SSR range with horizontal direction and colStart', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'horizontal',
-        itemSize: 50,
-        ssrRange: { start: 0, end: 10, colStart: 5 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.renderedItems.value[ 0 ]?.offset.x).toBe(-250);
-    });
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(0);
 
-    it('should handle SSR range with direction "both" and colStart', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'both',
-        columnCount: 20,
-        columnWidth: 100,
-        ssrRange: { start: 0, end: 10, colStart: 5, colEnd: 15 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      // ssrOffsetX = columnSizes.query(5) = 5 * 100 = 500
-      expect(result.renderedItems.value[ 0 ]?.offset.x).toBe(-500);
-    });
+      Object.defineProperty(container, 'scrollLeft', { configurable: true, value: -400, writable: true });
+      container.dispatchEvent(new Event('scroll'));
+      vi.spyOn(hostElement, 'getBoundingClientRect').mockReturnValue({
+        bottom: 500,
+        left: 600,
+        right: 1100,
+        toJSON: () => {},
+        top: 0,
+        width: 500,
+      } as DOMRect);
 
-    it('should handle SSR range with direction "both" and colEnd falsy', () => {
-      const propsValue = ref({
-        columnCount: 10,
-        columnWidth: 100,
-        direction: 'both' as const,
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        ssrRange: { colEnd: 0, colStart: 5, end: 10, start: 0 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      // colEnd is 0, so it should use colCount (10)
-      // totalWidth = columnSizes.query(10) - columnSizes.query(5) = 1000 - 500 = 500
-      expect(result.totalWidth.value).toBe(500);
-    });
+      result.updateHostOffset();
+      await nextTick();
+      await nextTick();
 
-    it('should handle SSR range with colCount > 0 in totalWidth', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'both',
-        columnCount: 10,
-        columnWidth: 100,
-        ssrRange: { start: 0, end: 10, colStart: 0, colEnd: 5 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(500);
-    });
-  });
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(100);
 
-  describe('helpers', () => {
-    it('should handle zero column count in totalWidth', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'both', columnCount: 0 });
-      expect(result.totalWidth.value).toBe(0);
+      result.scrollToIndex(null, 4, { align: 'start', behavior: 'auto' });
+      expect(container.scrollLeft).toBe(-500);
+      wrapper.unmount();
+      styleSpy.mockRestore();
     });
 
-    it('should handle vertical direction in totalWidth', () => {
-      const { result } = setup({ ...defaultProps, direction: 'vertical' });
-      expect(result.totalWidth.value).toBe(0);
-    });
+    it('calculates rendered item offsets correctly in RTL mode when scrolled', async () => {
+      const container = document.createElement('div');
+      container.setAttribute('dir', 'rtl');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
 
-    it('should handle horizontal direction in totalHeight', () => {
-      const { result } = setup({ ...defaultProps, direction: 'horizontal' });
-      expect(result.totalHeight.value).toBe(0);
-    });
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => {
+        const dir = el === container ? 'rtl' : 'ltr';
+        return {
+          get direction() { return dir; },
+        } as unknown as CSSStyleDeclaration;
+      });
 
-    it('should handle zero items in totalWidth/totalHeight', async () => {
-      const { result } = setup({ ...defaultProps, items: [] });
-      expect(result.totalHeight.value).toBe(0);
+      const { result, wrapper } = setup({
+        container,
+        direction: 'horizontal',
+        itemSize: 100,
+        items: mockItems,
+      });
 
-      const { result: rH } = setup({ ...defaultProps, direction: 'horizontal', items: [] });
-      expect(rH.totalWidth.value).toBe(0);
-    });
+      await nextTick();
+      await nextTick();
 
-    it('should cover SSR with zero items/columns', () => {
-      const props = ref({
-        items: [],
-        direction: 'both',
-        columnCount: 0,
-        ssrRange: { start: 0, end: 0, colStart: 0, colEnd: 0 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(0);
-      expect(result.totalHeight.value).toBe(0);
-    });
+      Object.defineProperty(container, 'scrollLeft', { configurable: true, value: -200, writable: true });
+      container.dispatchEvent(new Event('scroll'));
+      await nextTick();
+      await nextTick();
 
-    it('should handle SSR range with both directions and no columns', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'both',
-        columnCount: 0,
-        ssrRange: { start: 10, end: 20, colStart: 0, colEnd: 0 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(0);
-    });
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(200);
 
-    it('should handle SSR range with direction both and colCount > 0 but colEnd <= colStart', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'both',
-        columnCount: 10,
-        ssrRange: { start: 0, end: 10, colStart: 5, colEnd: 5 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(0);
+      const item2 = result.renderedItems.value.find((i) => i.index === 2);
+      expect(item2).toBeDefined();
+      expect(item2?.offset.x).toBe(200);
+      wrapper.unmount();
+      styleSpy.mockRestore();
     });
 
-    it('should handle SSR range with vertical/both and end <= start', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'vertical',
-        ssrRange: { start: 10, end: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalHeight.value).toBe(0);
-    });
+    it('maintains horizontal scroll position when switching between RTL and LTR', async () => {
+      const container = document.createElement('div');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      let scrollLeft = 0;
+      Object.defineProperty(container, 'scrollLeft', {
+        configurable: true,
+        get: () => scrollLeft,
+        set: (val) => { scrollLeft = val; },
+      });
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.left !== undefined) {
+          scrollLeft = options.left;
+        }
+        container.dispatchEvent(new Event('scroll'));
+      });
 
-    it('should handle SSR range with dynamic horizontal sizes for total sizes', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
+      let currentDir = 'ltr';
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation(() => ({
+        get direction() { return currentDir; },
+      } as unknown as CSSStyleDeclaration));
+
+      const { result, wrapper } = setup({
+        container,
         direction: 'horizontal',
-        itemSize: 0,
-        ssrRange: { start: 10, end: 20 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(400); // (20-10) * 40
-    });
+        itemSize: 100,
+        items: mockItems,
+      });
 
-    it('should handle SSR range with both directions and dynamic offsets for total width', () => {
-      const props = ref({
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        direction: 'both',
-        columnCount: 10,
-        itemSize: 0,
-        ssrRange: { start: 10, end: 20, colStart: 2, colEnd: 5 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(props);
-      expect(result.totalWidth.value).toBe(300);
-    });
+      await nextTick();
+      await nextTick();
 
-    it('should handle updateItemSizes with index < 0', async () => {
-      const { result } = setup({ ...defaultProps, itemSize: undefined });
-      result.updateItemSizes([ { index: -1, inlineSize: 100, blockSize: 100 } ]);
+      result.scrollToOffset(200, null, { behavior: 'auto' });
       await nextTick();
-      // Should not change total height
-      expect(result.totalHeight.value).toBe(4000);
-    });
+      expect(scrollLeft).toBe(200);
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(200);
 
-    it('should handle updateItemSizes with direction vertical and dynamic itemSize for X', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'vertical', itemSize: undefined });
-      // Measured Items X should not be updated if direction is vertical
-      result.updateItemSizes([ { index: 0, inlineSize: 100, blockSize: 100 } ]);
+      currentDir = 'rtl';
+      result.updateDirection();
+      await nextTick();
       await nextTick();
-      expect(result.totalWidth.value).toBe(0);
-    });
 
-    it('should handle SSR with horizontal direction and fixedItemSize', () => {
-      const propsValue = ref({
-        direction: 'horizontal' as const,
-        itemSize: 50,
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        ssrRange: { end: 20, start: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalWidth.value).toBe(500); // (20-10) * 50 - 0 gap
-    });
+      expect(result.isRtl.value).toBe(true);
+      expect(scrollLeft).toBe(-200);
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(200);
 
-    it('should handle SSR with vertical direction and fixedItemSize', () => {
-      const propsValue = ref({
-        direction: 'vertical' as const,
-        itemSize: 50,
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        ssrRange: { end: 20, start: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalHeight.value).toBe(500); // (20-10) * 50 - 0 gap
+      wrapper.unmount();
+      styleSpy.mockRestore();
     });
 
-    it('should handle SSR with direction both and fixedItemSize for totalHeight', () => {
-      const propsValue = ref({
-        direction: 'both' as const,
-        columnCount: 10,
-        itemSize: 50,
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        ssrRange: { end: 20, start: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalHeight.value).toBe(500);
-    });
+    it('maintains horizontal scroll position when switching between RTL and LTR with padding', async () => {
+      const container = document.createElement('div');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      let scrollLeft = 0;
+      Object.defineProperty(container, 'scrollLeft', {
+        configurable: true,
+        get: () => scrollLeft,
+        set: (val) => { scrollLeft = val; },
+      });
+      container.scrollTo = vi.fn().mockImplementation((options: ScrollToOptions) => {
+        if (options.left !== undefined) {
+          scrollLeft = options.left;
+        }
+        container.dispatchEvent(new Event('scroll'));
+      });
 
-    it('should handle SSR range with direction both and colEnd falsy', () => {
-      const propsValue = ref({
-        columnCount: 10,
-        columnWidth: 100,
-        direction: 'both' as const,
-        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
-        ssrRange: { colEnd: 0, colStart: 5, end: 10, start: 0 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      // colEnd is 0, so it should use colCount (10)
-      // totalWidth = (10 - 5) * 100 = 500
-      expect(result.totalWidth.value).toBe(500);
-    });
+      let currentDir = 'ltr';
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation(() => ({
+        get direction() { return currentDir; },
+      } as unknown as CSSStyleDeclaration));
 
-    it('should handle updateItemSizes with direction both and dynamic itemSize for Y', async () => {
-      const { result } = setup({ ...defaultProps, direction: 'both', columnCount: 2, itemSize: undefined });
-      // First measurement
-      result.updateItemSizes([ { index: 0, inlineSize: 100, blockSize: 100 } ]);
+      const { result, wrapper } = setup({
+        container,
+        direction: 'horizontal',
+        itemSize: 100,
+        items: Array.from({ length: 10 }, (_, i) => ({ id: i })),
+        scrollPaddingStart: 50,
+      });
+
+      await nextTick();
       await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(100);
 
-      // Increase
-      result.updateItemSizes([ { index: 0, inlineSize: 100, blockSize: 120 } ]);
+      result.scrollToOffset(150, null, { behavior: 'auto' });
       await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(120);
+      expect(scrollLeft).toBe(150);
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(150);
 
-      // Significant decrease
-      result.updateItemSizes([ { index: 0, inlineSize: 100, blockSize: 100 } ]);
+      currentDir = 'rtl';
+      result.updateDirection();
+      await nextTick();
       await nextTick();
-      expect(result.renderedItems.value[ 0 ]!.size.height).toBe(100);
-    });
 
-    it('should handle object padding branches in helpers', () => {
-      expect(getPaddingX({ x: 10 }, 'horizontal')).toBe(10);
-      expect(getPaddingY({ y: 20 }, 'vertical')).toBe(20);
-    });
+      expect(result.isRtl.value).toBe(true);
+      expect(scrollLeft).toBe(-150);
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(150);
 
-    it('should cover totalWidth SSR len <= 0', () => {
-      const propsValue = ref({
-        items: mockItems,
-        direction: 'horizontal' as const,
-        itemSize: 50,
-        ssrRange: { start: 10, end: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalWidth.value).toBe(0);
-    });
+      currentDir = 'ltr';
+      result.updateDirection();
+      await nextTick();
+      await nextTick();
 
-    it('should cover totalWidth SSR end <= start for dynamic sizes', () => {
-      const propsValue = ref({
-        items: mockItems,
-        direction: 'horizontal' as const,
-        itemSize: undefined,
-        ssrRange: { start: 10, end: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalWidth.value).toBe(0);
-    });
+      expect(result.isRtl.value).toBe(false);
+      expect(scrollLeft).toBe(150);
+      expect(result.scrollDetails.value.scrollOffset.x).toBe(150);
 
-    it('should cover totalWidth non-SSR items.length <= 0 for dynamic sizes', () => {
-      const propsValue = ref({
-        items: [],
-        direction: 'horizontal' as const,
-        itemSize: undefined,
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalWidth.value).toBe(0);
+      wrapper.unmount();
+      styleSpy.mockRestore();
     });
+  });
 
-    it('should cover totalHeight SSR len <= 0', () => {
-      const propsValue = ref({
-        items: mockItems,
-        direction: 'vertical' as const,
-        itemSize: 50,
-        ssrRange: { start: 10, end: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalHeight.value).toBe(0);
-    });
+  describe('scaling & large lists', () => {
+    it('syncs display scroll when items count changes in a scaled list', async () => {
+      const props = ref<VirtualScrollProps<MockItem>>({
+        itemSize: 1000,
+        items: Array.from({ length: 30000 }, (_, i) => ({ id: i })), // 30M VU
+      });
+      const result = useVirtualScroll(props);
 
-    it('should cover totalHeight SSR end <= start for dynamic sizes', () => {
-      const propsValue = ref({
-        items: mockItems,
-        direction: 'vertical' as const,
-        itemSize: undefined,
-        ssrRange: { start: 10, end: 10 },
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalHeight.value).toBe(0);
-    });
+      result.scrollToOffset(null, 10000000);
+      await nextTick();
+      await nextTick();
 
-    it('should cover totalHeight non-SSR items.length <= 0 for dynamic sizes', () => {
-      const propsValue = ref({
-        items: [],
-        direction: 'vertical' as const,
-        itemSize: undefined,
-      }) as Ref<VirtualScrollProps<unknown>>;
-      const result = useVirtualScroll(propsValue);
-      expect(result.totalHeight.value).toBe(0);
+      props.value.items = Array.from({ length: 40000 }, (_, i) => ({ id: i }));
+      await nextTick();
+      await nextTick();
+
+      expect(result.scrollDetails.value.scrollOffset.y).toBeCloseTo(10000000, 0);
     });
 
-    describe('internal sizing stabilization and edge cases', () => {
-      const mockItems = Array.from({ length: 10 }, (_, i) => ({ id: i }));
+    describe('coordinate scaling & bounds', () => {
+      it('rendered item offsets do not grow excessively under scaling', async () => {
+        const itemCount = 11000;
+        const itemSize = 1000;
+        const viewportHeight = 500;
+        const items = Array.from({ length: itemCount }, (_, i) => ({ id: i }));
 
-      it('should skip re-initializing sizes for already measured dynamic items', async () => {
-        const props = ref({
-          items: mockItems,
-          direction: 'both' as const,
-          columnCount: 2,
-        }) as Ref<VirtualScrollProps<{ id: number; }>>;
+        const { result, wrapper } = setup({
+          container: window,
+          direction: 'vertical',
+          itemSize,
+          items,
+        });
 
-        const result = useVirtualScroll(props);
         await nextTick();
-
-        // Measure item 0 and col 0
-        const parent = document.createElement('div');
-        const col0 = document.createElement('div');
-        col0.dataset.colIndex = '0';
-        Object.defineProperty(col0, 'offsetWidth', { value: 200 });
-        parent.appendChild(col0);
-
-        result.updateItemSizes([ { index: 0, inlineSize: 200, blockSize: 150, element: parent } ]);
         await nextTick();
 
-        expect(result.getColumnWidth(0)).toBe(200);
-        expect(result.renderedItems.value[ 0 ]?.size.height).toBe(150);
-
-        // Trigger initializeSizes by changing items length
-        props.value.items = Array.from({ length: 11 }, (_, i) => ({ id: i }));
+        // Viewport 500
+        Object.defineProperty(document.documentElement, 'clientHeight', { configurable: true, value: viewportHeight });
+        window.dispatchEvent(new Event('resize'));
         await nextTick();
 
-        // Should NOT reset already measured item 0
-        expect(result.getColumnWidth(0)).toBe(200);
-        expect(result.renderedItems.value[ 0 ]?.size.height).toBe(150);
-      });
-
-      it('should mark items as measured when fixed size matches current size within tolerance', async () => {
-        const props = ref({
-          items: mockItems,
-          direction: 'horizontal' as const,
-          itemSize: 50,
-        }) as Ref<VirtualScrollProps<{ id: number; }>>;
-
-        useVirtualScroll(props);
+        // Scroll to item 100 (virtual 100000)
+        result.scrollToIndex(100, null, { align: 'start', behavior: 'auto' });
         await nextTick();
-
-        // Trigger initializeSizes again with same prop
-        props.value.columnGap = 0;
         await nextTick();
-        // Hits the branch where Math.abs(current - target) <= 0.5
-      });
 
-      it('should mark columns as measured when fixed width matches current width within tolerance', async () => {
-        const props = ref({
-          items: mockItems,
-          direction: 'both' as const,
-          columnCount: 2,
-          columnWidth: 100,
-        }) as Ref<VirtualScrollProps<{ id: number; }>>;
+        const scaleY = result.scaleY.value;
+        const expectedDisplayScroll = 100000 / scaleY;
+        expect(window.scrollY).toBeCloseTo(expectedDisplayScroll, 0);
 
-        useVirtualScroll(props);
-        await nextTick();
+        const item100 = result.renderedItems.value.find((i) => i.index === 100);
+        expect(item100).toBeDefined();
 
-        props.value.columnGap = 0;
-        await nextTick();
+        // item100.offset.y should be (100 * 1000) / scaleY = 100000 / scaleY
+        expect(item100?.offset.y).toBeCloseTo(expectedDisplayScroll, 0);
+
+        wrapper.unmount();
       });
 
-      it('should reset item sizes when switching between horizontal and vertical directions', async () => {
-        const props = ref({
-          items: mockItems,
-          direction: 'horizontal' as const,
-          itemSize: 50,
-        }) as Ref<VirtualScrollProps<{ id: number; }>>;
+      it('does not allow scrolling below the last item when sticky elements are present', async () => {
+        const itemCount = 1000;
+        const itemSize = 50;
+        const headerHeight = 50;
+        const footerHeight = 50;
+        const viewportHeight = 500;
+        const items = Array.from({ length: itemCount }, (_, i) => ({ id: i }));
+
+        const { result, wrapper } = setup({
+          container: window,
+          direction: 'vertical',
+          itemSize,
+          items,
+          stickyStart: { y: headerHeight },
+          stickyEnd: { y: footerHeight },
+        });
 
-        const result = useVirtualScroll(props);
         await nextTick();
-        expect(result.totalWidth.value).toBe(500);
-
-        // Switch to vertical (resets X)
-        props.value.direction = 'vertical';
         await nextTick();
-        expect(result.totalWidth.value).toBe(0);
 
-        // Switch to both
-        props.value.direction = 'both';
-        props.value.columnCount = 10;
-        props.value.columnWidth = 100;
-        await nextTick();
-        expect(result.totalHeight.value).toBe(500);
-        expect(result.totalWidth.value).toBe(1000);
+        expect(result.totalHeight.value).toBe(50100);
 
-        // Switch to horizontal (resets Y)
-        props.value.direction = 'horizontal';
+        result.scrollToIndex(999, null, { align: 'end', behavior: 'auto' });
         await nextTick();
         await nextTick();
-        expect(result.totalHeight.value).toBe(0);
-      });
 
-      it('should skip re-initialization if dynamic size is already measured and non-zero', async () => {
-        const props = ref({
-          items: mockItems,
-          direction: 'horizontal' as const,
-          itemSize: undefined, // dynamic
-        }) as Ref<VirtualScrollProps<{ id: number; }>>;
+        expect(window.scrollY).toBe(49600);
 
-        const result = useVirtualScroll(props);
-        await nextTick();
+        const lastItem = result.renderedItems.value.find((i) => i.index === 999);
+        expect(lastItem).toBeDefined();
 
-        result.updateItemSizes([ { index: 0, inlineSize: 100, blockSize: 50, element: document.createElement('div') } ]);
-        await nextTick();
+        const itemBottomDisplay = lastItem!.offset.y + headerHeight + itemSize;
+        expect(itemBottomDisplay - (window.scrollY + viewportHeight)).toBe(-footerHeight);
 
-        props.value.gap = 1;
-        await nextTick();
+        wrapper.unmount();
+      });
+    });
+  });
 
-        expect(result.totalWidth.value).toBeGreaterThan(0);
+  describe('host element & layout', () => {
+    it('calculates hostRefOffset correctly', async () => {
+      const container = document.createElement('div');
+      const hostRef = document.createElement('div');
+      vi.spyOn(hostRef, 'getBoundingClientRect').mockReturnValue({
+        left: 100,
+        top: 100,
+        width: 100,
+        height: 50,
+      } as DOMRect);
+
+      const { result, wrapper } = setup({
+        container,
+        hostRef,
+        items: mockItems,
+        itemSize: 50,
       });
+
+      await nextTick();
+      result.updateHostOffset();
+
+      expect(result.scrollDetails.value.displayScrollOffset.y).toBe(0);
+      wrapper.unmount();
     });
   });
 });