@pdanpdan/virtual-scroll 0.3.0 → 0.5.0

package/src/components/VirtualScroll.test.ts

@@ -1,980 +1,2332 @@
-import type { ScrollAlignment, ScrollAlignmentOptions, ScrollDetails, ScrollToIndexOptions } from '../composables/useVirtualScroll';
-import type { DOMWrapper, VueWrapper } from '@vue/test-utils';
+import type { ItemSlotProps, ScrollbarSlotProps, ScrollDetails, VirtualScrollInstance } from '../types';
+import type { VueWrapper } from '@vue/test-utils';
+import type { DefineComponent } from 'vue';
 
+/* global ScrollToOptions, ResizeObserverCallback */
 import { mount } from '@vue/test-utils';
-import { beforeEach, describe, expect, it } from 'vitest';
-import { defineComponent, nextTick, ref } from 'vue';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { h, nextTick, ref } from 'vue';
 
+import { displayToVirtual, virtualToDisplay } from '../utils/virtual-scroll-logic';
 import VirtualScroll from './VirtualScroll.vue';
 
-type ResizeObserverCallback = (entries: ResizeObserverEntry[], observer: ResizeObserver) => void;
+// --- Mocks ---
+
+Object.defineProperty(HTMLElement.prototype, 'clientHeight', { configurable: true, value: 500 });
+Object.defineProperty(HTMLElement.prototype, 'clientWidth', { configurable: true, value: 500 });
+Object.defineProperty(HTMLElement.prototype, 'offsetWidth', { configurable: true, value: 500 });
+Object.defineProperty(HTMLElement.prototype, 'offsetHeight', { configurable: true, value: 500 });
+
+HTMLElement.prototype.scrollTo = function (this: HTMLElement, options?: number | ScrollToOptions, y?: number) {
+  if (typeof options === 'object') {
+    if (options.top !== undefined) {
+      this.scrollTop = options.top;
+    }
+    if (options.left !== undefined) {
+      this.scrollLeft = options.left;
+    }
+  } else if (typeof options === 'number' && typeof y === 'number') {
+    this.scrollLeft = options;
+    this.scrollTop = y;
+  }
+  this.dispatchEvent(new (this.ownerDocument?.defaultView?.Event || Event)('scroll'));
+};
+
+HTMLElement.prototype.setPointerCapture = vi.fn();
+HTMLElement.prototype.releasePointerCapture = vi.fn();
 
-// 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, useBorderBox = true) {
+  const obs = observers.find((o) => o.targets.has(el));
+  if (obs) {
+    obs.callback([ {
+      ...(useBorderBox ? { 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);
+  }
+}
 
-  trigger(entries: Partial<ResizeObserverEntry>[]) {
-    this.callback(entries as ResizeObserverEntry[], this as unknown as ResizeObserver);
+// Mock window.scrollTo
+globalThis.window.scrollTo = vi.fn().mockImplementation((options) => {
+  if (options.left !== undefined) {
+    Object.defineProperty(window, 'scrollX', { configurable: true, value: options.left, writable: true });
   }
-} as unknown as typeof ResizeObserver & { instances: ResizeObserverMock[]; };
-
-// eslint-disable-next-line test/prefer-lowercase-title
-describe('VirtualScroll component', () => {
-  const mockItems = Array.from({ length: 100 }, (_, i) => ({ id: i, label: `Item ${ i }` }));
-
-  interface VSInstance {
-    scrollDetails: ScrollDetails<unknown>;
-    scrollToIndex: (rowIndex: number | null, colIndex: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
-    scrollToOffset: (x: number | null, y: number | null, options?: { behavior?: 'auto' | 'smooth'; }) => void;
-    setItemRef: (el: unknown, index: number) => void;
-    stopProgrammaticScroll: () => void;
-    refresh: () => void;
+  if (options.top !== undefined) {
+    Object.defineProperty(window, 'scrollY', { configurable: true, value: options.top, writable: true });
   }
+  document.dispatchEvent(new Event('scroll'));
+});
 
-  interface TestCompInstance {
-    mockItems: typeof mockItems;
-    show: boolean;
-    showFooter: boolean;
-  }
+// --- Tests ---
+
+interface MockItem {
+  id: number;
+  label: string;
+}
+
+describe('virtualScroll', () => {
+  const mockItems: MockItem[] = Array.from({ length: 100 }, (_, i) => ({ id: i, label: `Item ${ i }` }));
+
+  beforeEach(() => {
+    Object.defineProperty(window, 'scrollX', { configurable: true, value: 0, writable: true });
+    Object.defineProperty(window, 'scrollY', { configurable: true, value: 0, writable: true });
+    Object.defineProperty(window, 'innerHeight', { configurable: true, value: 500 });
+    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 500 });
+    vi.useFakeTimers({ toFake: [ 'requestAnimationFrame' ] });
+  });
 
-  describe('rendering and structure', () => {
-    it('should render items correctly', () => {
+  afterEach(() => {
+    observers.length = 0;
+    vi.clearAllMocks();
+    vi.useRealTimers();
+  });
+
+  describe('core rendering & lifecycle', () => {
+    it('renders the visible items', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems,
           itemSize: 50,
+          items: mockItems,
         },
         slots: {
-          item: '<template #item="{ item, index }"><div class="item">{{ index }}: {{ item.label }}</div></template>',
+          item: (props: ItemSlotProps) => {
+            const { index, item } = props as ItemSlotProps<MockItem>;
+            return h('div', { class: 'item' }, `${ index }: ${ item.label }`);
+          },
         },
       });
-      expect(wrapper.findAll('.item').length).toBeGreaterThan(0);
-      expect(wrapper.text()).toContain('0: Item 0');
+
+      await nextTick();
+
+      const items = wrapper.findAll('.item');
+      expect(items.length).toBe(15);
+      expect(items[ 0 ]?.text()).toBe('0: Item 0');
+      expect(items[ 14 ]?.text()).toBe('14: Item 14');
     });
 
-    it('should render header and footer slots', () => {
+    it('updates when items change', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems,
           itemSize: 50,
-        },
-        slots: {
-          header: '<div class="header">Header</div>',
-          footer: '<div class="footer">Footer</div>',
+          items: mockItems.slice(0, 5),
         },
       });
-      expect(wrapper.find('.virtual-scroll-header').exists()).toBe(true);
-      expect(wrapper.find('.header').exists()).toBe(true);
-      expect(wrapper.find('.virtual-scroll-footer').exists()).toBe(true);
-      expect(wrapper.find('.footer').exists()).toBe(true);
+      await nextTick();
+      expect(wrapper.findAll('.virtual-scroll-item').length).toBe(5);
+
+      await wrapper.setProps({ items: mockItems.slice(0, 10) });
+      await nextTick();
+      expect(wrapper.findAll('.virtual-scroll-item').length).toBe(10);
     });
 
-    it('should not render header and footer slots when absent', () => {
+    it('supports horizontal direction', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
+          direction: 'horizontal',
+          itemSize: 100,
           items: mockItems,
-          itemSize: 50,
         },
       });
-      expect(wrapper.find('.virtual-scroll-header').exists()).toBe(false);
-      expect(wrapper.find('.virtual-scroll-footer').exists()).toBe(false);
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+      expect(container.classes()).toContain('virtual-scroll--horizontal');
+      expect((wrapper.find('.virtual-scroll-wrapper').element as HTMLElement).style.inlineSize).toBe('10000px');
+
+      // 500px / 100px = 5 visible
+      // + 5 bufferAfter = 10 total
+      expect(wrapper.findAll('.virtual-scroll-item').length).toBe(10);
     });
 
-    it('should render debug information when debug prop is true', async () => {
+    it('supports grid mode (both directions)', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 5),
+          columnCount: 5,
+          columnWidth: 100,
+          direction: 'both',
           itemSize: 50,
-          debug: true,
+          items: mockItems,
         },
       });
       await nextTick();
-      expect(wrapper.find('.virtual-scroll-debug-info').exists()).toBe(true);
-      expect(wrapper.find('.virtual-scroll-item').classes()).toContain('virtual-scroll--debug');
+      const style = (wrapper.find('.virtual-scroll-wrapper').element as HTMLElement).style;
+      expect(style.blockSize).toBe('5000px');
+      expect(style.inlineSize).toBe('500px');
+
+      // 500px / 50px = 10 visible rows
+      // + 5 bufferAfter = 15 total rows
+      expect(wrapper.findAll('.virtual-scroll-item').length).toBe(15);
     });
 
-    it('should not render debug information when debug prop is false', async () => {
+    it('works with window as container', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 5),
+          container: window,
           itemSize: 50,
-          debug: false,
+          items: mockItems,
         },
       });
       await nextTick();
-      expect(wrapper.find('.virtual-scroll-debug-info').exists()).toBe(false);
-      expect(wrapper.find('.virtual-scroll-item').classes()).not.toContain('virtual-scroll--debug');
+      expect(wrapper.classes()).toContain('virtual-scroll--window');
     });
 
-    it('should handle missing slots gracefully', () => {
+    it('unmounts cleanly', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 1),
-          itemSize: 50,
+          items: mockItems,
         },
       });
-      expect(wrapper.exists()).toBe(true);
+      await nextTick();
+      wrapper.unmount();
+      // no errors should be thrown
     });
 
-    it('should render table correctly', () => {
+    it('handles hostRef change', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 10),
-          itemSize: 50,
-          containerTag: 'table',
-          wrapperTag: 'tbody',
-          itemTag: 'tr',
-        },
-        slots: {
-          item: '<template #item="{ item, index }"><td>{{ index }}</td><td>{{ item.label }}</td></template>',
+          items: mockItems,
+          containerTag: 'div',
         },
       });
-      expect(wrapper.element.tagName).toBe('TABLE');
-      expect(wrapper.find('tbody').exists()).toBe(true);
-      expect(wrapper.find('tr.virtual-scroll-item').exists()).toBe(true);
+      await nextTick();
+      await wrapper.setProps({ containerTag: 'section' });
+      await nextTick();
+      // should have unobserved old and observed new
     });
 
-    it('should render table with header and footer', () => {
+    it('stops active smooth scroll via stopProgrammaticScroll', async () => {
       const wrapper = mount(VirtualScroll, {
-        props: {
-          items: mockItems.slice(0, 10),
-          itemSize: 50,
-          containerTag: 'table',
-          wrapperTag: 'tbody',
-          itemTag: 'tr',
-        },
-        slots: {
-          header: '<tr><th>ID</th></tr>',
-          footer: '<tr><td>Footer</td></tr>',
-        },
+        props: { itemSize: 50, items: mockItems },
       });
-      expect(wrapper.find('thead').exists()).toBe(true);
-      expect(wrapper.find('tfoot').exists()).toBe(true);
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      vs.scrollToIndex(50, null, { behavior: 'smooth' });
+      await nextTick();
+
+      const posBefore = vs.scrollDetails.scrollOffset.y;
+      vs.stopProgrammaticScroll();
+      await nextTick();
+
+      // Should not have moved significantly or at all from where it was stopped
+      expect(vs.scrollDetails.scrollOffset.y).toBe(posBefore);
     });
+  });
 
-    it('should render div header and footer', () => {
+  describe('scrolling interaction', () => {
+    it('scrolls and updates visible items', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 10),
-          containerTag: 'div',
+          itemSize: 50,
+          items: mockItems,
         },
         slots: {
-          header: '<div class="header">Header</div>',
-          footer: '<div class="footer">Footer</div>',
+          item: (props: ItemSlotProps) => {
+            const { item } = props as ItemSlotProps<MockItem>;
+            return h('div', { class: 'item' }, item.label);
+          },
         },
       });
-      expect(wrapper.find('div.virtual-scroll-header').exists()).toBe(true);
-      expect(wrapper.find('div.virtual-scroll-footer').exists()).toBe(true);
+      await nextTick();
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const el = container.element as HTMLElement;
+
+      Object.defineProperty(el, 'scrollTop', { value: 1000, writable: true });
+      await container.trigger('scroll');
+      await nextTick();
+      await nextTick();
+
+      expect(wrapper.text()).toContain('Item 20');
+      expect(wrapper.text()).toContain('Item 15');
+
+      const items = wrapper.findAll('.item');
+      expect(items.length).toBeGreaterThanOrEqual(15);
+      expect(items.length).toBeLessThanOrEqual(25);
     });
 
-    it('should apply sticky classes to header and footer', async () => {
+    it('emits load event when reaching end', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems,
-          stickyHeader: true,
-          stickyFooter: true,
-        },
-        slots: {
-          header: '<div>H</div>',
-          footer: '<div>F</div>',
+          itemSize: 50,
+          items: mockItems.slice(0, 20),
+          loadDistance: 100,
         },
       });
       await nextTick();
-      expect(wrapper.find('.virtual-scroll-header').classes()).toContain('virtual-scroll--sticky');
-      expect(wrapper.find('.virtual-scroll-footer').classes()).toContain('virtual-scroll--sticky');
-    });
-
-    it('should handle switching containerTag', async () => {
-      const wrapper = mount(VirtualScroll, { props: { items: mockItems.slice(0, 10), containerTag: 'div' } });
       await nextTick();
-      await wrapper.setProps({ containerTag: 'table' });
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const el = container.element as HTMLElement;
+
+      expect(wrapper.emitted('load')).toBeUndefined();
+
+      Object.defineProperty(el, 'scrollTop', { value: 450, writable: true });
+      await container.trigger('scroll');
       await nextTick();
-      expect(wrapper.element.tagName).toBe('TABLE');
-      await wrapper.setProps({ containerTag: 'div' });
       await nextTick();
-      expect(wrapper.element.tagName).toBe('DIV');
+
+      expect(wrapper.emitted('load')).toBeDefined();
     });
 
-    it('should render table spacer and items', () => {
+    it('handles wheel when virtual scrollbars are inactive', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 5),
-          containerTag: 'table',
-          wrapperTag: 'tbody',
-          itemTag: 'tr',
-        },
-        slots: {
-          item: '<template #item="{ item }"><td>{{ item.label }}</td></template>',
+          items: mockItems,
+          virtualScrollbar: false,
         },
       });
-      expect(wrapper.find('tr.virtual-scroll-spacer').exists()).toBe(true);
-      expect(wrapper.find('tr.virtual-scroll-item').exists()).toBe(true);
+      await nextTick();
+      await wrapper.find('.virtual-scroll-container').trigger('wheel', { deltaY: 100 });
+      // should just stop programmatic scroll
     });
 
-    it('should handle table rendering without header and footer', async () => {
+    it('should not enter a loop when scrolling to end with dynamic items', async () => {
+      const items = Array.from({ length: 200 }, (_, i) => ({ id: i }));
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 5),
-          containerTag: 'table',
+          items,
+          itemSize: 0, // dynamic
+          defaultItemSize: 40,
         },
       });
+
       await nextTick();
-      expect(wrapper.find('thead').exists()).toBe(false);
-      expect(wrapper.find('tfoot').exists()).toBe(false);
-    });
-
-    it('should cover all template branches for slots and tags', async () => {
-      for (const tag of [ 'div', 'table' ] as const) {
-        for (const direction of [ 'vertical', 'horizontal', 'both' ] as const) {
-          for (const loading of [ true, false ]) {
-            for (const withSlots of [ true, false ]) {
-              const slots = withSlots
-                ? {
-                  header: tag === 'table' ? '<tr><td>H</td></tr>' : '<div>H</div>',
-                  footer: tag === 'table' ? '<tr><td>F</td></tr>' : '<div>F</div>',
-                  loading: tag === 'table' ? '<tr><td>L</td></tr>' : '<div>L</div>',
-                }
-                : {};
-              const wrapper = mount(VirtualScroll, {
-                props: { items: mockItems.slice(0, 1), containerTag: tag, loading, direction },
-                slots,
-              });
-              await nextTick();
-              wrapper.unmount();
-            }
-          }
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+
+      // Press End
+      await wrapper.trigger('keydown', { key: 'End' });
+
+      // Wait for multiple ticks to let the correction logic work
+      for (let i = 0; i < 5; i++) {
+        await nextTick();
+      }
+
+      // Simulate items being measured differently than estimated
+      const rendered = wrapper.findAll('.virtual-scroll-item');
+      for (const item of rendered) {
+        const idx = Number(item.attributes('data-index'));
+        if (idx >= 90) {
+          triggerResize(item.element, 500, 50); // 50 instead of 40
         }
       }
+
+      // Wait for corrections
+      for (let i = 0; i < 5; i++) {
+        await nextTick();
+      }
+
+      const details = vs.scrollDetails;
+      // Should be at the end
+      expect(details.scrollOffset.y).toBeGreaterThanOrEqual(details.totalSize.height - details.viewportSize.height - 1);
+
+      const scrollToIndexSpy = vi.spyOn(vs, 'scrollToIndex');
+
+      await nextTick();
+      await nextTick();
+
+      // Should not be calling scrollToIndex anymore
+      expect(scrollToIndexSpy).not.toHaveBeenCalled();
     });
   });
 
-  describe('styling and dimensions', () => {
-    it('should render items horizontally when direction is horizontal', async () => {
+  describe('keyboard navigation', () => {
+    it('responds to home and end keys in vertical mode', async () => {
       const wrapper = mount(VirtualScroll, {
-        props: {
-          items: Array.from({ length: 10 }, (_, i) => ({ id: i })),
-          itemSize: 100,
-          direction: 'horizontal',
-        },
+        props: { itemSize: 50, items: mockItems },
       });
       await nextTick();
-      const items = wrapper.findAll('.virtual-scroll-item');
-      expect(items.length).toBeGreaterThan(0);
-      const firstItem = items[ 0 ]?.element as HTMLElement;
-      expect(firstItem.style.transform).toBe('translate(0px, 0px)');
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'End' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(4500);
+
+      await container.trigger('keydown', { key: 'Home' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(0);
     });
 
-    it('should handle bidirectional scroll dimensions', async () => {
+    it('responds to arrows in vertical mode', async () => {
       const wrapper = mount(VirtualScroll, {
-        props: {
-          items: Array.from({ length: 10 }, (_, i) => ({ id: i })),
-          itemSize: 100,
-          direction: 'both',
-          columnCount: 5,
-          columnWidth: 150,
-        },
+        props: { itemSize: 50, items: mockItems },
       });
-      const VS_wrapper = wrapper.find('.virtual-scroll-wrapper');
-      const style = (VS_wrapper.element as HTMLElement).style;
-      expect(style.blockSize).toBe('1000px');
-      expect(style.inlineSize).toBe('750px');
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(50);
+
+      await container.trigger('keydown', { key: 'ArrowUp' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(0);
     });
 
-    it('should cover all containerStyle branches', () => {
-      [ 'vertical', 'horizontal', 'both' ].forEach((direction) => {
-        mount(VirtualScroll, { props: { items: mockItems, direction: direction as 'vertical' | 'horizontal' | 'both' } });
-        mount(VirtualScroll, { props: { items: mockItems, direction: direction as 'vertical' | 'horizontal' | 'both', container: document.body } });
-        mount(VirtualScroll, { props: { items: mockItems, direction: direction as 'vertical' | 'horizontal' | 'both', containerTag: 'table' } });
+    it('responds correctly to arrows in rtl mode', async () => {
+      const container = document.createElement('div');
+      container.setAttribute('dir', 'rtl');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      container.scrollTo = vi.fn().mockImplementation((options) => {
+        if (options.left !== undefined) {
+          Object.defineProperty(container, 'scrollLeft', { configurable: true, value: options.left, writable: true });
+        }
+        container.dispatchEvent(new Event('scroll'));
       });
-      mount(VirtualScroll, { props: { items: mockItems, container: null } });
-    });
 
-    it('should cover getItemStyle branches', async () => {
-      const wrapper = mount(VirtualScroll, {
-        props: {
-          items: mockItems.slice(0, 5),
-          itemSize: 50,
-          direction: 'horizontal',
-        },
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => {
+        if (el === container) {
+          return { direction: 'rtl' } as CSSStyleDeclaration;
+        }
+        return { direction: 'ltr' } as CSSStyleDeclaration;
       });
-      await nextTick();
-      const item = wrapper.find('.virtual-scroll-item').element as HTMLElement;
-      expect(item.style.inlineSize).toBe('50px');
-      expect(item.style.blockSize).toBe('100%');
-    });
 
-    it('should cover sticky item style branches in getItemStyle', async () => {
-      const items = Array.from({ length: 10 }, (_, i) => ({ id: i }));
       const wrapper = mount(VirtualScroll, {
         props: {
-          items,
+          container,
           direction: 'horizontal',
-          stickyIndices: [ 0 ],
-          scrollPaddingStart: 10,
+          itemSize: 100,
+          items: mockItems,
         },
       });
+
+      await nextTick();
       await nextTick();
 
-      const stickyItem = wrapper.find('.virtual-scroll-item').element as HTMLElement;
-      // It should be sticky active if we scroll
-      await wrapper.trigger('scroll');
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      vs.updateDirection();
       await nextTick();
+      expect(vs.isRtl).toBe(true);
+
+      const vsContainer = wrapper.find('.virtual-scroll-container');
 
-      expect(stickyItem.style.insetInlineStart).toBe('10px');
+      await vsContainer.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.x).toBeCloseTo(100, 0);
 
-      await wrapper.setProps({ direction: 'vertical', scrollPaddingStart: 20 });
+      await vsContainer.trigger('keydown', { key: 'ArrowRight' });
       await nextTick();
-      expect(stickyItem.style.insetBlockStart).toBe('20px');
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.x).toBeCloseTo(0, 0);
+
+      styleSpy.mockRestore();
     });
 
-    it('should handle custom container element for header/footer padding', async () => {
+    it('aligns partially visible items correctly with arrows in rtl mode', async () => {
       const container = document.createElement('div');
-      const items = Array.from({ length: 10 }, (_, i) => ({ id: i }));
-      mount(VirtualScroll, {
+      container.setAttribute('dir', 'rtl');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      container.scrollTo = vi.fn().mockImplementation((options) => {
+        if (options.left !== undefined) {
+          Object.defineProperty(container, 'scrollLeft', { configurable: true, value: options.left, writable: true });
+        }
+        container.dispatchEvent(new Event('scroll'));
+      });
+
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => {
+        if (el === container) {
+          return { direction: 'rtl' } as CSSStyleDeclaration;
+        }
+        return { direction: 'ltr' } as CSSStyleDeclaration;
+      });
+
+      const wrapper = mount(VirtualScroll, {
         props: {
-          items,
           container,
-          stickyHeader: true,
+          direction: 'horizontal',
+          itemSize: 100,
+          items: mockItems,
         },
       });
+
+      await nextTick();
       await nextTick();
-      // This covers the branch where container is NOT host element and NOT window
-    });
 
-    it('should handle stickyHeader with window container', async () => {
-      const items = Array.from({ length: 10 }, (_, i) => ({ id: i }));
-      mount(VirtualScroll, {
-        props: {
-          items,
-          container: window,
-          stickyHeader: true,
-        },
-        slots: { header: '<div>H</div>' },
-      });
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      vs.updateDirection();
+      await nextTick();
+
+      vs.scrollToOffset(50, null);
+      await nextTick();
+      await nextTick();
+
+      const vsContainer = wrapper.find('.virtual-scroll-container');
+
+      await vsContainer.trigger('keydown', { key: 'ArrowRight' });
+      await nextTick();
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.x).toBeCloseTo(0, 0);
+
+      await wrapper.setProps({ itemSize: 150 });
       await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentEndIndex).toBe(3);
+
+      await vsContainer.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.x).toBeCloseTo(100, 0);
+
+      styleSpy.mockRestore();
     });
 
-    it('should cover object padding branches in virtualScrollProps', () => {
-      mount(VirtualScroll, {
-        props: {
-          items: mockItems.slice(0, 1),
-          scrollPaddingStart: { x: 10, y: 20 },
-          scrollPaddingEnd: { x: 30, y: 40 },
-        },
+    it('scrolls to next item with arrowleft when current item is already at the left edge (rtl)', async () => {
+      const container = document.createElement('div');
+      container.setAttribute('dir', 'rtl');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      container.scrollTo = vi.fn().mockImplementation((options) => {
+        if (options.left !== undefined) {
+          Object.defineProperty(container, 'scrollLeft', { configurable: true, value: options.left, writable: true });
+        }
+        container.dispatchEvent(new Event('scroll'));
       });
-      mount(VirtualScroll, {
+
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => {
+        if (el === container) {
+          return { direction: 'rtl' } as CSSStyleDeclaration;
+        }
+        return { direction: 'ltr' } as CSSStyleDeclaration;
+      });
+
+      const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 1),
+          container,
           direction: 'horizontal',
-          scrollPaddingStart: 10,
-          scrollPaddingEnd: 20,
+          itemSize: 100,
+          items: mockItems,
         },
       });
-    });
-  });
 
-  describe('keyboard navigation', () => {
-    let wrapper: VueWrapper<VSInstance>;
-    let container: DOMWrapper<Element>;
-    let el: HTMLElement;
+      await nextTick();
+      await nextTick();
 
-    beforeEach(async () => {
-      wrapper = mount(VirtualScroll, {
-        props: {
-          items: mockItems,
-          itemSize: 50,
-          direction: 'vertical',
-        },
-      }) as unknown as VueWrapper<VSInstance>;
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      vs.updateDirection();
+      await nextTick();
+
+      vs.scrollToIndex(null, 4, { align: 'end', behavior: 'auto' });
+      await nextTick();
       await nextTick();
-      container = wrapper.find('.virtual-scroll-container');
-      el = container.element as HTMLElement;
 
-      // Mock dimensions
-      Object.defineProperty(el, 'clientHeight', { value: 500, configurable: true });
-      Object.defineProperty(el, 'clientWidth', { value: 500, configurable: true });
-      Object.defineProperty(el, 'offsetHeight', { value: 500, configurable: true });
-      Object.defineProperty(el, 'offsetWidth', { value: 500, configurable: true });
+      expect(vs.scrollDetails.currentEndColIndex).toBe(4);
+      expect(vs.scrollDetails.scrollOffset.x).toBe(0);
 
-      const observers = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.filter((i) => i.targets.has(el));
-      observers.forEach((i) => i.trigger([ { target: el, contentRect: { width: 500, height: 500 } as unknown as DOMRectReadOnly } ]));
+      const containerEl = wrapper.find('.virtual-scroll-container');
+      await containerEl.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
       await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.x).toBe(100);
+      styleSpy.mockRestore();
     });
 
-    it('should handle Home key', async () => {
-      el.scrollTop = 1000;
-      el.scrollLeft = 500;
-      await container.trigger('keydown', { key: 'Home' });
+    it('scrolls to previous item with arrowup when current item is already at the top', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems },
+      });
       await nextTick();
-      expect(el.scrollTop).toBe(0);
-      expect(el.scrollLeft).toBe(0);
-    });
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      vs.scrollToIndex(2, null, { align: 'start', behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(100);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      await container.trigger('keydown', { key: 'ArrowUp' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(50);
+    });
+
+    it('scrolls to next item with arrowright when current item is already at the right edge (ltr)', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 100, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      vs.scrollToIndex(4, null, { align: 'end', behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentEndIndex).toBe(4);
+      expect(vs.scrollDetails.scrollOffset.x).toBe(0);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      await container.trigger('keydown', { key: 'ArrowRight' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.x).toBe(100);
+    });
+
+    it('scrolls to next item with arrowdown when current item is already at the bottom edge', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      vs.scrollToIndex(9, null, { align: 'end', behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentEndIndex).toBe(9);
+      expect(vs.scrollDetails.scrollOffset.y).toBe(0);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(50);
+    });
+
+    it('does not scroll with arrowdown when already at the very last item', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      vs.scrollToOffset(null, 4500, { behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentEndIndex).toBe(99);
+      expect(vs.scrollDetails.scrollOffset.y).toBe(4500);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(4500);
+    });
+
+    it('does not scroll with arrowright when already at the very last item (horizontal ltr)', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 100, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      vs.scrollToOffset(9500, null, { behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentEndColIndex).toBe(99);
+      expect(vs.scrollDetails.scrollOffset.x).toBe(9500);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      await container.trigger('keydown', { key: 'ArrowRight' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.x).toBe(9500);
+    });
+
+    it('does not scroll with arrowleft when already at the very last item (horizontal rtl)', async () => {
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockReturnValue({
+        direction: 'rtl',
+      } as CSSStyleDeclaration);
+
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 100, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      vs.scrollToOffset(9500, null, { behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentEndColIndex).toBe(99);
+      expect(vs.scrollDetails.scrollOffset.x).toBe(9500);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      await container.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.x).toBe(9500);
+      styleSpy.mockRestore();
+    });
+
+    it('responds to pageup and pagedown in vertical mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'PageDown' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(500);
+
+      await container.trigger('keydown', { key: 'PageUp' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(0);
+    });
+
+    it('responds to home and end keys in horizontal mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 100, items: mockItems },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'End' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(9500);
+
+      await container.trigger('keydown', { key: 'Home' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(0);
+    });
+
+    it('responds to arrows in horizontal mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 100, items: mockItems },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'ArrowRight' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(100);
+
+      await container.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(0);
+    });
+
+    it('responds to pageup and pagedown in horizontal mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 100, items: mockItems },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'PageDown' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(500);
+
+      await container.trigger('keydown', { key: 'PageUp' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(0);
+    });
+
+    it('disables smooth scroll for large distances (home/end)', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 50,
+          items: Array.from({ length: 1000 }, (_, i) => ({ id: i, label: `Item ${ i }` })),
+          container: window,
+        },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      const scrollToSpy = vi.spyOn(window, 'scrollTo');
+
+      await container.trigger('keydown', { key: 'End' });
+      await nextTick();
+
+      expect(scrollToSpy).toHaveBeenCalledWith(expect.objectContaining({
+        behavior: 'auto',
+      }));
+
+      scrollToSpy.mockClear();
+      await container.trigger('keydown', { key: 'Home' });
+      await nextTick();
+
+      expect(scrollToSpy).toHaveBeenCalledWith(expect.objectContaining({
+        behavior: 'auto',
+      }));
+    });
+
+    it('responds to home and end keys in grid mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          columnCount: 10,
+          columnWidth: 100,
+          direction: 'both',
+          itemSize: 50,
+          items: mockItems,
+        },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'End' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(4500);
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(500);
+
+      await container.trigger('keydown', { key: 'Home' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(0);
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(0);
+    });
+
+    it('responds to all arrows in grid mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          columnCount: 10,
+          columnWidth: 100,
+          direction: 'both',
+          itemSize: 50,
+          items: mockItems,
+        },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await container.trigger('keydown', { key: 'ArrowRight' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(50);
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(100);
+
+      await container.trigger('keydown', { key: 'ArrowUp' });
+      await container.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.y).toBe(0);
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(0);
+    });
+
+    it('aligns items precisely with arrow keys', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 100,
+          items: mockItems,
+        },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      vs.scrollToOffset(null, 50, { behavior: 'auto' });
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.y).toBe(50);
+
+      await container.trigger('keydown', { key: 'ArrowUp' });
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.y).toBe(0);
+
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.y).toBe(100);
+
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.y).toBe(200);
+    });
+
+    it('aligns partially visible items at the bottom with arrow down', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      // viewport 500. item 9 ends at 500.
+      // scroll to 25. item 9 now ends at 525 (partially cut off).
+      vs.scrollToOffset(null, 25);
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentEndIndex).toBe(10); // item 10 is at 500-550
+
+      // item 10 is partially visible at bottom. ArrowDown should align it to end.
+      const container = wrapper.find('.virtual-scroll-container');
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await nextTick();
+      await nextTick();
+
+      // item 10 ends at 550. viewport 500. targetEnd = 550 - 500 = 50.
+      expect(vs.scrollDetails.scrollOffset.y).toBe(50);
+    });
+
+    it('aligns partially visible columns with arrowleft and arrowright in ltr', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 100, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+
+      // Viewport 500. Scroll to 50.
+      // Item 0 (0-100) is partially visible at start.
+      // Item 5 (500-600) is partially visible at end.
+      vs.scrollToOffset(50, null);
+      await nextTick();
+      await nextTick();
+
+      const container = wrapper.find('.virtual-scroll-container');
+
+      // 1. ArrowLeft should align item 0 to start
+      await container.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.x).toBe(0);
+
+      // Reset
+      vs.scrollToOffset(50, null);
+      await nextTick();
+      await nextTick();
+
+      // 2. ArrowRight should align item 5 to end
+      await container.trigger('keydown', { key: 'ArrowRight' });
+      await nextTick();
+      await nextTick();
+      // item 5 ends at 600. viewport 500. targetEnd = 600 - 500 = 100.
+      expect(vs.scrollDetails.scrollOffset.x).toBe(100);
+    });
+
+    it('aligns partially visible columns with arrowleft and arrowright in rtl', async () => {
+      const container = document.createElement('div');
+      container.setAttribute('dir', 'rtl');
+      Object.defineProperty(container, 'clientWidth', { configurable: true, value: 500 });
+      container.scrollTo = vi.fn().mockImplementation((options) => {
+        if (options.left !== undefined) {
+          Object.defineProperty(container, 'scrollLeft', { configurable: true, value: options.left, writable: true });
+        }
+        container.dispatchEvent(new Event('scroll'));
+      });
+
+      const styleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => {
+        if (el === container) {
+          return { direction: 'rtl' } as CSSStyleDeclaration;
+        }
+        return { direction: 'ltr' } as CSSStyleDeclaration;
+      });
+
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          container,
+          direction: 'horizontal',
+          itemSize: 100,
+          items: mockItems,
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      vs.updateDirection();
+      await nextTick();
+
+      // Viewport 500. Logical scroll 50.
+      // Item 0 (0-100) is partially visible at logical START (Right edge).
+      // Item 5 (500-600) is partially visible at logical END (Left edge).
+      vs.scrollToOffset(50, null);
+      await nextTick();
+      await nextTick();
+
+      const vsContainer = wrapper.find('.virtual-scroll-container');
+
+      // 1. ArrowRight in RTL should align item 0 to logical START
+      await vsContainer.trigger('keydown', { key: 'ArrowRight' });
+      await nextTick();
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.x).toBe(0);
+
+      // Reset
+      vs.scrollToOffset(50, null);
+      await nextTick();
+      await nextTick();
+
+      // 2. ArrowLeft in RTL should align item 5 to logical END
+      await vsContainer.trigger('keydown', { key: 'ArrowLeft' });
+      await nextTick();
+      await nextTick();
+      // item 5 ends at 600. viewport 500. targetEnd = 600 - 500 = 100.
+      expect(vs.scrollDetails.scrollOffset.x).toBe(100);
+
+      styleSpy.mockRestore();
+    });
+
+    it('ignores vertical arrows in horizontal mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          items: mockItems,
+          direction: 'horizontal',
+        },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      const scrollToIndexSpy = vi.spyOn(vs, 'scrollToIndex');
+
+      await wrapper.find('.virtual-scroll-container').trigger('keydown', { key: 'ArrowUp' });
+      await wrapper.find('.virtual-scroll-container').trigger('keydown', { key: 'ArrowDown' });
+
+      expect(scrollToIndexSpy).not.toHaveBeenCalled();
+    });
+
+    it('ignores horizontal arrows in vertical mode', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          items: mockItems,
+          direction: 'vertical',
+        },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      const scrollToIndexSpy = vi.spyOn(vs, 'scrollToIndex');
+
+      await wrapper.find('.virtual-scroll-container').trigger('keydown', { key: 'ArrowLeft' });
+      await wrapper.find('.virtual-scroll-container').trigger('keydown', { key: 'ArrowRight' });
+
+      expect(scrollToIndexSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('dynamic sizing & measurements', () => {
+    it('adjusts total size when items are measured', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 0,
+          items: mockItems.slice(0, 10),
+        },
+      });
+      await nextTick();
+
+      expect((wrapper.find('.virtual-scroll-wrapper').element as HTMLElement).style.blockSize).toBe('400px');
+
+      const firstItem = wrapper.find('.virtual-scroll-item[data-index="0"]').element;
+      triggerResize(firstItem, 100, 100);
+      await nextTick();
+      await nextTick();
+
+      expect((wrapper.find('.virtual-scroll-wrapper').element as HTMLElement).style.blockSize).toBe('460px');
+    });
+
+    it('does not allow columns to become 0 width due to 0-size measurements', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          bufferAfter: 0,
+          bufferBefore: 0,
+          columnCount: 10,
+          defaultColumnWidth: 100,
+          direction: 'both',
+          itemSize: 50,
+          items: mockItems,
+        },
+        slots: {
+          item: ({ columnRange, index }: ItemSlotProps) => h('div', {
+            'data-index': index,
+          }, [
+            ...Array.from({ length: columnRange.end - columnRange.start }, (_, i) => h('div', {
+              class: 'cell',
+              'data-col-index': columnRange.start + i,
+            })),
+          ]),
+        },
+      });
+
+      await nextTick();
+
+      const initialWidth = (wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.totalSize.width;
+      expect(initialWidth).toBeGreaterThan(0);
+
+      const row0 = wrapper.find('.virtual-scroll-item[data-index="0"]').element;
+      const cell0 = row0.querySelector('.cell') as HTMLElement;
+      expect(cell0).not.toBeNull();
+
+      triggerResize(cell0, 0, 0);
+
+      await nextTick();
+      await nextTick();
+
+      const currentWidth = (wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.totalSize.width;
+      expect(currentWidth).toBe(initialWidth);
+    });
+
+    it('should not shift horizontally when scrolling vertically even if measurements vary slightly', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          bufferAfter: 0,
+          bufferBefore: 0,
+          columnCount: 10,
+          defaultColumnWidth: 100,
+          direction: 'both',
+          itemSize: 50,
+          items: mockItems,
+        },
+        slots: {
+          item: ({ columnRange, index }: ItemSlotProps) => h('div', {
+            'data-index': index,
+          }, [
+            ...Array.from({ length: columnRange.end - columnRange.start }, (_, i) => h('div', {
+              class: 'cell',
+              'data-col-index': columnRange.start + i,
+            })),
+          ]),
+        },
+      });
+
+      await nextTick();
+
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(0);
+
+      const row0 = wrapper.find('.virtual-scroll-item[data-index="0"]').element;
+      const cells0 = Array.from(row0.querySelectorAll('.cell'));
+
+      triggerResize(row0, 1000, 50);
+      for (const cell of cells0) {
+        triggerResize(cell, 110, 50);
+      }
+
+      await nextTick();
+      await nextTick();
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const el = container.element as HTMLElement;
+      Object.defineProperty(el, 'scrollTop', { configurable: true, value: 1000, writable: true });
+      await container.trigger('scroll');
+
+      await nextTick();
+      await nextTick();
+
+      const row20 = wrapper.find('.virtual-scroll-item[data-index="20"]').element;
+      const cells20 = Array.from(row20.querySelectorAll('.cell'));
+
+      for (const cell of cells20) {
+        triggerResize(cell, 110.1, 50);
+      }
+
+      await nextTick();
+      await nextTick();
+
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(0);
+    });
+
+    it('correctly aligns item 50:50 auto after measurements in dynamic grid', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          bufferAfter: 5,
+          bufferBefore: 5,
+          columnCount: 100,
+          defaultColumnWidth: 120,
+          defaultItemSize: 120,
+          direction: 'both',
+          items: mockItems,
+        },
+        slots: {
+          item: ({ columnRange, index }: ItemSlotProps) => h('div', {
+            'data-index': index,
+          }, [
+            ...Array.from({ length: columnRange.end - columnRange.start }, (_, i) => h('div', {
+              class: 'cell',
+              'data-col-index': columnRange.start + i,
+            })),
+          ]),
+        },
+      });
+
+      await nextTick();
+
+      (wrapper.vm as { scrollToIndex: (r: number, c: number, a: string) => void; }).scrollToIndex(50, 50, 'auto');
+      await nextTick();
+      await nextTick();
+
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(5620);
+
+      const row45El = wrapper.find('.virtual-scroll-item[data-index="45"]').element;
+      const cells45 = Array.from(row45El.querySelectorAll('.cell'));
+
+      for (const cell of cells45) {
+        triggerResize(cell, 150, 120);
+      }
+
+      await nextTick();
+      await nextTick();
+      await nextTick();
+
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await nextTick();
+
+      expect((wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; }).scrollDetails.scrollOffset.x).toBe(5830);
+    });
+
+    it('handles fallback measurement when borderboxsize is missing', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          items: mockItems,
+          itemSize: 0, // dynamic
+        },
+      });
+
+      await nextTick();
+      const item = wrapper.find('.virtual-scroll-item');
+
+      Object.defineProperty(item.element, 'offsetWidth', { value: 500, configurable: true });
+      Object.defineProperty(item.element, 'offsetHeight', { value: 60, configurable: true });
+
+      triggerResize(item.element, 500, 60, false);
+
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      expect(vs.getRowHeight(0)).toBe(60);
+    });
+  });
+
+  describe('sticky elements', () => {
+    it('applies sticky styles to marked items', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 50,
+          items: mockItems,
+          stickyIndices: [ 0 ],
+        },
+      });
+      await nextTick();
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const el = container.element as HTMLElement;
+
+      Object.defineProperty(el, 'scrollTop', { value: 100, writable: true });
+      await container.trigger('scroll');
+      await nextTick();
+      await nextTick();
+
+      const item0 = wrapper.find('.virtual-scroll-item[data-index="0"]');
+      expect(item0.classes()).toContain('virtual-scroll--sticky');
+      expect((item0.element as HTMLElement).style.insetBlockStart).toBe('0px');
+    });
+
+    it('does not gather multiple sticky items at the top', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 50,
+          items: mockItems,
+          stickyIndices: [ 0, 1, 2 ],
+        },
+        slots: {
+          item: (props: ItemSlotProps) => {
+            const { index, item } = props as ItemSlotProps<MockItem>;
+            return h('div', { class: 'item' }, `${ index }: ${ item.label }`);
+          },
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const el = container.element as HTMLElement;
+
+      Object.defineProperty(el, 'scrollTop', { configurable: true, value: 150, writable: true });
+      await container.trigger('scroll');
+      await nextTick();
+      await nextTick();
+
+      const item0 = wrapper.find('.virtual-scroll-item[data-index="0"]');
+      const item1 = wrapper.find('.virtual-scroll-item[data-index="1"]');
+      const item2 = wrapper.find('.virtual-scroll-item[data-index="2"]');
+
+      expect(item2.classes()).toContain('virtual-scroll--sticky');
+      expect(item1.classes()).not.toContain('virtual-scroll--sticky');
+      expect(item0.classes()).not.toContain('virtual-scroll--sticky');
+    });
+
+    it('scrolls only one item with arrowdown when sticky header is visible', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          bufferAfter: 0,
+          bufferBefore: 0,
+          itemSize: 50,
+          items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
+          stickyHeader: true,
+        },
+        slots: {
+          header: () => h('div', { class: 'header' }, 'Header'),
+        },
+      });
+      await nextTick();
+
+      const header = wrapper.find('.virtual-scroll-header');
+      Object.defineProperty(header.element, 'offsetHeight', { configurable: true, value: 100 });
+      triggerResize(header.element, 500, 100);
+
+      await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      const container = wrapper.find('.virtual-scroll-container');
+
+      expect(vs.scrollDetails.currentEndIndex).toBe(7);
+
+      vs.scrollToOffset(null, 200);
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.currentIndex).toBe(4);
+
+      await container.trigger('keydown', { key: 'ArrowDown' });
+      await nextTick();
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(250);
+    });
+  });
+
+  describe('scaling & massive lists', () => {
+    it('items should not overlap when scaling is active', async () => {
+      const itemSize = 1000;
+      const rowCount = 11000;
+      const massiveItems = Array.from({ length: rowCount }, (_, i) => ({ id: i, label: `Item ${ i }` }));
+
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize,
+          items: massiveItems,
+        },
+        slots: {
+          item: ({ index }: { index: number; }) => h('div', { class: 'item' }, `Item ${ index }`),
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const items = wrapper.findAll('.virtual-scroll-item');
+      expect(items.length).toBeGreaterThan(1);
+      expect(items.length).toBeLessThan(50);
+
+      const item0 = items[ 0 ]!.element as HTMLElement;
+      const item1 = items[ 1 ]!.element as HTMLElement;
+
+      const style0 = item0.style.transform;
+      const style1 = item1.style.transform;
+
+      const getY = (style: string) => {
+        const match = style.match(/translate\([^,]+, ([^)]+)px\)/);
+        return match ? Number.parseFloat(match[ 1 ]!) : 0;
+      };
+
+      const y0 = getY(style0);
+      const y1 = getY(style1);
+
+      const diff = Math.abs(y1 - y0);
+      expect(diff).toBeCloseTo(itemSize, 0);
+    });
+
+    it('emulates touch scroll when scaling is active', async () => {
+      const itemSize = 1000;
+      const rowCount = 11000;
+      const massiveItems = Array.from({ length: rowCount }, (_, i) => ({ id: i }));
+
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize,
+          items: massiveItems,
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      expect(vs.scaleY).toBeGreaterThan(1);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const containerEl = container.element as HTMLElement;
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(0);
+
+      containerEl.dispatchEvent(new PointerEvent('pointerdown', {
+        clientX: 0,
+        clientY: 500,
+        pointerId: 1,
+        pointerType: 'touch',
+        button: 0,
+        bubbles: true,
+      }));
+
+      containerEl.dispatchEvent(new PointerEvent('pointermove', {
+        clientX: 0,
+        clientY: 400,
+        pointerId: 1,
+        pointerType: 'touch',
+        bubbles: true,
+      }));
+
+      await vi.advanceTimersToNextFrame();
+      expect(vs.scrollDetails.scrollOffset.y).toBeCloseTo(100, 0);
+
+      containerEl.dispatchEvent(new PointerEvent('pointerup', {
+        bubbles: true,
+        pointerId: 1,
+        pointerType: 'touch',
+      }));
+    });
+
+    it('ignores pointer events when scaling is inactive', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+      expect(vs.scaleY).toBe(1);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const containerEl = container.element as HTMLElement;
+
+      const pointerDownEvent = new PointerEvent('pointerdown', { button: 0, bubbles: true, clientY: 500 });
+      containerEl.dispatchEvent(pointerDownEvent);
+
+      const scrollOffsetBefore = vs.scrollDetails.scrollOffset.y;
+      containerEl.dispatchEvent(new PointerEvent('pointermove', { bubbles: true, clientY: 400 }));
+      expect(vs.scrollDetails.scrollOffset.y).toBe(scrollOffsetBefore);
+    });
+
+    it('ignores non-primary mouse button pointerdown', async () => {
+      const massiveItems = Array.from({ length: 40001 }, (_, i) => ({ id: i }));
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 250, items: massiveItems },
+      });
+      await nextTick();
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      expect(vs.scaleY).toBeGreaterThan(1);
+
+      const container = wrapper.find('.virtual-scroll-container');
+      const containerEl = container.element as HTMLElement;
+
+      const pointerDownEvent = new PointerEvent('pointerdown', { button: 1, bubbles: true, clientY: 500, pointerType: 'mouse' });
+      containerEl.dispatchEvent(pointerDownEvent);
+
+      const scrollOffsetBefore = vs.scrollDetails.scrollOffset.y;
+      containerEl.dispatchEvent(new PointerEvent('pointermove', { bubbles: true, clientY: 400 }));
+      expect(vs.scrollDetails.scrollOffset.y).toBe(scrollOffsetBefore);
+    });
+
+    it('ignores pointermove and pointerup when not dragging', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems },
+      });
+      await nextTick();
+      const container = wrapper.find('.virtual-scroll-container');
+      const containerEl = container.element as HTMLElement;
+
+      const pointerMoveEvent = new PointerEvent('pointermove', { bubbles: true, clientY: 400 });
+      containerEl.dispatchEvent(pointerMoveEvent);
+
+      const pointerUpEvent = new PointerEvent('pointerup', { bubbles: true });
+      containerEl.dispatchEvent(pointerUpEvent);
+    });
+
+    it('handles pointer-based scrolling when scaling is active', async () => {
+      const items = Array.from({ length: 11000 }, (_, i) => ({ id: i }));
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 1000, // 11M VU
+          items,
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<unknown>;
+      expect(vs.scaleY).toBeGreaterThan(1);
+
+      const container = wrapper.find('.virtual-scroll-container');
+
+      container.element.dispatchEvent(new PointerEvent('pointerdown', { clientX: 0, clientY: 100, button: 0, pointerId: 1, bubbles: true }));
+      container.element.dispatchEvent(new PointerEvent('pointermove', { clientX: 0, clientY: 50, pointerId: 1, bubbles: true }));
+      await nextTick();
+      vi.runAllTimers(); // process requestAnimationFrame
+      await nextTick();
+
+      // Dragged 50px up.
+      expect(vs.scrollDetails.scrollOffset.y).toBe(50);
+
+      // pointerup
+      container.element.dispatchEvent(new PointerEvent('pointerup', { clientX: 0, clientY: 50, pointerId: 1, bubbles: true }));
+      await nextTick();
+    });
+
+    it('implements inertia scrolling with friction and cancellation', async () => {
+      const items = Array.from({ length: 11000 }, (_, i) => ({ id: i }));
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 1000,
+          items,
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<unknown>;
+      const container = wrapper.find('.virtual-scroll-container');
+
+      // 1. Start inertia by swiping quickly
+      container.element.dispatchEvent(new PointerEvent('pointerdown', { clientX: 0, clientY: 400, button: 0, pointerId: 1, bubbles: true }));
+      container.element.dispatchEvent(new PointerEvent('pointermove', { clientX: 0, clientY: 300, pointerId: 1, bubbles: true }));
+      await nextTick();
+
+      // Swipe fast
+      container.element.dispatchEvent(new PointerEvent('pointerup', { clientX: 0, clientY: 200, pointerId: 1, bubbles: true }));
+      await nextTick();
+
+      // 2. Verify it continues to scroll
+      vi.advanceTimersByTime(16); // step 1
+      await nextTick();
+      const pos1 = vs.scrollDetails.scrollOffset.y;
+      expect(pos1).toBeGreaterThan(200);
+
+      vi.advanceTimersByTime(16); // step 2
+      await nextTick();
+      const pos2 = vs.scrollDetails.scrollOffset.y;
+      expect(pos2).toBeGreaterThan(pos1);
+
+      // 3. Stop inertia via stopProgrammaticScroll
+      vs.stopProgrammaticScroll();
+      vi.advanceTimersByTime(16);
+      await nextTick();
+      expect(vs.scrollDetails.scrollOffset.y).toBe(pos2);
+    });
+
+    it('prevents cross-axis drift during inertia', async () => {
+      const items = Array.from({ length: 11000 }, (_, i) => ({ id: i }));
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 1000,
+          columnCount: 11000,
+          columnWidth: 1000,
+          direction: 'both',
+          items,
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<unknown>;
+      const container = wrapper.find('.virtual-scroll-container');
+
+      // Swipe horizontally with very small vertical component
+      container.element.dispatchEvent(new PointerEvent('pointerdown', { clientX: 400, clientY: 100, button: 0, pointerId: 1, bubbles: true }));
+      container.element.dispatchEvent(new PointerEvent('pointermove', { clientX: 300, clientY: 98, pointerId: 1, bubbles: true }));
+      await nextTick();
+      vi.runAllTimers();
+      await nextTick();
+
+      container.element.dispatchEvent(new PointerEvent('pointerup', { clientX: 200, clientY: 98, pointerId: 1, bubbles: true }));
+      await nextTick();
+
+      // Velocity Y should have been zeroed because X velocity is much higher
+      vi.advanceTimersByTime(16);
+      await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.x).toBeGreaterThan(200);
+      expect(vs.scrollDetails.scrollOffset.y).toBe(2); // Initial deltaY was 2 (100 -> 98). No more movement.
+    });
+
+    describe('large scale rendering boundaries', () => {
+      const rowHeight = 1000;
+      const rowCount = 11000; // 11,000,000px
+      const massiveItems = Array.from({ length: rowCount }, (_, i) => ({ id: i }));
+      const viewportHeight = 500;
+
+      const variants = [
+        { name: 'plain', props: {} },
+        { name: 'sticky header', props: { stickyHeader: true }, hasHeader: true },
+        { name: 'sticky footer', props: { stickyFooter: true }, hasFooter: true },
+        { name: 'both sticky', props: { stickyHeader: true, stickyFooter: true }, hasHeader: true, hasFooter: true },
+        { name: 'plain with gap', props: {} },
+        { name: 'sticky header with gap', props: { stickyHeader: true, gap: 50 }, hasHeader: true },
+        { name: 'sticky footer with gap', props: { stickyFooter: true, gap: 50 }, hasFooter: true },
+        { name: 'both sticky with gap', props: { stickyHeader: true, stickyFooter: true, gap: 50 }, hasHeader: true, hasFooter: true },
+      ];
+
+      for (const variant of variants) {
+        describe(variant.name, () => {
+          it('renders last items when scrolled to end manually', async () => {
+            const wrapper = mount(VirtualScroll, {
+              props: {
+                items: massiveItems,
+                itemSize: rowHeight,
+                ...variant.props,
+              },
+              slots: {
+                ...(variant.hasHeader ? { header: '<div style="height: 50px">Header</div>' } : {}),
+                ...(variant.hasFooter ? { footer: '<div style="height: 50px">Footer</div>' } : {}),
+              },
+            });
+
+            await nextTick();
+            await nextTick();
+
+            const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+            const container = wrapper.find('.virtual-scroll-container');
+
+            const totalRUHeight = vs.scrollDetails.totalSize.height;
+            const maxRUOffset = totalRUHeight - vs.scrollDetails.viewportSize.height;
+            const maxScroll = virtualToDisplay(maxRUOffset, vs.componentOffset.y, vs.scaleY);
+            Object.defineProperty(container.element, 'scrollTop', { configurable: true, value: maxScroll });
+            await container.trigger('scroll');
+
+            await nextTick();
+            await nextTick();
+
+            const renderedIndices = vs.scrollDetails.items.map((i) => i.index);
+            expect(renderedIndices).toContain(rowCount - 1);
+            expect(renderedIndices).toContain(rowCount - 2);
+
+            const lastItem = vs.scrollDetails.items.find((i) => i.index === rowCount - 1)!;
+            expect(lastItem.originalY + lastItem.size.height).toBeCloseTo(vs.scrollDetails.scrollOffset.y + viewportHeight, 0);
+            expect(vs.scrollDetails.scrollOffset.y + viewportHeight).toBeCloseTo(totalRUHeight, 0);
+
+            wrapper.unmount();
+          });
+
+          it('renders last items when end key is pressed', async () => {
+            const wrapper = mount(VirtualScroll, {
+              props: {
+                items: massiveItems,
+                itemSize: rowHeight,
+                ...variant.props,
+              },
+              slots: {
+                ...(variant.hasHeader ? { header: '<div style="height: 50px">Header</div>' } : {}),
+                ...(variant.hasFooter ? { footer: '<div style="height: 50px">Footer</div>' } : {}),
+              },
+            });
+
+            await nextTick();
+            await nextTick();
+
+            const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+            const container = wrapper.find('.virtual-scroll-container');
+
+            await container.trigger('keydown', { key: 'End' });
+
+            await nextTick();
+            await nextTick();
+
+            const renderedIndices = vs.scrollDetails.items.map((i) => i.index);
+            expect(renderedIndices).toContain(rowCount - 1);
+
+            const lastItem = vs.scrollDetails.items.find((i) => i.index === rowCount - 1)!;
+            expect(lastItem.originalY + lastItem.size.height).toBeCloseTo(vs.scrollDetails.scrollOffset.y + viewportHeight, 0);
+
+            wrapper.unmount();
+          });
+
+          it('renders first items when home key is pressed after being at end', async () => {
+            const wrapper = mount(VirtualScroll, {
+              props: {
+                items: massiveItems,
+                itemSize: rowHeight,
+                ...variant.props,
+              },
+              slots: {
+                ...(variant.hasHeader ? { header: '<div style="height: 50px">Header</div>' } : {}),
+                ...(variant.hasFooter ? { footer: '<div style="height: 50px">Footer</div>' } : {}),
+              },
+            });
+
+            await nextTick();
+            await nextTick();
+
+            const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+            const container = wrapper.find('.virtual-scroll-container');
+
+            vs.scrollToIndex(rowCount - 1, null, { align: 'end', behavior: 'auto' });
+            await nextTick();
+            await nextTick();
+
+            await container.trigger('keydown', { key: 'Home' });
+            await nextTick();
+            await nextTick();
+
+            const renderedIndices = vs.scrollDetails.items.map((i) => i.index);
+            expect(renderedIndices).toContain(0);
+            expect(renderedIndices).toContain(1);
+            expect(vs.scrollDetails.scrollOffset.y).toBe(0);
+
+            wrapper.unmount();
+          });
+
+          it('renders correct items when scrollbar is at boundaries', async () => {
+            const wrapper = mount(VirtualScroll, {
+              props: {
+                items: massiveItems,
+                itemSize: rowHeight,
+                virtualScrollbar: true,
+                ...variant.props,
+              },
+              slots: {
+                ...(variant.hasHeader ? { header: '<div style="height: 50px">Header</div>' } : {}),
+                ...(variant.hasFooter ? { footer: '<div style="height: 50px">Footer</div>' } : {}),
+              },
+            });
+
+            await nextTick();
+            await nextTick();
+
+            const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+
+            const maxDisplayOffset = vs.renderedHeight - vs.scrollDetails.displayViewportSize.height;
+            vs.scrollToOffset(null, displayToVirtual(maxDisplayOffset, vs.componentOffset.y, vs.scaleY));
+
+            await nextTick();
+            await nextTick();
+
+            expect(vs.scrollDetails.items.map((i) => i.index)).toContain(rowCount - 1);
+
+            vs.scrollToOffset(null, 0);
+            await nextTick();
+            await nextTick();
+
+            expect(vs.scrollDetails.items.map((i) => i.index)).toContain(0);
+            expect(vs.scrollDetails.scrollOffset.y).toBe(0);
+
+            wrapper.unmount();
+          });
+        });
+      }
+    });
+  });
+
+  describe('virtual scrollbars', () => {
+    it('scrolls horizontally with shift + mousewheel when scaling is active', async () => {
+      const massiveColCount = 200000;
+      const massiveItems = Array.from({ length: 10 }, (_, i) => ({ id: i }));
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          columnCount: massiveColCount,
+          columnWidth: 100,
+          direction: 'both',
+          itemSize: 50,
+          items: massiveItems,
+        },
+      });
+
+      await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      expect(vs.scaleX).toBeGreaterThan(1);
+
+      expect(vs.scrollDetails.scrollOffset.x).toBe(0);
+      expect(vs.scrollDetails.scrollOffset.y).toBe(0);
+
+      const wheelEvent = new WheelEvent('wheel', {
+        bubbles: true,
+        cancelable: true,
+        deltaX: 0,
+        deltaY: 100,
+        shiftKey: true,
+      });
+      wrapper.find('.virtual-scroll-container').element.dispatchEvent(wheelEvent);
 
-    it('should handle End key (vertical)', async () => {
-      el.scrollLeft = 0;
-      await container.trigger('keydown', { key: 'End' });
       await nextTick();
-      // totalHeight = 100 items * 50px = 5000px
-      // viewportHeight = 500px
-      // scrollToIndex(99, 0, 'end') -> targetY = 99 * 50 = 4950
-      // alignment 'end' -> targetY = 4950 - (500 - 50) = 4500
-      expect(el.scrollTop).toBe(4500);
-      expect(el.scrollLeft).toBe(0);
+
+      expect(vs.scrollDetails.scrollOffset.x).toBeCloseTo(100, 0);
+      expect(vs.scrollDetails.scrollOffset.y).toBe(0);
     });
 
-    it('should handle End key (horizontal)', async () => {
-      await wrapper.setProps({ direction: 'horizontal' });
+    it('updates thumb size when total size changes', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 50,
+          items: Array.from({ length: 20 }, (_, i) => ({ id: i })),
+          virtualScrollbar: true,
+        },
+      });
+
       await nextTick();
-      // Trigger resize again for horizontal
-      const observers = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.filter((i) => i.targets.has(el));
-      observers.forEach((i) => i.trigger([ { target: el, contentRect: { width: 500, height: 500 } as unknown as DOMRectReadOnly } ]));
       await nextTick();
 
-      el.scrollTop = 0;
-      await container.trigger('keydown', { key: 'End' });
-      await nextTick();
-      expect(el.scrollLeft).toBe(4500);
-      expect(el.scrollTop).toBe(0);
-    });
+      const verticalThumb = wrapper.find('.virtual-scroll-scrollbar-container .virtual-scrollbar-thumb--vertical');
+      expect(verticalThumb.exists()).toBe(true);
+      expect((verticalThumb.element as HTMLElement).style.blockSize).toBe('50%');
 
-    it('should handle End key in both mode', async () => {
-      await wrapper.setProps({ columnCount: 5, columnWidth: 100, direction: 'both' });
-      await nextTick();
+      await wrapper.setProps({
+        items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
+      });
 
-      // Trigger a resize
-      const observers = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.filter((i) => i.targets.has(el));
-      observers.forEach((i) => i.trigger([ { target: el, contentRect: { width: 500, height: 500 } as unknown as DOMRectReadOnly } ]));
       await nextTick();
-
-      await container.trigger('keydown', { key: 'End' });
+      await nextTick();
       await nextTick();
 
-      // items: 100 (rows), height: 50 -> totalHeight: 5000
-      // columns: 5, width: 100 -> totalWidth: 500
-      // viewport: 500x500
-      // scrollToIndex(99, 4, 'end')
-      // targetY = 99 * 50 = 4950. end alignment: 4950 - (500 - 50) = 4500
-      // targetX = 4 * 100 = 400. end alignment: 400 - (500 - 100) = 0
-      expect(el.scrollTop).toBe(4500);
-      expect(el.scrollLeft).toBe(0);
-    });
+      expect((verticalThumb.element as HTMLElement).style.blockSize).toBe('10%');
+
+      await wrapper.setProps({
+        items: Array.from({ length: 1000 }, (_, i) => ({ id: i })),
+      });
 
-    it('should handle End key with empty items', async () => {
-      await wrapper.setProps({ items: [] });
       await nextTick();
-      await container.trigger('keydown', { key: 'End' });
       await nextTick();
-    });
-
-    it('should handle ArrowDown / ArrowUp', async () => {
-      el.scrollLeft = 0;
-      await container.trigger('keydown', { key: 'ArrowDown' });
       await nextTick();
-      expect(el.scrollTop).toBe(40);
-      expect(el.scrollLeft).toBe(0);
 
-      await container.trigger('keydown', { key: 'ArrowUp' });
-      await nextTick();
-      expect(el.scrollTop).toBe(0);
-      expect(el.scrollLeft).toBe(0);
+      expect((verticalThumb.element as HTMLElement).style.blockSize).toBe('6.4%');
     });
 
-    it('should handle ArrowRight / ArrowLeft', async () => {
-      await wrapper.setProps({ direction: 'horizontal' });
+    it('scrolls when clicking on vertical scrollbar track', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 50,
+          items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
+          virtualScrollbar: true,
+        },
+      });
+
       await nextTick();
-      el.scrollTop = 0;
-      await container.trigger('keydown', { key: 'ArrowRight' });
       await nextTick();
-      expect(el.scrollLeft).toBe(40);
-      expect(el.scrollTop).toBe(0);
 
-      await container.trigger('keydown', { key: 'ArrowLeft' });
-      await nextTick();
-      expect(el.scrollLeft).toBe(0);
-      expect(el.scrollTop).toBe(0);
-    });
+      const track = wrapper.find('.virtual-scrollbar-track--vertical');
+      expect(track.exists()).toBe(true);
 
-    it('should handle PageDown / PageUp', async () => {
-      el.scrollLeft = 0;
-      await container.trigger('keydown', { key: 'PageDown' });
-      await nextTick();
-      expect(el.scrollTop).toBe(500);
-      expect(el.scrollLeft).toBe(0);
+      vi.spyOn(track.element, 'getBoundingClientRect').mockReturnValue({
+        top: 0,
+        left: 490,
+        width: 10,
+        height: 500,
+        bottom: 500,
+        right: 500,
+      } as DOMRect);
 
-      await container.trigger('keydown', { key: 'PageUp' });
-      await nextTick();
-      expect(el.scrollTop).toBe(0);
-      expect(el.scrollLeft).toBe(0);
-    });
+      await track.trigger('mousedown', {
+        clientY: 250,
+      });
 
-    it('should handle PageDown / PageUp in horizontal mode', async () => {
-      await wrapper.setProps({ direction: 'horizontal' });
-      await nextTick();
-      el.scrollTop = 0;
-      await container.trigger('keydown', { key: 'PageDown' });
       await nextTick();
-      expect(el.scrollLeft).toBe(500);
-      expect(el.scrollTop).toBe(0);
 
-      await container.trigger('keydown', { key: 'PageUp' });
-      await nextTick();
-      expect(el.scrollLeft).toBe(0);
-      expect(el.scrollTop).toBe(0);
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      expect(vs.scrollDetails.scrollOffset.y).toBeCloseTo(2250, 0);
     });
 
-    it('should not scroll past the end using PageDown', async () => {
-      // items: 100, itemSize: 50 -> totalHeight = 5000
-      // viewportHeight: 500 -> maxScroll = 4500
-      (wrapper.vm as unknown as VSInstance).scrollToOffset(null, 4400);
+    it('scrolls to absolute end when clicking near the end of the vertical track', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { itemSize: 50, items: mockItems, virtualScrollbar: true },
+      });
       await nextTick();
-      await container.trigger('keydown', { key: 'PageDown' });
       await nextTick();
-      expect(el.scrollTop).toBe(4500);
-    });
 
-    it('should not scroll past the end using ArrowDown', async () => {
-      // maxScroll = 4500
-      (wrapper.vm as unknown as VSInstance).scrollToOffset(null, 4480);
-      await nextTick();
-      await container.trigger('keydown', { key: 'ArrowDown' });
-      await nextTick();
-      expect(el.scrollTop).toBe(4500);
-    });
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      const track = wrapper.find('.virtual-scrollbar-track--vertical');
 
-    it('should handle unhandled keys', async () => {
-      const event = new KeyboardEvent('keydown', { key: 'Enter', cancelable: true });
-      el.dispatchEvent(event);
-      expect(event.defaultPrevented).toBe(false);
-    });
-  });
+      vi.spyOn(track.element, 'getBoundingClientRect').mockReturnValue({
+        bottom: 500,
+        height: 500,
+        left: 490,
+        right: 500,
+        top: 0,
+        width: 10,
+        x: 490,
+        y: 0,
+      } as DOMRect);
 
-  describe('resize and observers', () => {
-    it('should update item size on resize', async () => {
-      const wrapper = mount(VirtualScroll, { props: { items: mockItems.slice(0, 5) } });
-      await nextTick();
-      const firstItem = wrapper.find('.virtual-scroll-item').element;
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(firstItem));
-      if (observer) {
-        observer.trigger([ {
-          target: firstItem,
-          contentRect: { width: 100, height: 100 } as DOMRectReadOnly,
-          borderBoxSize: [ { inlineSize: 110, blockSize: 110 } ],
-        } ]);
-      }
+      await track.trigger('mousedown', { clientY: 500 });
       await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(4500);
     });
 
-    it('should handle resize fallback (no borderBoxSize)', async () => {
-      const wrapper = mount(VirtualScroll, { props: { items: mockItems.slice(0, 5) } });
+    it('scrolls to absolute end when clicking near the end of the horizontal track', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { direction: 'horizontal', itemSize: 50, items: mockItems, virtualScrollbar: true },
+      });
       await nextTick();
-      const firstItem = wrapper.find('.virtual-scroll-item').element;
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(firstItem));
-      if (observer) {
-        observer.trigger([ { target: firstItem, contentRect: { width: 100, height: 100 } as DOMRectReadOnly } ]);
-      }
       await nextTick();
-    });
 
-    it('should observe host resize and update offset', async () => {
-      const wrapper = mount(VirtualScroll, { props: { items: mockItems, itemSize: 50 } });
-      await nextTick();
-      const host = wrapper.find('.virtual-scroll-container').element;
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(host));
-      if (observer) {
-        observer.trigger([ { target: host } ]);
-      }
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      const track = wrapper.find('.virtual-scrollbar-track--horizontal');
+
+      vi.spyOn(track.element, 'getBoundingClientRect').mockReturnValue({
+        bottom: 500,
+        height: 10,
+        left: 0,
+        right: 500,
+        top: 490,
+        width: 500,
+        x: 0,
+        y: 490,
+      } as DOMRect);
+
+      await track.trigger('mousedown', { clientX: 500 });
       await nextTick();
+
+      expect(vs.scrollDetails.scrollOffset.x).toBe(4500);
     });
 
-    it('should observe cell resize with data-col-index', async () => {
+    it('scrolls when clicking on horizontal scrollbar track', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 1),
-          direction: 'both',
-          columnCount: 2,
-        },
-        slots: {
-          item: '<template #item="{ index }"><div class="row"><div class="cell" data-col-index="0">Cell {{ index }}</div></div></template>',
+          direction: 'horizontal',
+          itemSize: 100,
+          items: Array.from({ length: 100 }, (_, i) => ({ id: i })),
+          virtualScrollbar: true,
         },
       });
+
+      await nextTick();
       await nextTick();
-      const cell = wrapper.find('.cell').element;
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(cell));
-      expect(observer).toBeDefined();
 
-      if (observer) {
-        observer.trigger([ {
-          target: cell,
-          contentRect: { width: 100, height: 50 } as DOMRectReadOnly,
-        } ]);
-      }
+      const track = wrapper.find('.virtual-scrollbar-track--horizontal');
+      expect(track.exists()).toBe(true);
+
+      vi.spyOn(track.element, 'getBoundingClientRect').mockReturnValue({
+        top: 490,
+        left: 0,
+        width: 500,
+        height: 10,
+        bottom: 500,
+        right: 500,
+      } as DOMRect);
+
+      await track.trigger('mousedown', {
+        clientX: 250,
+      });
+
       await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      expect(vs.scrollDetails.scrollOffset.x).toBeCloseTo(4750, 0);
     });
 
-    it('should observe header and footer resize', async () => {
+    it('calls internal scrolltooffset with infinity when scrollbar reaches the end', async () => {
+      let capturedCallback: ((offset: number) => void) | undefined;
       const wrapper = mount(VirtualScroll, {
-        props: { items: mockItems, itemSize: 50 },
+        props: { itemSize: 50, items: mockItems, virtualScrollbar: true },
         slots: {
-          header: '<div class="header">H</div>',
-          footer: '<div class="footer">F</div>',
+          scrollbar: (slotProps: ScrollbarSlotProps) => {
+            if (slotProps.scrollbarProps.axis === 'vertical') {
+              capturedCallback = slotProps.scrollbarProps.scrollToOffset;
+            }
+            return h('div', { class: 'captured-scrollbar' });
+          },
         },
       });
+
+      await nextTick();
       await nextTick();
-      const header = wrapper.find('.virtual-scroll-header').element;
-      const footer = wrapper.find('.virtual-scroll-footer').element;
 
-      const headerObserver = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(header));
-      if (headerObserver) {
-        headerObserver.trigger([ { target: header } ]);
-      }
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
 
-      const footerObserver = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(footer));
-      if (footerObserver) {
-        footerObserver.trigger([ { target: footer } ]);
-      }
+      triggerResize(wrapper.element as HTMLElement, 500, 500);
+      await nextTick();
       await nextTick();
-    });
 
-    it('should observe footer on mount if slot exists', async () => {
-      const wrapper = mount(VirtualScroll, {
-        props: { items: mockItems, itemSize: 50 },
-        slots: { footer: '<div class="footer">F</div>' },
-      });
+      expect(vs.isHydrated).toBe(true);
+      expect(wrapper.find('.captured-scrollbar').exists()).toBe(true);
+      expect(typeof capturedCallback).toBe('function');
+
+      capturedCallback!(4500);
+      await nextTick();
       await nextTick();
-      const footer = wrapper.find('.virtual-scroll-footer').element;
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(footer));
-      expect(observer).toBeDefined();
+
+      expect(vs.scrollDetails.scrollOffset.y).toBe(4500);
     });
 
-    it('should cover header/footer unobserve when removed/replaced', async () => {
-      const TestComp = defineComponent({
-        components: { VirtualScroll },
-        setup() {
-          const show = ref(true);
-          const showFooter = ref(true);
-          return { mockItems, show, showFooter };
+    it('does not show horizontal scrollbar if items fit', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          direction: 'horizontal',
+          itemSize: 100,
+          items: Array.from({ length: 2 }, (_, i) => ({ id: i })),
+          virtualScrollbar: true,
         },
-        template: `
-          <VirtualScroll :items="mockItems">
-            <template v-if="show" #header><div>H</div></template>
-            <template v-if="showFooter" #footer><div>F</div></template>
-          </VirtualScroll>
-        `,
       });
-      const wrapper = mount(TestComp);
-      await nextTick();
 
-      (wrapper.vm as unknown as TestCompInstance).show = false;
-      (wrapper.vm as unknown as TestCompInstance).showFooter = false;
       await nextTick();
-
-      (wrapper.vm as unknown as TestCompInstance).show = true;
-      (wrapper.vm as unknown as TestCompInstance).showFooter = true;
       await nextTick();
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+      expect(vs.scrollbarPropsHorizontal).toBeNull();
     });
 
-    it('should cleanup observers on unmount', async () => {
+    it('forces virtual scrollbars when virtualscrollbar prop is true', async () => {
       const wrapper = mount(VirtualScroll, {
-        props: { items: mockItems, stickyFooter: true, stickyHeader: true },
-        slots: { footer: '<div>F</div>', header: '<div>H</div>' },
+        props: {
+          items: [ { id: 1 } ],
+          itemSize: 50,
+          virtualScrollbar: true,
+        },
       });
       await nextTick();
-      wrapper.unmount();
+      expect(wrapper.find('.virtual-scroll-scrollbar-container').exists()).toBe(true);
     });
+  });
 
-    it('should ignore elements with missing or invalid data attributes in itemResizeObserver', async () => {
-      mount(VirtualScroll, { props: { items: mockItems.slice(0, 1) } });
-      await nextTick();
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances[ 0 ]!;
-
-      // 1. Invalid index string
-      const div1 = document.createElement('div');
-      div1.dataset.index = 'invalid';
-      observer.trigger([ { target: div1, contentRect: { width: 100, height: 100 } as unknown as DOMRectReadOnly } ]);
-
-      // 2. Missing index and colIndex
-      const div2 = document.createElement('div');
-      observer.trigger([ { target: div2, contentRect: { width: 100, height: 100 } as unknown as DOMRectReadOnly } ]);
-
-      await nextTick();
+  describe('ssr & hydration', () => {
+    it('renders ssr range if provided', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: {
+          itemSize: 50,
+          items: mockItems,
+          ssrRange: { end: 20, start: 10 },
+        },
+        slots: {
+          item: (props: ItemSlotProps) => {
+            const { item } = props as ItemSlotProps<MockItem>;
+            return h('div', item.label);
+          },
+        },
+      });
+      const items = wrapper.findAll('.virtual-scroll-item');
+      expect(items.length).toBe(10);
+      expect(items[ 0 ]?.attributes('data-index')).toBe('10');
+      expect(wrapper.text()).toContain('Item 10');
     });
-  });
 
-  describe('grid mode logic', () => {
-    it('should cover firstRenderedIndex watcher for grid', async () => {
+    it('hydrates and scrolls to initial index', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          bufferBefore: 2,
-          columnCount: 5,
-          direction: 'both',
+          initialScrollIndex: 50,
           itemSize: 50,
           items: mockItems,
         },
         slots: {
-          item: '<template #item="{ index }"><div class="cell" :data-col-index="0">Item {{ index }}</div></template>',
+          item: (props: ItemSlotProps) => {
+            const { item } = props as ItemSlotProps<MockItem>;
+            return h('div', item.label);
+          },
         },
       });
       await nextTick();
-      const vm = wrapper.vm as unknown as VSInstance;
-
-      // Scroll to 10
-      vm.scrollToIndex(10, 0, { align: 'start', behavior: 'auto' });
       await nextTick();
       await nextTick();
-
-      const item8 = wrapper.find('.virtual-scroll-item[data-index="8"]').element;
-      const itemResizeObserver = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances.find((i) => i.targets.has(item8));
-      expect(itemResizeObserver).toBeDefined();
-
-      // Scroll to 9
-      vm.scrollToIndex(9, 0, { align: 'start', behavior: 'auto' });
       await nextTick();
       await nextTick();
 
-      // Scroll to 50
-      vm.scrollToIndex(50, 0, { align: 'start', behavior: 'auto' });
-      await nextTick();
-      await nextTick();
+      expect(wrapper.text()).toContain('Item 50');
     });
 
-    it('should cover firstRenderedIndex watcher when items becomes empty', async () => {
+    it('renders gaps correctly during initial mount/ssr', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          columnCount: 5,
           direction: 'both',
+          items: mockItems.slice(0, 10),
           itemSize: 50,
-          items: mockItems,
+          columnCount: 5,
+          columnWidth: 100,
+          gap: 10,
+          columnGap: 20,
         },
       });
-      await nextTick();
-      await wrapper.setProps({ items: [] });
-      await nextTick();
+
+      // Check styles immediately after mount (before hydration)
+      const vsWrapper = wrapper.find('.virtual-scroll-wrapper');
+      const vsWrapperStyle = (vsWrapper.element as HTMLElement).style;
+      expect(vsWrapperStyle.rowGap).toBe('10px');
+      expect(vsWrapperStyle.columnGap).toBe('20px');
+
+      const vsItem = wrapper.find('.virtual-scroll-item');
+      const vsItemStyle = (vsItem.element as HTMLElement).style;
+      expect(vsItemStyle.columnGap).toBe('20px');
     });
   });
 
-  describe('infinite scroll and loading', () => {
-    it('should emit load event when reaching scroll end (vertical)', async () => {
+  describe('slots & custom content', () => {
+    it('renders header and footer', async () => {
       const wrapper = mount(VirtualScroll, {
-        props: {
-          itemSize: 50,
-          items: mockItems.slice(0, 10),
-          loadDistance: 400,
+        props: { items: mockItems.slice(0, 1) },
+        slots: {
+          footer: () => h('div', 'FOOTER'),
+          header: () => h('div', 'HEADER'),
         },
       });
-      await nextTick();
-
-      (wrapper.vm as unknown as VSInstance).scrollToOffset(0, 250);
-      await nextTick();
-      await nextTick();
+      expect(wrapper.text()).toContain('HEADER');
+      expect(wrapper.text()).toContain('FOOTER');
+    });
 
-      expect(wrapper.emitted('load')).toBeDefined();
-      expect(wrapper.emitted('load')![ 0 ]).toEqual([ 'vertical' ]);
+    it('shows loading indicator', async () => {
+      const wrapper = mount(VirtualScroll, {
+        props: { items: [], loading: true },
+        slots: {
+          loading: () => h('div', 'LOADING...'),
+        },
+      });
+      expect(wrapper.text()).toContain('LOADING...');
     });
 
-    it('should emit load event when reaching scroll end (horizontal)', async () => {
+    it('uses correct html tags', () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          direction: 'horizontal',
-          itemSize: 50,
-          items: mockItems.slice(0, 10),
-          loadDistance: 400,
+          containerTag: 'table',
+          itemTag: 'tr',
+          items: [],
+          wrapperTag: 'tbody',
         },
       });
-      await nextTick();
-
-      (wrapper.vm as unknown as VSInstance).scrollToOffset(250, 0);
-      await nextTick();
-      await nextTick();
-
-      expect(wrapper.emitted('load')).toBeDefined();
-      expect(wrapper.emitted('load')![ 0 ]).toEqual([ 'horizontal' ]);
+      expect(wrapper.element.tagName).toBe('TABLE');
+      expect(wrapper.find('tbody').exists()).toBe(true);
     });
 
-    it('should not emit load event when loading is true', async () => {
+    it('triggers refresh and updates items', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
           itemSize: 50,
           items: mockItems.slice(0, 10),
-          loadDistance: 100,
-          loading: true,
         },
       });
       await nextTick();
-      const container = wrapper.find('.virtual-scroll-container');
-      const el = container.element as HTMLElement;
-      Object.defineProperty(el, 'clientHeight', { value: 200, configurable: true });
-      Object.defineProperty(el, 'scrollHeight', { value: 500, configurable: true });
 
-      el.scrollTop = 250;
-      container.element.dispatchEvent(new Event('scroll'));
-      await nextTick();
+      const vs = wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; refresh: () => void; };
+      vs.refresh();
       await nextTick();
-
-      expect(wrapper.emitted('load')).toBeUndefined();
+      expect(vs.scrollDetails.items.length).toBeGreaterThan(0);
+      expect(vs.scrollDetails.items.length).toBeLessThan(50);
     });
 
-    it('should render loading slot correctly', async () => {
-      const wrapper = mount(VirtualScroll, {
+    it('handles sticky header and footer measurements', async () => {
+      mount(VirtualScroll, {
         props: {
-          itemSize: 50,
           items: mockItems.slice(0, 10),
-          loading: true,
+          stickyFooter: true,
+          stickyHeader: true,
         },
         slots: {
-          loading: '<div class="loading-indicator">Loading...</div>',
+          footer: () => h('div', { class: 'footer', style: 'height: 30px' }, 'FOOTER'),
+          header: () => h('div', { class: 'header', style: 'height: 40px' }, 'HEADER'),
         },
       });
       await nextTick();
-      expect(wrapper.find('.loading-indicator').exists()).toBe(true);
-
-      await wrapper.setProps({ direction: 'horizontal' });
-      await nextTick();
-      expect((wrapper.find('.virtual-scroll-loading').element as HTMLElement).style.display).toBe('inline-block');
     });
 
-    it('should toggle loading slot visibility based on loading prop', async () => {
+    it('accounts for sticky header and footer in scroll padding', async () => {
       const wrapper = mount(VirtualScroll, {
         props: {
-          items: mockItems.slice(0, 5),
-          loading: false,
+          items: mockItems,
+          itemSize: 50,
+          stickyHeader: true,
         },
         slots: {
-          loading: '<div class="loader">Loading...</div>',
+          header: () => h('div', { class: 'header', style: 'height: 40px' }, 'HEADER'),
         },
       });
+
       await nextTick();
+      await nextTick();
+
+      const vs = wrapper.vm as { scrollDetails: ScrollDetails<MockItem>; };
+      expect(vs.scrollDetails.totalSize.height).toBeGreaterThan(0);
+    });
+
+    it('resets measured padding when header/footer is removed', async () => {
+      const TestComponent = {
+        components: { VirtualScroll },
+        props: [ 'showHeader', 'showFooter' ],
+        template: `
+          <VirtualScroll :itemSize="50" :items="items">
+            <template v-if="showHeader" #header>
+              <div class="header" style="height: 100px">HEADER</div>
+            </template>
+            <template v-if="showFooter" #footer>
+              <div class="footer" style="height: 100px">FOOTER</div>
+            </template>
+          </VirtualScroll>
+        `,
+        data() {
+          return { items: Array.from({ length: 10 }, (_, i) => ({ id: i })) };
+        },
+      };
 
-      expect(wrapper.find('.loader').exists()).toBe(false);
-      expect(wrapper.find('.virtual-scroll-loading').exists()).toBe(false);
+      const wrapper = mount(TestComponent, {
+        props: {
+          showHeader: true,
+          showFooter: true,
+        },
+      });
 
-      await wrapper.setProps({ loading: true });
       await nextTick();
-      expect(wrapper.find('.loader').exists()).toBe(true);
-      expect(wrapper.find('.virtual-scroll-loading').exists()).toBe(true);
 
-      await wrapper.setProps({ loading: false });
+      const vs = wrapper.findComponent(VirtualScroll as unknown as DefineComponent).vm as unknown as VirtualScrollInstance<MockItem>;
+
+      const headerEl = wrapper.find('.virtual-scroll-header').element as HTMLElement;
+      const footerEl = wrapper.find('.virtual-scroll-footer').element as HTMLElement;
+
+      Object.defineProperty(headerEl, 'offsetHeight', { configurable: true, value: 100 });
+      Object.defineProperty(footerEl, 'offsetHeight', { configurable: true, value: 100 });
+
+      triggerResize(headerEl, 500, 100);
+      triggerResize(footerEl, 500, 100);
+
       await nextTick();
-      expect(wrapper.find('.loader').exists()).toBe(false);
-      expect(wrapper.find('.virtual-scroll-loading').exists()).toBe(false);
-    });
-  });
+      await nextTick();
+
+      expect(vs.scrollDetails.totalSize.height).toBe(700);
 
-  describe('internal methods and exports', () => {
-    it('should handle setItemRef', async () => {
-      const wrapper = mount(VirtualScroll, { props: { items: mockItems.slice(0, 1) } });
+      await wrapper.setProps({ showHeader: false });
+      await nextTick();
       await nextTick();
-      const vm = wrapper.vm as unknown as VSInstance;
-      const item = wrapper.find('.virtual-scroll-item').element as HTMLElement;
-      vm.setItemRef(item, 0);
-      vm.setItemRef(null, 0);
-    });
 
-    it('should handle setItemRef with NaN index', async () => {
-      mount(VirtualScroll, { props: { items: mockItems.slice(0, 1) } });
+      expect(vs.scrollDetails.totalSize.height).toBe(600);
+
+      await wrapper.setProps({ showFooter: false });
+      await nextTick();
       await nextTick();
-      const observer = (globalThis.ResizeObserver as unknown as { instances: ResizeObserverMock[]; }).instances[ 0 ];
-      const div = document.createElement('div');
-      observer?.trigger([ { target: div, contentRect: { width: 100, height: 100 } as unknown as DOMRectReadOnly } ]);
-    });
 
-    it('should expose methods', () => {
-      const wrapper = mount(VirtualScroll, { props: { items: mockItems, itemSize: 50 } });
-      expect(typeof (wrapper.vm as unknown as VSInstance).scrollToIndex).toBe('function');
-      expect(typeof (wrapper.vm as unknown as VSInstance).scrollToOffset).toBe('function');
+      expect(vs.scrollDetails.totalSize.height).toBe(500);
     });
+  });
 
-    it('should manually re-measure items on refresh', async () => {
-      const items = [ { id: 1 } ];
-      const wrapper = mount(VirtualScroll, {
-        props: { items, itemSize: 0 }, // dynamic
-        slots: { item: '<template #item="{ index }"><div class="dynamic-item" :style="{ height: \'100px\' }">Item {{ index }}</div></template>' },
+  describe('dynamic list changes', () => {
+    it('clamps scroll position when items count decreases (with scaling)', async () => {
+      const items = ref(Array.from({ length: 11000 }, (_, i) => ({ id: i })));
+      const wrapper = mount({
+        components: { VirtualScroll },
+        setup() {
+          return { items };
+        },
+        template: '<VirtualScroll :items="items" :item-size="1000" style="height: 500px" />',
       });
       await nextTick();
+      await nextTick();
+      const vs = wrapper.findComponent(VirtualScroll as unknown as VueWrapper).vm as VirtualScrollInstance<{ id: number; }>;
+
+      expect(vs.scaleY).toBeGreaterThan(1);
+
+      vs.scrollToIndex(10500, null, { align: 'start', behavior: 'auto' });
+      await nextTick();
+      await nextTick();
 
-      const el = wrapper.find('.virtual-scroll-item').element as HTMLElement;
-      Object.defineProperty(el, 'offsetHeight', { value: 100 });
-      Object.defineProperty(el, 'offsetWidth', { value: 100 });
+      expect(vs.scrollDetails.scrollOffset.y).toBe(10500000);
 
-      // First measurement via refresh (simulating manual trigger or initial measurement)
-      const vm = wrapper.vm as unknown as VSInstance;
-      vm.refresh();
+      items.value = Array.from({ length: 1000 }, (_, i) => ({ id: i }));
       await nextTick();
       await nextTick();
 
-      expect(vm.scrollDetails.totalSize.height).toBe(100);
+      expect(vs.scrollDetails.scrollOffset.y).toBeLessThanOrEqual(1000000 - 500);
     });
 
-    it('should handle refresh with no rendered items', async () => {
-      const wrapper = mount(VirtualScroll, {
-        props: { items: [], itemSize: 0 },
+    it('syncs display scroll position when total height changes (with scaling)', async () => {
+      const items = ref(Array.from({ length: 30000 }, (_, i) => ({ id: i })));
+      const wrapper = mount({
+        components: { VirtualScroll },
+        setup() {
+          return { items };
+        },
+        template: '<VirtualScroll :items="items" :item-size="1000" style="height: 500px" />',
       });
       await nextTick();
-      const vm = wrapper.vm as unknown as VSInstance;
-      vm.refresh();
       await nextTick();
+      const vs = wrapper.findComponent(VirtualScroll as unknown as VueWrapper).vm as unknown as VirtualScrollInstance<{ id: number; }>;
+
+      vs.scrollToOffset(null, 10000000);
+      await nextTick();
+      await nextTick();
+
+      const initialDisplayScroll = (wrapper.find('.virtual-scroll-container').element as HTMLElement).scrollTop;
+
+      items.value = Array.from({ length: 40000 }, (_, i) => ({ id: i }));
+      await nextTick();
+      await nextTick();
+
+      const newDisplayScroll = (wrapper.find('.virtual-scroll-container').element as HTMLElement).scrollTop;
+      expect(newDisplayScroll).not.toBe(initialDisplayScroll);
+      expect(vs.scrollDetails.scrollOffset.y).toBeCloseTo(10000000, 0);
     });
 
-    it('should emit visibleRangeChange on scroll and hydration', async () => {
-      const wrapper = mount(VirtualScroll, {
-        props: { itemSize: 50, items: mockItems },
+    it('updates pending scroll index when items are prepended in a dynamic list', async () => {
+      const items = ref(Array.from({ length: 50 }, (_, i) => ({ id: i })));
+      const wrapper = mount({
+        components: { VirtualScroll },
+        setup() {
+          return { items };
+        },
+        template: '<VirtualScroll :items="items" :item-size="50" restore-scroll-on-prepend style="height: 200px" />',
       });
+
+      await nextTick();
       await nextTick();
       await nextTick();
-      expect(wrapper.emitted('visibleRangeChange')).toBeDefined();
 
-      const container = wrapper.find('.virtual-scroll-container').element as HTMLElement;
-      Object.defineProperty(container, 'scrollTop', { value: 500, writable: true });
-      await container.dispatchEvent(new Event('scroll'));
+      const vs = wrapper.findComponent(VirtualScroll as unknown as VueWrapper).vm as unknown as VirtualScrollInstance<{ id: number; }>;
+
+      expect(vs.isHydrated).toBe(true);
+
+      vs.scrollToIndex(10, null, { behavior: 'smooth', align: 'start' });
       await nextTick();
       await nextTick();
-      expect(wrapper.emitted('visibleRangeChange')!.length).toBeGreaterThan(1);
+
+      items.value = [ { id: -2 }, { id: -1 }, ...items.value ];
+
+      for (let i = 0; i < 15; i++) {
+        await nextTick();
+      }
+
+      expect(vs.scrollDetails.scrollOffset.y).toBeCloseTo(600, 0);
     });
 
-    it('should not emit scroll event before hydration in watch', async () => {
-      // initialScrollIndex triggers delayed hydration via nextTick in useVirtualScroll
+    it('recycles items and maintains a small rendered item count', async () => {
+      const items = Array.from({ length: 1000 }, (_, i) => ({ id: i }));
       const wrapper = mount(VirtualScroll, {
         props: {
-          initialScrollIndex: 5,
+          items,
           itemSize: 50,
-          items: mockItems.slice(0, 10),
         },
       });
 
-      // Before first nextTick, isHydrated is false.
-      // Changing items will trigger scrollDetails update.
-      await wrapper.setProps({ items: mockItems.slice(0, 20) });
+      await nextTick();
+      await nextTick();
+
+      expect(wrapper.findAll('.virtual-scroll-item').length).toBe(15);
+
+      const vs = wrapper.vm as unknown as VirtualScrollInstance<{ id: number; }>;
+
+      vs.scrollToOffset(null, 5000, { behavior: 'auto' });
+      await nextTick();
+      await nextTick();
+
+      expect(wrapper.findAll('.virtual-scroll-item').length).toBe(20);
 
-      // Line 196 in VirtualScroll.vue should be hit here (return if !isHydrated)
-      expect(wrapper.emitted('scroll')).toBeUndefined();
+      vs.scrollToOffset(null, 49500, { behavior: 'auto' });
+      await nextTick();
+      await nextTick();
 
-      await nextTick(); // hydration tick
-      await nextTick(); // one more for good measure
-      expect(wrapper.emitted('scroll')).toBeDefined();
+      expect(wrapper.findAll('.virtual-scroll-item').length).toBe(15);
     });
   });
 });