@pdanpdan/virtual-scroll 0.3.0 → 0.5.0

package/src/composables/useVirtualScroll.ts

@@ -1,144 +1,55 @@
-import type { Ref } from 'vue';
+import type {
+  RenderedItem,
+  ScrollAlignment,
+  ScrollAlignmentOptions,
+  ScrollDetails,
+  ScrollDirection,
+  ScrollToIndexOptions,
+  VirtualScrollProps,
+} from '../types';
+import type { MaybeRefOrGetter } from 'vue';
 
 /* global ScrollToOptions */
-import { computed, getCurrentInstance, nextTick, onMounted, onUnmounted, reactive, ref, watch } from 'vue';
+import { computed, getCurrentInstance, nextTick, onMounted, onUnmounted, reactive, ref, toValue, watch } from 'vue';
 
 import { FenwickTree } from '../utils/fenwick-tree';
-import { getPaddingX, getPaddingY, isElement, isScrollableElement, isScrollToIndexOptions } from '../utils/scroll';
+import { BROWSER_MAX_SIZE, getPaddingX, getPaddingY, isElement, isScrollableElement, isScrollToIndexOptions, isWindowLike } from '../utils/scroll';
+import {
+  calculateColumnRange,
+  calculateItemPosition,
+  calculateRange,
+  calculateScrollTarget,
+  calculateStickyItem,
+  calculateTotalSize,
+  displayToVirtual,
+  findPrevStickyIndex,
+  virtualToDisplay,
+} from '../utils/virtual-scroll-logic';
+
+export {
+  type RenderedItem,
+  type ScrollAlignment,
+  type ScrollAlignmentOptions,
+  type ScrollDetails,
+  type ScrollDirection,
+  type ScrollToIndexOptions,
+  type VirtualScrollProps,
+};
 
 export const DEFAULT_ITEM_SIZE = 40;
 export const DEFAULT_COLUMN_WIDTH = 100;
 export const DEFAULT_BUFFER = 5;
 
-export type ScrollDirection = 'vertical' | 'horizontal' | 'both';
-export type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';
-
-/** Options for scroll alignment in a single axis or both axes. */
-export interface ScrollAlignmentOptions {
-  /** Alignment on the X axis. */
-  x?: ScrollAlignment;
-  /** Alignment on the Y axis. */
-  y?: ScrollAlignment;
-}
-
-/** Options for the scrollToIndex method. */
-export interface ScrollToIndexOptions {
-  /** Where to align the item in the viewport. */
-  align?: ScrollAlignment | ScrollAlignmentOptions;
-  /** Scroll behavior. */
-  behavior?: 'auto' | 'smooth';
-  /** Internal flag for recursive correction calls. */
-  isCorrection?: boolean;
-}
-
-/** Configuration properties for the useVirtualScroll composable. */
-export interface VirtualScrollProps<T = unknown> {
-  /** Array of items to be virtualized. */
-  items: T[];
-  /** Fixed size of each item or a function that returns the size of an item. */
-  itemSize?: number | ((item: T, index: number) => number) | undefined;
-  /** Direction of the scroll: 'vertical', 'horizontal', or 'both'. */
-  direction?: ScrollDirection | undefined;
-  /** Number of items to render before the visible viewport. */
-  bufferBefore?: number | undefined;
-  /** Number of items to render after the visible viewport. */
-  bufferAfter?: number | undefined;
-  /** The scrollable container element or window. */
-  container?: HTMLElement | Window | null | undefined;
-  /** The host element that contains the items. */
-  hostElement?: HTMLElement | null | undefined;
-  /** Range of items to render for SSR. */
-  ssrRange?: {
-    start: number;
-    end: number;
-    colStart?: number;
-    colEnd?: number;
-  } | undefined;
-  /** Number of columns for bidirectional scroll. */
-  columnCount?: number | undefined;
-  /** Fixed width of columns or an array/function for column widths. */
-  columnWidth?: number | number[] | ((index: number) => number) | undefined;
-  /** Padding at the start of the scroll container. */
-  scrollPaddingStart?: number | { x?: number; y?: number; } | undefined;
-  /** Padding at the end of the scroll container. */
-  scrollPaddingEnd?: number | { x?: number; y?: number; } | undefined;
-  /** Gap between items in pixels (vertical). */
-  gap?: number | undefined;
-  /** Gap between columns in pixels (horizontal/grid). */
-  columnGap?: number | undefined;
-  /** Indices of items that should stick to the top/start. */
-  stickyIndices?: number[] | undefined;
-  /** Distance from the end of the scrollable area to trigger 'load' event. */
-  loadDistance?: number | undefined;
-  /** Whether items are currently being loaded. */
-  loading?: boolean | undefined;
-  /** Whether to restore scroll position when items are prepended. */
-  restoreScrollOnPrepend?: boolean | undefined;
-  /** Initial scroll index to jump to on mount. */
-  initialScrollIndex?: number | undefined;
-  /** Alignment for the initial scroll index. */
-  initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions | undefined;
-  /** Default size for items before they are measured. */
-  defaultItemSize?: number | undefined;
-  /** Default width for columns before they are measured. */
-  defaultColumnWidth?: number | undefined;
-  /** Whether to enable debug mode. */
-  debug?: boolean | undefined;
-}
-
-/** Represents an item currently rendered in the virtual scroll area. */
-export interface RenderedItem<T = unknown> {
-  /** The original data item. */
-  item: T;
-  /** The index of the item in the original array. */
-  index: number;
-  /** The calculated offset relative to the host element. */
-  offset: { x: number; y: number; };
-  /** The current measured or estimated size. */
-  size: { width: number; height: number; };
-  /** The original X offset before sticky adjustments. */
-  originalX: number;
-  /** The original Y offset before sticky adjustments. */
-  originalY: number;
-  /** Whether this item is configured to be sticky. */
-  isSticky?: boolean;
-  /** Whether this item is currently stuck at the threshold. */
-  isStickyActive?: boolean;
-  /** The offset applied for the sticky pushing effect. */
-  stickyOffset: { x: number; y: number; };
-}
-
-/** Comprehensive state of the virtual scroll system. */
-export interface ScrollDetails<T = unknown> {
-  /** List of items currently rendered. */
-  items: RenderedItem<T>[];
-  /** Index of the first item partially or fully visible in the viewport. */
-  currentIndex: number;
-  /** Index of the first column partially or fully visible. */
-  currentColIndex: number;
-  /** Current scroll position relative to content start. */
-  scrollOffset: { x: number; y: number; };
-  /** Dimensions of the visible viewport. */
-  viewportSize: { width: number; height: number; };
-  /** Total calculated size of all items and gaps. */
-  totalSize: { width: number; height: number; };
-  /** Whether the container is currently being scrolled. */
-  isScrolling: boolean;
-  /** Whether the current scroll was initiated by a method call. */
-  isProgrammaticScroll: boolean;
-  /** Range of items currently being rendered. */
-  range: { start: number; end: number; };
-  /** Range of columns currently being rendered (for grid mode). */
-  columnRange: { start: number; end: number; padStart: number; padEnd: number; };
-}
-
 /**
  * Composable for virtual scrolling logic.
- * Handles calculation of visible items, scroll events, and dynamic item sizes.
+ * Handles calculation of visible items, scroll events, dynamic item sizes, and programmatic scrolling.
  *
- * @param props - Reactive properties for virtual scroll configuration
+ * @param propsInput - The configuration properties. Can be a plain object, a Ref, or a getter function.
+ * @see VirtualScrollProps
  */
-export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>) {
+export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<VirtualScrollProps<T>>) {
+  const props = computed(() => toValue(propsInput));
+
   // --- State ---
   const scrollX = ref(0);
   const scrollY = ref(0);
@@ -146,16 +57,42 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
   const isHydrated = ref(false);
   const isHydrating = ref(false);
   const isMounted = ref(false);
+  const isRtl = ref(false);
   const viewportWidth = ref(0);
   const viewportHeight = ref(0);
   const hostOffset = reactive({ x: 0, y: 0 });
+  const hostRefOffset = reactive({ x: 0, y: 0 });
   let scrollTimeout: ReturnType<typeof setTimeout> | undefined;
 
   const isProgrammaticScroll = ref(false);
+  const internalScrollX = ref(0);
+  const internalScrollY = ref(0);
+
+  let computedStyle: CSSStyleDeclaration | null = null;
+
+  /**
+   * Detects the current direction (LTR/RTL) of the scroll container.
+   */
+  const updateDirection = () => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+    const container = props.value.container || props.value.hostRef || window;
+    const el = isElement(container) ? container : document.documentElement;
+
+    if (!computedStyle || !('direction' in computedStyle)) {
+      computedStyle = window.getComputedStyle(el);
+    }
+
+    const newRtl = computedStyle.direction === 'rtl';
+    if (isRtl.value !== newRtl) {
+      isRtl.value = newRtl;
+    }
+  };
 
   // --- Fenwick Trees for efficient size and offset management ---
-  const itemSizesX = new FenwickTree(props.value.items.length);
-  const itemSizesY = new FenwickTree(props.value.items.length);
+  const itemSizesX = new FenwickTree(props.value.items?.length || 0);
+  const itemSizesY = new FenwickTree(props.value.items?.length || 0);
   const columnSizes = new FenwickTree(props.value.columnCount || 0);
 
   const treeUpdateFlag = ref(0);
@@ -176,6 +113,8 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
   let lastItems: T[] = [];
 
   // --- Computed Config ---
+  const direction = computed(() => [ 'vertical', 'horizontal', 'both' ].includes(props.value.direction as string) ? props.value.direction as ScrollDirection : 'vertical' as ScrollDirection);
+
   const isDynamicItemSize = computed(() =>
     props.value.itemSize === undefined || props.value.itemSize === null || props.value.itemSize === 0,
   );
@@ -188,108 +127,175 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
     (typeof props.value.itemSize === 'number' && props.value.itemSize > 0) ? props.value.itemSize : null,
   );
 
+  const fixedColumnWidth = computed(() =>
+    (typeof props.value.columnWidth === 'number' && props.value.columnWidth > 0) ? props.value.columnWidth : null,
+  );
+
   const defaultSize = computed(() => props.value.defaultItemSize || fixedItemSize.value || DEFAULT_ITEM_SIZE);
 
   const sortedStickyIndices = computed(() =>
     [ ...(props.value.stickyIndices || []) ].sort((a, b) => a - b),
   );
 
+  const stickyIndicesSet = computed(() => new Set(sortedStickyIndices.value));
+
+  const paddingStartX = computed(() => getPaddingX(props.value.scrollPaddingStart, props.value.direction));
+  const paddingEndX = computed(() => getPaddingX(props.value.scrollPaddingEnd, props.value.direction));
+  const paddingStartY = computed(() => getPaddingY(props.value.scrollPaddingStart, props.value.direction));
+  const paddingEndY = computed(() => getPaddingY(props.value.scrollPaddingEnd, props.value.direction));
+
+  const stickyStartX = computed(() => getPaddingX(props.value.stickyStart, props.value.direction));
+  const stickyEndX = computed(() => getPaddingX(props.value.stickyEnd, props.value.direction));
+  const stickyStartY = computed(() => getPaddingY(props.value.stickyStart, props.value.direction));
+  const stickyEndY = computed(() => getPaddingY(props.value.stickyEnd, props.value.direction));
+
+  const flowStartX = computed(() => getPaddingX(props.value.flowPaddingStart, props.value.direction));
+  const flowEndX = computed(() => getPaddingX(props.value.flowPaddingEnd, props.value.direction));
+  const flowStartY = computed(() => getPaddingY(props.value.flowPaddingStart, props.value.direction));
+  const flowEndY = computed(() => getPaddingY(props.value.flowPaddingEnd, props.value.direction));
+
+  const usableWidth = computed(() => viewportWidth.value - (direction.value !== 'vertical' ? (stickyStartX.value + stickyEndX.value) : 0));
+
+  const usableHeight = computed(() => viewportHeight.value - (direction.value !== 'horizontal' ? (stickyStartY.value + stickyEndY.value) : 0));
+
   // --- Size Calculations ---
   /**
-   * Total width of all items in the scrollable area.
+   * Total size (width and height) of all items in the scrollable area.
    */
-  const totalWidth = computed(() => {
+  const totalSize = computed(() => {
     // eslint-disable-next-line ts/no-unused-expressions
     treeUpdateFlag.value;
 
     if (!isHydrated.value && props.value.ssrRange && !isMounted.value) {
       const { start = 0, end = 0, colStart = 0, colEnd = 0 } = props.value.ssrRange;
       const colCount = props.value.columnCount || 0;
-      if (props.value.direction === 'both') {
-        if (colCount <= 0) {
-          return 0;
+      const gap = props.value.gap || 0;
+      const columnGap = props.value.columnGap || 0;
+
+      let width = 0;
+      let height = 0;
+
+      if (direction.value === 'both') {
+        if (colCount > 0) {
+          const effectiveColEnd = colEnd || colCount;
+          const total = columnSizes.query(effectiveColEnd) - columnSizes.query(colStart);
+          width = Math.max(0, total - (effectiveColEnd > colStart ? columnGap : 0));
         }
-        const effectiveColEnd = colEnd || colCount;
-        const total = columnSizes.query(effectiveColEnd) - columnSizes.query(colStart);
-        return Math.max(0, total - (effectiveColEnd > colStart ? (props.value.columnGap || 0) : 0));
-      }
-      /* v8 ignore else -- @preserve */
-      if (props.value.direction === 'horizontal') {
         if (fixedItemSize.value !== null) {
           const len = end - start;
-          return Math.max(0, len * (fixedItemSize.value + (props.value.columnGap || 0)) - (len > 0 ? (props.value.columnGap || 0) : 0));
+          height = Math.max(0, len * (fixedItemSize.value + gap) - (len > 0 ? gap : 0));
+        } else {
+          const total = itemSizesY.query(end) - itemSizesY.query(start);
+          height = Math.max(0, total - (end > start ? gap : 0));
+        }
+      } else if (direction.value === 'horizontal') {
+        if (fixedItemSize.value !== null) {
+          const len = end - start;
+          width = Math.max(0, len * (fixedItemSize.value + columnGap) - (len > 0 ? columnGap : 0));
+        } else {
+          const total = itemSizesX.query(end) - itemSizesX.query(start);
+          width = Math.max(0, total - (end > start ? columnGap : 0));
+        }
+        height = usableHeight.value;
+      } else {
+        // vertical
+        width = usableWidth.value;
+        if (fixedItemSize.value !== null) {
+          const len = end - start;
+          height = Math.max(0, len * (fixedItemSize.value + gap) - (len > 0 ? gap : 0));
+        } else {
+          const total = itemSizesY.query(end) - itemSizesY.query(start);
+          height = Math.max(0, total - (end > start ? gap : 0));
         }
-        const total = itemSizesX.query(end) - itemSizesX.query(start);
-        return Math.max(0, total - (end > start ? (props.value.columnGap || 0) : 0));
       }
-    }
 
-    if (props.value.direction === 'both') {
-      const colCount = props.value.columnCount || 0;
-      if (colCount <= 0) {
-        return 0;
-      }
-      const total = columnSizes.query(colCount);
-      return Math.max(0, total - (props.value.columnGap || 0));
-    }
-    if (props.value.direction === 'vertical') {
-      return 0;
-    }
-    if (fixedItemSize.value !== null) {
-      const len = props.value.items.length;
-      return Math.max(0, len * (fixedItemSize.value + (props.value.columnGap || 0)) - (len > 0 ? (props.value.columnGap || 0) : 0));
+      return {
+        width: Math.max(width, usableWidth.value),
+        height: Math.max(height, usableHeight.value),
+      };
     }
-    const total = itemSizesX.query(props.value.items.length);
-    return Math.max(0, total - (props.value.items.length > 0 ? (props.value.columnGap || 0) : 0));
+
+    return calculateTotalSize({
+      direction: direction.value,
+      itemsLength: props.value.items.length,
+      columnCount: props.value.columnCount || 0,
+      fixedSize: fixedItemSize.value,
+      fixedWidth: fixedColumnWidth.value,
+      gap: props.value.gap || 0,
+      columnGap: props.value.columnGap || 0,
+      usableWidth: usableWidth.value,
+      usableHeight: usableHeight.value,
+      queryY: (idx) => itemSizesY.query(idx),
+      queryX: (idx) => itemSizesX.query(idx),
+      queryColumn: (idx) => columnSizes.query(idx),
+    });
   });
 
-  /**
-   * Total height of all items in the scrollable area.
-   */
-  const totalHeight = computed(() => {
-    // eslint-disable-next-line ts/no-unused-expressions
-    treeUpdateFlag.value;
+  const isWindowContainer = computed(() => isWindowLike(props.value.container));
 
-    if (!isHydrated.value && props.value.ssrRange && !isMounted.value) {
-      const { start, end } = props.value.ssrRange;
-      /* v8 ignore else -- @preserve */
-      if (props.value.direction === 'vertical' || props.value.direction === 'both') {
-        if (fixedItemSize.value !== null) {
-          const len = end - start;
-          return Math.max(0, len * (fixedItemSize.value + (props.value.gap || 0)) - (len > 0 ? (props.value.gap || 0) : 0));
-        }
-        const total = itemSizesY.query(end) - itemSizesY.query(start);
-        return Math.max(0, total - (end > start ? (props.value.gap || 0) : 0));
-      }
-    }
+  const virtualWidth = computed(() => totalSize.value.width + paddingStartX.value + paddingEndX.value);
+  const virtualHeight = computed(() => totalSize.value.height + paddingStartY.value + paddingEndY.value);
 
-    if (props.value.direction === 'horizontal') {
-      return 0;
+  const totalWidth = computed(() => (flowStartX.value + stickyStartX.value + stickyEndX.value + flowEndX.value + virtualWidth.value));
+
+  const totalHeight = computed(() => (flowStartY.value + stickyStartY.value + stickyEndY.value + flowEndY.value + virtualHeight.value));
+
+  const componentOffset = reactive({
+    x: computed(() => Math.max(0, hostOffset.x - (flowStartX.value + stickyStartX.value))),
+    y: computed(() => Math.max(0, hostOffset.y - (flowStartY.value + stickyStartY.value))),
+  });
+
+  const renderedWidth = computed(() => (isWindowContainer.value ? totalWidth.value : Math.min(totalWidth.value, BROWSER_MAX_SIZE)));
+  const renderedHeight = computed(() => (isWindowContainer.value ? totalHeight.value : Math.min(totalHeight.value, BROWSER_MAX_SIZE)));
+
+  const renderedVirtualWidth = computed(() => (isWindowContainer.value ? virtualWidth.value : Math.max(0, renderedWidth.value - (flowStartX.value + stickyStartX.value + stickyEndX.value + flowEndX.value))));
+  const renderedVirtualHeight = computed(() => (isWindowContainer.value ? virtualHeight.value : Math.max(0, renderedHeight.value - (flowStartY.value + stickyStartY.value + stickyEndY.value + flowEndY.value))));
+
+  const scaleX = computed(() => {
+    if (isWindowContainer.value || totalWidth.value <= BROWSER_MAX_SIZE) {
+      return 1;
     }
-    if (fixedItemSize.value !== null) {
-      const len = props.value.items.length;
-      return Math.max(0, len * (fixedItemSize.value + (props.value.gap || 0)) - (len > 0 ? (props.value.gap || 0) : 0));
+    const realRange = totalWidth.value - viewportWidth.value;
+    const displayRange = renderedWidth.value - viewportWidth.value;
+    return displayRange > 0 ? realRange / displayRange : 1;
+  });
+
+  const scaleY = computed(() => {
+    if (isWindowContainer.value || totalHeight.value <= BROWSER_MAX_SIZE) {
+      return 1;
     }
-    const total = itemSizesY.query(props.value.items.length);
-    return Math.max(0, total - (props.value.items.length > 0 ? (props.value.gap || 0) : 0));
+    const realRange = totalHeight.value - viewportHeight.value;
+    const displayRange = renderedHeight.value - viewportHeight.value;
+    return displayRange > 0 ? realRange / displayRange : 1;
   });
 
   const relativeScrollX = computed(() => {
-    const isHorizontal = props.value.direction === 'horizontal' || props.value.direction === 'both';
-    const padding = isHorizontal ? getPaddingX(props.value.scrollPaddingStart, props.value.direction) : 0;
-    return Math.max(0, scrollX.value + padding - hostOffset.x);
+    if (direction.value === 'vertical') {
+      return 0;
+    }
+    const flowPaddingX = flowStartX.value + stickyStartX.value + paddingStartX.value;
+    return internalScrollX.value - flowPaddingX;
   });
+
   const relativeScrollY = computed(() => {
-    const isVertical = props.value.direction === 'vertical' || props.value.direction === 'both';
-    const padding = isVertical ? getPaddingY(props.value.scrollPaddingStart, props.value.direction) : 0;
-    return Math.max(0, scrollY.value + padding - hostOffset.y);
+    if (direction.value === 'horizontal') {
+      return 0;
+    }
+    const flowPaddingY = flowStartY.value + stickyStartY.value + paddingStartY.value;
+    return internalScrollY.value - flowPaddingY;
   });
 
-  // --- Scroll Helpers ---
+  /**
+   * Returns the currently calculated width for a specific column index, taking measurements and gaps into account.
+   *
+   * @param index - The column index.
+   * @returns The width in pixels (excluding gap).
+   */
   const getColumnWidth = (index: number) => {
     // eslint-disable-next-line ts/no-unused-expressions
     treeUpdateFlag.value;
 
+    const columnGap = props.value.columnGap || 0;
     const cw = props.value.columnWidth;
     if (typeof cw === 'number' && cw > 0) {
       return cw;
@@ -298,11 +304,39 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       const val = cw[ index % cw.length ];
       return (val != null && val > 0) ? val : (props.value.defaultColumnWidth || DEFAULT_COLUMN_WIDTH);
     }
-    /* v8 ignore else -- @preserve */
     if (typeof cw === 'function') {
       return cw(index);
     }
-    return columnSizes.get(index) || props.value.defaultColumnWidth || DEFAULT_COLUMN_WIDTH;
+    const val = columnSizes.get(index);
+    return val > 0 ? val - columnGap : (props.value.defaultColumnWidth || DEFAULT_COLUMN_WIDTH);
+  };
+
+  /**
+   * Returns the currently calculated height for a specific row index, taking measurements and gaps into account.
+   *
+   * @param index - The row index.
+   * @returns The height in pixels (excluding gap).
+   */
+  const getRowHeight = (index: number) => {
+    // eslint-disable-next-line ts/no-unused-expressions
+    treeUpdateFlag.value;
+
+    if (direction.value === 'horizontal') {
+      return usableHeight.value;
+    }
+
+    const gap = props.value.gap || 0;
+    const itemSize = props.value.itemSize;
+    if (typeof itemSize === 'number' && itemSize > 0) {
+      return itemSize;
+    }
+    if (typeof itemSize === 'function') {
+      const item = props.value.items[ index ];
+      return item !== undefined ? itemSize(item, index) : (props.value.defaultItemSize || DEFAULT_ITEM_SIZE);
+    }
+
+    const val = itemSizesY.get(index);
+    return val > 0 ? val - gap : (props.value.defaultItemSize || DEFAULT_ITEM_SIZE);
   };
 
   // --- Public Scroll API ---
@@ -312,172 +346,80 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
    * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally.
    * @param colIndex - The column index to scroll to. Pass null to only scroll vertically.
    * @param options - Scroll options including alignment ('start', 'center', 'end', 'auto') and behavior ('auto', 'smooth').
+   *                  Defaults to { align: 'auto', behavior: 'auto' }.
    */
-  const scrollToIndex = (
+  function scrollToIndex(
     rowIndex: number | null | undefined,
     colIndex: number | null | undefined,
     options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions,
-  ) => {
+  ) {
     const isCorrection = typeof options === 'object' && options !== null && 'isCorrection' in options
       ? options.isCorrection
       : false;
 
-    if (!isCorrection) {
-      pendingScroll.value = { rowIndex, colIndex, options };
-    }
-
     const container = props.value.container || window;
-    const fixedSize = fixedItemSize.value;
-    const gap = props.value.gap || 0;
-    const columnGap = props.value.columnGap || 0;
-
-    let align: ScrollAlignment | ScrollAlignmentOptions | undefined;
-    let behavior: 'auto' | 'smooth' | undefined;
-
-    if (isScrollToIndexOptions(options)) {
-      align = options.align;
-      behavior = options.behavior;
-    } else {
-      align = options as ScrollAlignment | ScrollAlignmentOptions;
-    }
-
-    const alignX = (typeof align === 'object' ? align.x : align) || 'auto';
-    const alignY = (typeof align === 'object' ? align.y : align) || 'auto';
-
-    const paddingStartX = getPaddingX(props.value.scrollPaddingStart, props.value.direction);
-    const paddingEndX = getPaddingX(props.value.scrollPaddingEnd, props.value.direction);
-    const paddingStartY = getPaddingY(props.value.scrollPaddingStart, props.value.direction);
-    const paddingEndY = getPaddingY(props.value.scrollPaddingEnd, props.value.direction);
-
-    const isVertical = props.value.direction === 'vertical' || props.value.direction === 'both';
-    const isHorizontal = props.value.direction === 'horizontal' || props.value.direction === 'both';
-
-    const usableWidth = viewportWidth.value - (isHorizontal ? (paddingStartX + paddingEndX) : 0);
-    const usableHeight = viewportHeight.value - (isVertical ? (paddingStartY + paddingEndY) : 0);
-
-    let targetX = relativeScrollX.value;
-    let targetY = relativeScrollY.value;
-    let itemWidth = 0;
-    let itemHeight = 0;
-
-    // Y calculation
-    if (rowIndex !== null && rowIndex !== undefined) {
-      if (rowIndex >= props.value.items.length) {
-        targetY = totalHeight.value;
-        itemHeight = 0;
-      } else {
-        targetY = fixedSize !== null ? rowIndex * (fixedSize + gap) : itemSizesY.query(rowIndex);
-        itemHeight = fixedSize !== null ? fixedSize : itemSizesY.get(rowIndex) - gap;
-      }
-
-      // Apply Y Alignment
-      if (alignY === 'start') {
-        // targetY is already at the start of the list
-      } else if (alignY === 'center') {
-        targetY -= (usableHeight - itemHeight) / 2;
-      } else if (alignY === 'end') {
-        targetY -= (usableHeight - itemHeight);
-      } else {
-        const isVisibleY = targetY >= relativeScrollY.value && (targetY + itemHeight) <= (relativeScrollY.value + usableHeight);
-        if (!isVisibleY) {
-          if (targetY < relativeScrollY.value) {
-            // keep targetY at start
-          } else {
-            targetY -= (usableHeight - itemHeight);
-          }
-        }
-      }
-    }
 
-    // X calculation
-    if (colIndex !== null && colIndex !== undefined) {
-      const totalCols = props.value.columnCount || 0;
-      if (colIndex >= totalCols && totalCols > 0) {
-        targetX = totalWidth.value;
-        itemWidth = 0;
-      } else if (props.value.direction === 'horizontal') {
-        targetX = fixedSize !== null ? colIndex * (fixedSize + columnGap) : itemSizesX.query(colIndex);
-        itemWidth = fixedSize !== null ? fixedSize : itemSizesX.get(colIndex) - columnGap;
-      } else {
-        targetX = columnSizes.query(colIndex);
-        itemWidth = columnSizes.get(colIndex) - columnGap;
-      }
+    const { targetX, targetY, effectiveAlignX, effectiveAlignY } = calculateScrollTarget({
+      rowIndex,
+      colIndex,
+      options,
+      direction: direction.value,
+      viewportWidth: viewportWidth.value,
+      viewportHeight: viewportHeight.value,
+      totalWidth: totalWidth.value,
+      totalHeight: totalHeight.value,
+      gap: props.value.gap || 0,
+      columnGap: props.value.columnGap || 0,
+      fixedSize: fixedItemSize.value,
+      fixedWidth: fixedColumnWidth.value,
+      relativeScrollX: relativeScrollX.value,
+      relativeScrollY: relativeScrollY.value,
+      getItemSizeY: (idx) => itemSizesY.get(idx),
+      getItemSizeX: (idx) => itemSizesX.get(idx),
+      getItemQueryY: (idx) => itemSizesY.query(idx),
+      getItemQueryX: (idx) => itemSizesX.query(idx),
+      getColumnSize: (idx) => columnSizes.get(idx),
+      getColumnQuery: (idx) => columnSizes.query(idx),
+      scaleX: scaleX.value,
+      scaleY: scaleY.value,
+      hostOffsetX: componentOffset.x,
+      hostOffsetY: componentOffset.y,
+      stickyIndices: sortedStickyIndices.value,
+      stickyStartX: stickyStartX.value,
+      stickyStartY: stickyStartY.value,
+      stickyEndX: stickyEndX.value,
+      stickyEndY: stickyEndY.value,
+      flowPaddingStartX: flowStartX.value,
+      flowPaddingStartY: flowStartY.value,
+      flowPaddingEndX: flowEndX.value,
+      flowPaddingEndY: flowEndY.value,
+      paddingStartX: paddingStartX.value,
+      paddingStartY: paddingStartY.value,
+      paddingEndX: paddingEndX.value,
+      paddingEndY: paddingEndY.value,
+    });
 
-      // Apply X Alignment
-      if (alignX === 'start') {
-        // targetX is already at the start of the list
-      } else if (alignX === 'center') {
-        targetX -= (usableWidth - itemWidth) / 2;
-      } else if (alignX === 'end') {
-        targetX -= (usableWidth - itemWidth);
-      } else {
-        const isVisibleX = targetX >= relativeScrollX.value && (targetX + itemWidth) <= (relativeScrollX.value + usableWidth);
-        if (!isVisibleX) {
-          /* v8 ignore if -- @preserve */
-          if (targetX < relativeScrollX.value) {
-            // keep targetX at start
-          } else {
-            targetX -= (usableWidth - itemWidth);
-          }
-        }
-      }
+    if (!isCorrection) {
+      const behavior = isScrollToIndexOptions(options) ? options.behavior : undefined;
+      pendingScroll.value = {
+        rowIndex,
+        colIndex,
+        options: {
+          align: { x: effectiveAlignX, y: effectiveAlignY },
+          ...(behavior != null ? { behavior } : {}),
+        },
+      };
     }
 
-    // Clamp to valid range
-    targetX = Math.max(0, Math.min(targetX, Math.max(0, totalWidth.value - usableWidth)));
-    targetY = Math.max(0, Math.min(targetY, Math.max(0, totalHeight.value - usableHeight)));
-
-    const finalX = targetX + hostOffset.x - (isHorizontal ? paddingStartX : 0);
-    const finalY = targetY + hostOffset.y - (isVertical ? paddingStartY : 0);
-
-    // Check if we reached the target
-    const tolerance = 1;
-    let reachedX = (colIndex === null || colIndex === undefined) || Math.abs(relativeScrollX.value - targetX) < tolerance;
-    let reachedY = (rowIndex === null || rowIndex === undefined) || Math.abs(relativeScrollY.value - targetY) < tolerance;
-
-    if (!reachedX || !reachedY) {
-      let curX = 0;
-      let curY = 0;
-      let maxW = 0;
-      let maxH = 0;
-      let viewW = 0;
-      let viewH = 0;
-
-      /* v8 ignore else -- @preserve */
-      if (typeof window !== 'undefined') {
-        if (container === window) {
-          curX = window.scrollX;
-          curY = window.scrollY;
-          maxW = document.documentElement.scrollWidth;
-          maxH = document.documentElement.scrollHeight;
-          viewW = window.innerWidth;
-          viewH = window.innerHeight;
-        } else if (isElement(container)) {
-          curX = container.scrollLeft;
-          curY = container.scrollTop;
-          maxW = container.scrollWidth;
-          maxH = container.scrollHeight;
-          viewW = container.clientWidth;
-          viewH = container.clientHeight;
-        }
+    const displayTargetX = virtualToDisplay(targetX, componentOffset.x, scaleX.value);
+    const displayTargetY = virtualToDisplay(targetY, componentOffset.y, scaleY.value);
 
-        if (!reachedX && colIndex !== null && colIndex !== undefined) {
-          const atLeft = curX <= tolerance && finalX <= tolerance;
-          const atRight = curX >= maxW - viewW - tolerance && finalX >= maxW - viewW - tolerance;
-          /* v8 ignore else -- @preserve */
-          if (atLeft || atRight) {
-            reachedX = true;
-          }
-        }
+    const finalX = isRtl.value ? -displayTargetX : displayTargetX;
+    const finalY = displayTargetY;
 
-        if (!reachedY && rowIndex !== null && rowIndex !== undefined) {
-          const atTop = curY <= tolerance && finalY <= tolerance;
-          const atBottom = curY >= maxH - viewH - tolerance && finalY >= maxH - viewH - tolerance;
-          if (atTop || atBottom) {
-            reachedY = true;
-          }
-        }
-      }
+    let behavior: 'auto' | 'smooth' | undefined;
+    if (isScrollToIndexOptions(options)) {
+      behavior = options.behavior;
     }
 
     const scrollBehavior = isCorrection ? 'auto' : (behavior || 'smooth');
@@ -485,7 +427,7 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
 
     if (typeof window !== 'undefined' && container === window) {
       window.scrollTo({
-        left: (colIndex === null || colIndex === undefined) ? undefined : Math.max(0, finalX),
+        left: (colIndex === null || colIndex === undefined) ? undefined : (isRtl.value ? finalX : Math.max(0, finalX)),
         top: (rowIndex === null || rowIndex === undefined) ? undefined : Math.max(0, finalY),
         behavior: scrollBehavior,
       } as ScrollToOptions);
@@ -495,7 +437,7 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       };
 
       if (colIndex !== null && colIndex !== undefined) {
-        scrollOptions.left = Math.max(0, finalX);
+        scrollOptions.left = (isRtl.value ? finalX : Math.max(0, finalX));
       }
       if (rowIndex !== null && rowIndex !== undefined) {
         scrollOptions.top = Math.max(0, finalY);
@@ -515,53 +457,65 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
 
     if (scrollBehavior === 'auto' || scrollBehavior === undefined) {
       if (colIndex !== null && colIndex !== undefined) {
-        scrollX.value = Math.max(0, finalX);
+        scrollX.value = (isRtl.value ? finalX : Math.max(0, finalX));
+        internalScrollX.value = targetX;
       }
       if (rowIndex !== null && rowIndex !== undefined) {
         scrollY.value = Math.max(0, finalY);
+        internalScrollY.value = targetY;
       }
-    }
 
-    if (reachedX && reachedY && !isScrolling.value) {
-      pendingScroll.value = null;
+      if (pendingScroll.value) {
+        const currentOptions = pendingScroll.value.options;
+        if (isScrollToIndexOptions(currentOptions)) {
+          currentOptions.behavior = 'auto';
+        } else {
+          pendingScroll.value.options = {
+            align: currentOptions as ScrollAlignment | ScrollAlignmentOptions,
+            behavior: 'auto',
+          };
+        }
+      }
     }
-  };
+  }
 
   /**
    * Programmatically scroll to a specific pixel offset relative to the content start.
    *
    * @param x - The pixel offset to scroll to on the X axis. Pass null to keep current position.
    * @param y - The pixel offset to scroll to on the Y axis. Pass null to keep current position.
-   * @param options - Scroll options (behavior)
-   * @param options.behavior - The scroll behavior ('auto' | 'smooth')
+   * @param options - Scroll options (behavior).
+   * @param options.behavior - The scroll behavior ('auto' | 'smooth'). Defaults to 'auto'.
    */
   const scrollToOffset = (x?: number | null, y?: number | null, options?: { behavior?: 'auto' | 'smooth'; }) => {
     const container = props.value.container || window;
     isProgrammaticScroll.value = true;
-
-    const isVertical = props.value.direction === 'vertical' || props.value.direction === 'both';
-    const isHorizontal = props.value.direction === 'horizontal' || props.value.direction === 'both';
-
-    const paddingStartX = getPaddingX(props.value.scrollPaddingStart, props.value.direction);
-    const paddingStartY = getPaddingY(props.value.scrollPaddingStart, props.value.direction);
-    const paddingEndX = getPaddingX(props.value.scrollPaddingEnd, props.value.direction);
-    const paddingEndY = getPaddingY(props.value.scrollPaddingEnd, props.value.direction);
-
-    const usableWidth = viewportWidth.value - (isHorizontal ? (paddingStartX + paddingEndX) : 0);
-    const usableHeight = viewportHeight.value - (isVertical ? (paddingStartY + paddingEndY) : 0);
+    pendingScroll.value = null;
 
     const clampedX = (x !== null && x !== undefined)
-      ? (isHorizontal ? Math.max(0, Math.min(x, Math.max(0, totalWidth.value - usableWidth))) : Math.max(0, x))
+      ? Math.max(0, Math.min(x, totalWidth.value - viewportWidth.value))
       : null;
     const clampedY = (y !== null && y !== undefined)
-      ? (isVertical ? Math.max(0, Math.min(y, Math.max(0, totalHeight.value - usableHeight))) : Math.max(0, y))
+      ? Math.max(0, Math.min(y, totalHeight.value - viewportHeight.value))
       : null;
 
+    if (clampedX !== null) {
+      internalScrollX.value = clampedX;
+    }
+    if (clampedY !== null) {
+      internalScrollY.value = clampedY;
+    }
+
     const currentX = (typeof window !== 'undefined' && container === window ? window.scrollX : (container as HTMLElement).scrollLeft);
     const currentY = (typeof window !== 'undefined' && container === window ? window.scrollY : (container as HTMLElement).scrollTop);
 
-    const targetX = (clampedX !== null) ? clampedX + hostOffset.x - (isHorizontal ? paddingStartX : 0) : currentX;
-    const targetY = (clampedY !== null) ? clampedY + hostOffset.y - (isVertical ? paddingStartY : 0) : currentY;
+    const displayTargetX = (clampedX !== null) ? virtualToDisplay(clampedX, componentOffset.x, scaleX.value) : null;
+    const displayTargetY = (clampedY !== null) ? virtualToDisplay(clampedY, componentOffset.y, scaleY.value) : null;
+
+    const targetX = (displayTargetX !== null)
+      ? (isRtl.value ? -displayTargetX : displayTargetX)
+      : currentX;
+    const targetY = (displayTargetY !== null) ? displayTargetY : currentY;
 
     if (typeof window !== 'undefined' && container === window) {
       window.scrollTo({
@@ -604,11 +558,7 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
   };
 
   // --- Measurement & Initialization ---
-  const initializeSizes = () => {
-    const newItems = props.value.items;
-    const len = newItems.length;
-    const colCount = props.value.columnCount || 0;
-
+  const resizeMeasurements = (len: number, colCount: number) => {
     itemSizesX.resize(len);
     itemSizesY.resize(len);
     columnSizes.resize(colCount);
@@ -628,78 +578,38 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       newMeasuredCols.set(measuredColumns.subarray(0, Math.min(colCount, measuredColumns.length)));
       measuredColumns = newMeasuredCols;
     }
+  };
 
-    let prependCount = 0;
-    if (props.value.restoreScrollOnPrepend && lastItems.length > 0 && len > lastItems.length) {
-      const oldFirstItem = lastItems[ 0 ];
-      /* v8 ignore else -- @preserve */
-      if (oldFirstItem !== undefined) {
-        for (let i = 1; i <= len - lastItems.length; i++) {
-          if (newItems[ i ] === oldFirstItem) {
-            prependCount = i;
-            break;
-          }
-        }
-      }
-    }
-
-    if (prependCount > 0) {
-      itemSizesX.shift(prependCount);
-      itemSizesY.shift(prependCount);
-
-      if (pendingScroll.value && pendingScroll.value.rowIndex !== null && pendingScroll.value.rowIndex !== undefined) {
-        pendingScroll.value.rowIndex += prependCount;
-      }
-
-      const newMeasuredX = new Uint8Array(len);
-      const newMeasuredY = new Uint8Array(len);
-      newMeasuredX.set(measuredItemsX.subarray(0, Math.min(len - prependCount, measuredItemsX.length)), prependCount);
-      newMeasuredY.set(measuredItemsY.subarray(0, Math.min(len - prependCount, measuredItemsY.length)), prependCount);
-      measuredItemsX = newMeasuredX;
-      measuredItemsY = newMeasuredY;
-
-      // Calculate added size
-      const gap = props.value.gap || 0;
-      const columnGap = props.value.columnGap || 0;
-      let addedX = 0;
-      let addedY = 0;
-
-      for (let i = 0; i < prependCount; i++) {
-        const size = typeof props.value.itemSize === 'function'
-          ? props.value.itemSize(newItems[ i ] as T, i)
-          : defaultSize.value;
-
-        if (props.value.direction === 'horizontal') {
-          addedX += size + columnGap;
-        } else {
-          addedY += size + gap;
-        }
-      }
+  const initializeMeasurements = () => {
+    const newItems = props.value.items;
+    const len = newItems.length;
+    const colCount = props.value.columnCount || 0;
+    const gap = props.value.gap || 0;
+    const columnGap = props.value.columnGap || 0;
+    const cw = props.value.columnWidth;
 
-      /* v8 ignore else -- @preserve */
-      if (addedX > 0 || addedY > 0) {
-        nextTick(() => {
-          scrollToOffset(
-            addedX > 0 ? relativeScrollX.value + addedX : null,
-            addedY > 0 ? relativeScrollY.value + addedY : null,
-            { behavior: 'auto' },
-          );
-        });
-      }
-    }
+    let colNeedsRebuild = false;
+    let itemsNeedRebuild = false;
 
-    // Initialize columns if fixed width is provided
+    // Initialize columns
     if (colCount > 0) {
-      const columnGap = props.value.columnGap || 0;
-      let colNeedsRebuild = false;
       for (let i = 0; i < colCount; i++) {
-        const width = getColumnWidth(i);
         const currentW = columnSizes.get(i);
         const isMeasured = measuredColumns[ i ] === 1;
 
-        // If fixed/function, or if dynamic but not measured yet
-        if (!isDynamicColumnWidth.value || !isMeasured || currentW === 0) {
-          const targetW = width + columnGap;
+        if (!isDynamicColumnWidth.value || (!isMeasured && currentW === 0)) {
+          let baseWidth = 0;
+          if (typeof cw === 'number' && cw > 0) {
+            baseWidth = cw;
+          } else if (Array.isArray(cw) && cw.length > 0) {
+            baseWidth = cw[ i % cw.length ] || props.value.defaultColumnWidth || DEFAULT_COLUMN_WIDTH;
+          } else if (typeof cw === 'function') {
+            baseWidth = cw(i);
+          } else {
+            baseWidth = props.value.defaultColumnWidth || DEFAULT_COLUMN_WIDTH;
+          }
+
+          const targetW = baseWidth + columnGap;
           if (Math.abs(currentW - targetW) > 0.5) {
             columnSizes.set(i, targetW);
             measuredColumns[ i ] = isDynamicColumnWidth.value ? 0 : 1;
@@ -709,38 +619,20 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
           }
         }
       }
-      if (colNeedsRebuild) {
-        columnSizes.rebuild();
-      }
     }
 
-    const gap = props.value.gap || 0;
-    const columnGap = props.value.columnGap || 0;
-    let itemsNeedRebuild = false;
-
+    // Initialize items
     for (let i = 0; i < len; i++) {
       const item = props.value.items[ i ];
       const currentX = itemSizesX.get(i);
       const currentY = itemSizesY.get(i);
-
-      const size = typeof props.value.itemSize === 'function'
-        ? props.value.itemSize(item as T, i)
-        : defaultSize.value;
-
-      const isVertical = props.value.direction === 'vertical';
-      const isHorizontal = props.value.direction === 'horizontal';
-      const isBoth = props.value.direction === 'both';
-
-      const targetX = isHorizontal ? size + columnGap : 0;
-      const targetY = (isVertical || isBoth) ? size + gap : 0;
-
       const isMeasuredX = measuredItemsX[ i ] === 1;
       const isMeasuredY = measuredItemsY[ i ] === 1;
 
-      // Logic for X
-      if (isHorizontal) {
-        // If fixed/function, or if dynamic but not measured yet
-        if (!isDynamicItemSize.value || !isMeasuredX || currentX === 0) {
+      if (direction.value === 'horizontal') {
+        if (!isDynamicItemSize.value || (!isMeasuredX && currentX === 0)) {
+          const baseSize = typeof props.value.itemSize === 'function' ? props.value.itemSize(item as T, i) : defaultSize.value;
+          const targetX = baseSize + columnGap;
           if (Math.abs(currentX - targetX) > 0.5) {
             itemSizesX.set(i, targetX);
             measuredItemsX[ i ] = isDynamicItemSize.value ? 0 : 1;
@@ -755,9 +647,10 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
         itemsNeedRebuild = true;
       }
 
-      // Logic for Y
-      if (isVertical || isBoth) {
-        if (!isDynamicItemSize.value || !isMeasuredY || currentY === 0) {
+      if (direction.value !== 'horizontal') {
+        if (!isDynamicItemSize.value || (!isMeasuredY && currentY === 0)) {
+          const baseSize = typeof props.value.itemSize === 'function' ? props.value.itemSize(item as T, i) : defaultSize.value;
+          const targetY = baseSize + gap;
           if (Math.abs(currentY - targetY) > 0.5) {
             itemSizesY.set(i, targetY);
             measuredItemsY[ i ] = isDynamicItemSize.value ? 0 : 1;
@@ -773,10 +666,75 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       }
     }
 
+    if (colNeedsRebuild) {
+      columnSizes.rebuild();
+    }
     if (itemsNeedRebuild) {
       itemSizesX.rebuild();
       itemSizesY.rebuild();
     }
+  };
+
+  const initializeSizes = () => {
+    const newItems = props.value.items;
+    const len = newItems.length;
+    const colCount = props.value.columnCount || 0;
+
+    resizeMeasurements(len, colCount);
+
+    let prependCount = 0;
+    if (props.value.restoreScrollOnPrepend && lastItems.length > 0 && len > lastItems.length) {
+      const oldFirstItem = lastItems[ 0 ];
+      if (oldFirstItem !== undefined) {
+        for (let i = 1; i <= len - lastItems.length; i++) {
+          if (newItems[ i ] === oldFirstItem) {
+            prependCount = i;
+            break;
+          }
+        }
+      }
+    }
+
+    if (prependCount > 0) {
+      itemSizesX.shift(prependCount);
+      itemSizesY.shift(prependCount);
+
+      if (pendingScroll.value && pendingScroll.value.rowIndex !== null && pendingScroll.value.rowIndex !== undefined) {
+        pendingScroll.value.rowIndex += prependCount;
+      }
+
+      const newMeasuredX = new Uint8Array(len);
+      const newMeasuredY = new Uint8Array(len);
+      newMeasuredX.set(measuredItemsX.subarray(0, Math.min(len - prependCount, measuredItemsX.length)), prependCount);
+      newMeasuredY.set(measuredItemsY.subarray(0, Math.min(len - prependCount, measuredItemsY.length)), prependCount);
+      measuredItemsX = newMeasuredX;
+      measuredItemsY = newMeasuredY;
+
+      // Calculate added size
+      const gap = props.value.gap || 0;
+      const columnGap = props.value.columnGap || 0;
+      let addedX = 0;
+      let addedY = 0;
+
+      for (let i = 0; i < prependCount; i++) {
+        const size = typeof props.value.itemSize === 'function' ? props.value.itemSize(newItems[ i ] as T, i) : defaultSize.value;
+        if (direction.value === 'horizontal') {
+          addedX += size + columnGap;
+        } else { addedY += size + gap; }
+      }
+
+      if (addedX > 0 || addedY > 0) {
+        nextTick(() => {
+          scrollToOffset(
+            addedX > 0 ? relativeScrollX.value + addedX : null,
+            addedY > 0 ? relativeScrollY.value + addedY : null,
+            { behavior: 'auto', isCorrection: true } as ScrollToIndexOptions,
+          );
+        });
+      }
+    }
+
+    initializeMeasurements();
 
     lastItems = [ ...newItems ];
     sizesInitialized.value = true;
@@ -787,34 +745,56 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
    * Updates the host element's offset relative to the scroll container.
    */
   const updateHostOffset = () => {
-    if (props.value.hostElement && typeof window !== 'undefined') {
-      const rect = props.value.hostElement.getBoundingClientRect();
-      const container = props.value.container || window;
-
-      let newX = 0;
-      let newY = 0;
+    if (typeof window === 'undefined') {
+      return;
+    }
+    const container = props.value.container || window;
 
+    const calculateOffset = (el: HTMLElement) => {
+      const rect = el.getBoundingClientRect();
       if (container === window) {
-        newX = rect.left + window.scrollX;
-        newY = rect.top + window.scrollY;
-      } else if (container === props.value.hostElement) {
-        newX = 0;
-        newY = 0;
-      } else if (isElement(container)) {
+        return {
+          x: isRtl.value
+            ? document.documentElement.clientWidth - rect.right - window.scrollX
+            : rect.left + window.scrollX,
+          y: rect.top + window.scrollY,
+        };
+      }
+      if (container === el) {
+        return { x: 0, y: 0 };
+      }
+      if (isElement(container)) {
         const containerRect = container.getBoundingClientRect();
-        newX = rect.left - containerRect.left + container.scrollLeft;
-        newY = rect.top - containerRect.top + container.scrollTop;
+        return {
+          x: isRtl.value
+            ? containerRect.right - rect.right - container.scrollLeft
+            : rect.left - containerRect.left + container.scrollLeft,
+          y: rect.top - containerRect.top + container.scrollTop,
+        };
       }
+      return { x: 0, y: 0 };
+    };
 
-      if (Math.abs(hostOffset.x - newX) > 0.1 || Math.abs(hostOffset.y - newY) > 0.1) {
-        hostOffset.x = newX;
-        hostOffset.y = newY;
+    if (props.value.hostElement) {
+      const newOffset = calculateOffset(props.value.hostElement);
+      if (Math.abs(hostOffset.x - newOffset.x) > 0.1 || Math.abs(hostOffset.y - newOffset.y) > 0.1) {
+        hostOffset.x = newOffset.x;
+        hostOffset.y = newOffset.y;
+      }
+    }
+
+    if (props.value.hostRef) {
+      const newOffset = calculateOffset(props.value.hostRef);
+      if (Math.abs(hostRefOffset.x - newOffset.x) > 0.1 || Math.abs(hostRefOffset.y - newOffset.y) > 0.1) {
+        hostRefOffset.x = newOffset.x;
+        hostRefOffset.y = newOffset.y;
       }
     }
   };
 
   watch([
     () => props.value.items,
+    () => props.value.items.length,
     () => props.value.direction,
     () => props.value.columnCount,
     () => props.value.columnWidth,
@@ -829,7 +809,85 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
     updateHostOffset();
   });
 
-  // --- Range & Visible Items ---
+  watch(isRtl, (newRtl, oldRtl) => {
+    if (oldRtl === undefined || newRtl === oldRtl || !isMounted.value) {
+      return;
+    }
+
+    // Use the oldRtl to correctly interpret the current scrollX
+    if (direction.value === 'vertical') {
+      updateHostOffset();
+      return;
+    }
+
+    const scrollValue = oldRtl ? Math.abs(scrollX.value) : scrollX.value;
+    const oldRelativeScrollX = displayToVirtual(scrollValue, hostOffset.x, scaleX.value);
+
+    // Update host offset for the new direction
+    updateHostOffset();
+
+    // Maintain logical horizontal position when direction changes
+    scrollToOffset(oldRelativeScrollX, null, { behavior: 'auto' });
+  }, { flush: 'sync' });
+
+  watch([ scaleX, scaleY ], () => {
+    if (!isMounted.value || isScrolling.value || isProgrammaticScroll.value) {
+      return;
+    }
+    // Sync display scroll to maintain logical position
+    scrollToOffset(internalScrollX.value, internalScrollY.value, { behavior: 'auto' });
+  });
+
+  watch([ () => props.value.items.length, () => props.value.columnCount ], ([ newLen, newColCount ], [ oldLen, oldColCount ]) => {
+    nextTick(() => {
+      const maxRelX = Math.max(0, totalWidth.value - viewportWidth.value);
+      const maxRelY = Math.max(0, totalHeight.value - viewportHeight.value);
+
+      if (internalScrollX.value > maxRelX || internalScrollY.value > maxRelY) {
+        scrollToOffset(
+          Math.min(internalScrollX.value, maxRelX),
+          Math.min(internalScrollY.value, maxRelY),
+          { behavior: 'auto' },
+        );
+      } else if ((newLen !== oldLen && scaleY.value !== 1) || (newColCount !== oldColCount && scaleX.value !== 1)) {
+        // Even if within bounds, we must sync the display scroll position
+        // because the coordinate scaling factor changed.
+        scrollToOffset(internalScrollX.value, internalScrollY.value, { behavior: 'auto' });
+      }
+      updateHostOffset();
+    });
+  });
+
+  // --- Range & Visible Items ---
+  const getRowIndexAt = (offset: number) => {
+    const gap = props.value.gap || 0;
+    const columnGap = props.value.columnGap || 0;
+    const fixedSize = fixedItemSize.value;
+
+    if (direction.value === 'horizontal') {
+      const step = (fixedSize || 0) + columnGap;
+      if (fixedSize !== null && step > 0) {
+        return Math.floor(offset / step);
+      }
+      return itemSizesX.findLowerBound(offset);
+    }
+    const step = (fixedSize || 0) + gap;
+    if (fixedSize !== null && step > 0) {
+      return Math.floor(offset / step);
+    }
+    return itemSizesY.findLowerBound(offset);
+  };
+
+  const getColIndexAt = (offset: number) => {
+    if (direction.value === 'both') {
+      return columnSizes.findLowerBound(offset);
+    }
+    if (direction.value === 'horizontal') {
+      return getRowIndexAt(offset);
+    }
+    return 0;
+  };
+
   /**
    * Current range of items that should be rendered.
    */
@@ -844,58 +902,26 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       };
     }
 
-    const direction = props.value.direction || 'vertical';
     const bufferBefore = (props.value.ssrRange && !isScrolling.value) ? 0 : (props.value.bufferBefore ?? DEFAULT_BUFFER);
     const bufferAfter = props.value.bufferAfter ?? DEFAULT_BUFFER;
-    const gap = props.value.gap || 0;
-    const columnGap = props.value.columnGap || 0;
-    const fixedSize = fixedItemSize.value;
-    const paddingStartX = getPaddingX(props.value.scrollPaddingStart, direction);
-    const paddingEndX = getPaddingX(props.value.scrollPaddingEnd, direction);
-    const paddingStartY = getPaddingY(props.value.scrollPaddingStart, direction);
-    const paddingEndY = getPaddingY(props.value.scrollPaddingEnd, direction);
-
-    const isVertical = direction === 'vertical' || direction === 'both';
-    const isHorizontal = direction === 'horizontal' || direction === 'both';
-
-    const usableWidth = viewportWidth.value - (isHorizontal ? (paddingStartX + paddingEndX) : 0);
-    const usableHeight = viewportHeight.value - (isVertical ? (paddingStartY + paddingEndY) : 0);
-
-    let start = 0;
-    let end = props.value.items.length;
-
-    if (isVertical) {
-      if (fixedSize !== null) {
-        start = Math.floor(relativeScrollY.value / (fixedSize + gap));
-        end = Math.ceil((relativeScrollY.value + usableHeight) / (fixedSize + gap));
-      } else {
-        start = itemSizesY.findLowerBound(relativeScrollY.value);
-        let currentY = itemSizesY.query(start);
-        let i = start;
-        while (i < props.value.items.length && currentY < relativeScrollY.value + usableHeight) {
-          currentY = itemSizesY.query(++i);
-        }
-        end = i;
-      }
-    } else {
-      if (fixedSize !== null) {
-        start = Math.floor(relativeScrollX.value / (fixedSize + columnGap));
-        end = Math.ceil((relativeScrollX.value + usableWidth) / (fixedSize + columnGap));
-      } else {
-        start = itemSizesX.findLowerBound(relativeScrollX.value);
-        let currentX = itemSizesX.query(start);
-        let i = start;
-        while (i < props.value.items.length && currentX < relativeScrollX.value + usableWidth) {
-          currentX = itemSizesX.query(++i);
-        }
-        end = i;
-      }
-    }
 
-    return {
-      start: Math.max(0, start - bufferBefore),
-      end: Math.min(props.value.items.length, end + bufferAfter),
-    };
+    return calculateRange({
+      direction: direction.value,
+      relativeScrollX: relativeScrollX.value,
+      relativeScrollY: relativeScrollY.value,
+      usableWidth: usableWidth.value,
+      usableHeight: usableHeight.value,
+      itemsLength: props.value.items.length,
+      bufferBefore,
+      bufferAfter,
+      gap: props.value.gap || 0,
+      columnGap: props.value.columnGap || 0,
+      fixedSize: fixedItemSize.value,
+      findLowerBoundY: (offset) => itemSizesY.findLowerBound(offset),
+      findLowerBoundX: (offset) => itemSizesX.findLowerBound(offset),
+      queryY: (idx) => itemSizesY.query(idx),
+      queryX: (idx) => itemSizesX.query(idx),
+    });
   });
 
   /**
@@ -905,25 +931,69 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
     // eslint-disable-next-line ts/no-unused-expressions
     treeUpdateFlag.value;
 
-    const fixedSize = fixedItemSize.value;
-    const gap = props.value.gap || 0;
-    const columnGap = props.value.columnGap || 0;
+    const offsetX = relativeScrollX.value + stickyStartX.value;
+    const offsetY = relativeScrollY.value + stickyStartY.value;
+    const offset = direction.value === 'horizontal' ? offsetX : offsetY;
+    return getRowIndexAt(offset);
+  });
 
-    if (props.value.direction === 'horizontal') {
-      if (fixedSize !== null) {
-        return Math.floor(relativeScrollX.value / (fixedSize + columnGap));
-      }
-      return itemSizesX.findLowerBound(relativeScrollX.value);
+  const columnRange = computed(() => {
+    // eslint-disable-next-line ts/no-unused-expressions
+    treeUpdateFlag.value;
+
+    const totalCols = props.value.columnCount || 0;
+
+    if (!totalCols) {
+      return { start: 0, end: 0, padStart: 0, padEnd: 0 };
     }
-    if (fixedSize !== null) {
-      return Math.floor(relativeScrollY.value / (fixedSize + gap));
+
+    if ((!isHydrated.value || isHydrating.value) && props.value.ssrRange) {
+      const { colStart = 0, colEnd = 0 } = props.value.ssrRange;
+      const safeStart = Math.max(0, colStart);
+      const safeEnd = Math.min(totalCols, colEnd || totalCols);
+
+      const columnGap = props.value.columnGap || 0;
+      const padStart = fixedColumnWidth.value !== null
+        ? safeStart * (fixedColumnWidth.value + columnGap)
+        : columnSizes.query(safeStart);
+
+      const totalColWidth = fixedColumnWidth.value !== null
+        ? totalCols * (fixedColumnWidth.value + columnGap) - columnGap
+        : Math.max(0, columnSizes.query(totalCols) - columnGap);
+
+      const contentEnd = fixedColumnWidth.value !== null
+        ? (safeEnd * (fixedColumnWidth.value + columnGap) - (safeEnd > 0 ? columnGap : 0))
+        : (columnSizes.query(safeEnd) - (safeEnd > 0 ? columnGap : 0));
+
+      return {
+        start: safeStart,
+        end: safeEnd,
+        padStart,
+        padEnd: Math.max(0, totalColWidth - contentEnd),
+      };
     }
-    return itemSizesY.findLowerBound(relativeScrollY.value);
+
+    const colBuffer = (props.value.ssrRange && !isScrolling.value) ? 0 : 2;
+
+    return calculateColumnRange({
+      columnCount: totalCols,
+      relativeScrollX: relativeScrollX.value,
+      usableWidth: usableWidth.value,
+      colBuffer,
+      fixedWidth: fixedColumnWidth.value,
+      columnGap: props.value.columnGap || 0,
+      findLowerBound: (offset) => columnSizes.findLowerBound(offset),
+      query: (idx) => columnSizes.query(idx),
+      totalColsQuery: () => columnSizes.query(totalCols),
+    });
   });
 
   /**
    * List of items to be rendered with their calculated offsets and sizes.
    */
+
+  let lastRenderedItems: RenderedItem<T>[] = [];
+
   const renderedItems = computed<RenderedItem<T>[]>(() => {
     // eslint-disable-next-line ts/no-unused-expressions
     treeUpdateFlag.value;
@@ -934,231 +1004,209 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
     const gap = props.value.gap || 0;
     const columnGap = props.value.columnGap || 0;
     const stickyIndices = sortedStickyIndices.value;
+    const stickySet = stickyIndicesSet.value;
 
-    // Always include relevant sticky items
-    const indicesToRender = new Set<number>();
-    for (let i = start; i < end; i++) {
-      indicesToRender.add(i);
-    }
+    const sortedIndices: number[] = [];
 
     if (isHydrated.value || !props.value.ssrRange) {
       const activeIdx = currentIndex.value;
-      // find the largest index in stickyIndices that is < activeIdx
-      let prevStickyIdx: number | undefined;
-      let low = 0;
-      let high = stickyIndices.length - 1;
-      while (low <= high) {
-        const mid = (low + high) >>> 1;
-        if (stickyIndices[ mid ]! < activeIdx) {
-          prevStickyIdx = stickyIndices[ mid ];
-          low = mid + 1;
-        } else {
-          high = mid - 1;
-        }
-      }
-
-      if (prevStickyIdx !== undefined) {
-        indicesToRender.add(prevStickyIdx);
-      }
+      const prevStickyIdx = findPrevStickyIndex(stickyIndices, activeIdx);
 
-      for (const idx of stickyIndices) {
-        if (idx >= start && idx < end) {
-          indicesToRender.add(idx);
-        }
+      if (prevStickyIdx !== undefined && prevStickyIdx < start) {
+        sortedIndices.push(prevStickyIdx);
       }
     }
 
-    const sortedIndices = Array.from(indicesToRender).sort((a, b) => a - b);
+    for (let i = start; i < end; i++) {
+      sortedIndices.push(i);
+    }
 
     const ssrStartRow = props.value.ssrRange?.start || 0;
+
     const ssrStartCol = props.value.ssrRange?.colStart || 0;
 
     let ssrOffsetX = 0;
     let ssrOffsetY = 0;
 
     if (!isHydrated.value && props.value.ssrRange) {
-      ssrOffsetY = (props.value.direction === 'vertical' || props.value.direction === 'both')
+      ssrOffsetY = (direction.value !== 'horizontal')
         ? (fixedSize !== null ? ssrStartRow * (fixedSize + gap) : itemSizesY.query(ssrStartRow))
         : 0;
 
-      if (props.value.direction === 'horizontal') {
+      if (direction.value === 'horizontal') {
         ssrOffsetX = fixedSize !== null ? ssrStartCol * (fixedSize + columnGap) : itemSizesX.query(ssrStartCol);
-      } else if (props.value.direction === 'both') {
+      } else if (direction.value === 'both') {
         ssrOffsetX = columnSizes.query(ssrStartCol);
       }
     }
 
+    const lastItemsMap = new Map(lastRenderedItems.map((it) => [ it.index, it ]));
+
+    // Optimization: Cache sequential queries to avoid O(log N) tree traversal for every item
+    let lastIndexX = -1;
+    let lastOffsetX = 0;
+    let lastIndexY = -1;
+    let lastOffsetY = 0;
+
+    const queryXCached = (idx: number) => {
+      if (idx === lastIndexX + 1) {
+        lastOffsetX += itemSizesX.get(lastIndexX);
+        lastIndexX = idx;
+        return lastOffsetX;
+      }
+      lastOffsetX = itemSizesX.query(idx);
+      lastIndexX = idx;
+      return lastOffsetX;
+    };
+
+    const queryYCached = (idx: number) => {
+      if (idx === lastIndexY + 1) {
+        lastOffsetY += itemSizesY.get(lastIndexY);
+        lastIndexY = idx;
+        return lastOffsetY;
+      }
+      lastOffsetY = itemSizesY.query(idx);
+      lastIndexY = idx;
+      return lastOffsetY;
+    };
+
+    const itemsStartVU_X = flowStartX.value + stickyStartX.value + paddingStartX.value;
+    const itemsStartVU_Y = flowStartY.value + stickyStartY.value + paddingStartY.value;
+    const wrapperStartDU_X = flowStartX.value + stickyStartX.value;
+    const wrapperStartDU_Y = flowStartY.value + stickyStartY.value;
+
+    const colRange = columnRange.value;
+
     for (const i of sortedIndices) {
       const item = props.value.items[ i ];
       if (item === undefined) {
         continue;
       }
 
-      let x = 0;
-      let y = 0;
-      let width = 0;
-      let height = 0;
-
-      if (props.value.direction === 'horizontal') {
-        x = fixedSize !== null ? i * (fixedSize + columnGap) : itemSizesX.query(i);
-        width = fixedSize !== null ? fixedSize : itemSizesX.get(i) - columnGap;
-        height = viewportHeight.value;
-      } else {
-        // vertical or both
-        y = (props.value.direction === 'vertical' || props.value.direction === 'both') && fixedSize !== null ? i * (fixedSize + gap) : itemSizesY.query(i);
-        height = fixedSize !== null ? fixedSize : itemSizesY.get(i) - gap;
-        width = props.value.direction === 'both' ? totalWidth.value : viewportWidth.value;
-      }
+      const { x, y, width, height } = calculateItemPosition({
+        index: i,
+        direction: direction.value,
+        fixedSize: fixedItemSize.value,
+        gap: props.value.gap || 0,
+        columnGap: props.value.columnGap || 0,
+        usableWidth: usableWidth.value,
+        usableHeight: usableHeight.value,
+        totalWidth: totalSize.value.width,
+        queryY: queryYCached,
+        queryX: queryXCached,
+        getSizeY: (idx) => itemSizesY.get(idx),
+        getSizeX: (idx) => itemSizesX.get(idx),
+        columnRange: colRange,
+      });
 
-      const isSticky = stickyIndices.includes(i);
+      const isSticky = stickySet.has(i);
       const originalX = x;
       const originalY = y;
-      let isStickyActive = false;
-      const stickyOffset = { x: 0, y: 0 };
-
-      if (isSticky) {
-        if (props.value.direction === 'vertical' || props.value.direction === 'both') {
-          if (relativeScrollY.value > originalY) {
-            isStickyActive = true;
-            // Check if next sticky item pushes this one
-            let nextStickyIdx: number | undefined;
-            let low = 0;
-            let high = stickyIndices.length - 1;
-            while (low <= high) {
-              const mid = (low + high) >>> 1;
-              if (stickyIndices[ mid ]! > i) {
-                nextStickyIdx = stickyIndices[ mid ];
-                high = mid - 1;
-              } else {
-                low = mid + 1;
-              }
-            }
-
-            if (nextStickyIdx !== undefined) {
-              const nextStickyY = fixedSize !== null ? nextStickyIdx * (fixedSize + gap) : itemSizesY.query(nextStickyIdx);
-              const distance = nextStickyY - relativeScrollY.value;
-              /* v8 ignore else -- @preserve */
-              if (distance < height) {
-                stickyOffset.y = -(height - distance);
-              }
-            }
-          }
-        } else if (props.value.direction === 'horizontal') {
-          if (relativeScrollX.value > originalX) {
-            isStickyActive = true;
-            // Check if next sticky item pushes this one
-            let nextStickyIdx: number | undefined;
-            let low = 0;
-            let high = stickyIndices.length - 1;
-            while (low <= high) {
-              const mid = (low + high) >>> 1;
-              if (stickyIndices[ mid ]! > i) {
-                nextStickyIdx = stickyIndices[ mid ];
-                high = mid - 1;
-              } else {
-                low = mid + 1;
-              }
-            }
-
-            if (nextStickyIdx !== undefined) {
-              const nextStickyX = fixedSize !== null ? nextStickyIdx * (fixedSize + columnGap) : itemSizesX.query(nextStickyIdx);
-              const distance = nextStickyX - relativeScrollX.value;
-              /* v8 ignore else -- @preserve */
-              if (distance < width) {
-                stickyOffset.x = -(width - distance);
-              }
-            }
-          }
-        }
-      }
 
-      items.push({
-        item,
+      const { isStickyActive, stickyOffset } = calculateStickyItem({
         index: i,
-        offset: { x: originalX - ssrOffsetX, y: originalY - ssrOffsetY },
-        size: { width, height },
+        isSticky,
+        direction: direction.value,
+        relativeScrollX: relativeScrollX.value,
+        relativeScrollY: relativeScrollY.value,
         originalX,
         originalY,
-        isSticky,
-        isStickyActive,
-        stickyOffset,
+        width,
+        height,
+        stickyIndices,
+        fixedSize: fixedItemSize.value,
+        fixedWidth: fixedColumnWidth.value,
+        gap: props.value.gap || 0,
+        columnGap: props.value.columnGap || 0,
+        getItemQueryY: (idx) => itemSizesY.query(idx),
+        getItemQueryX: (idx) => itemSizesX.query(idx),
       });
-    }
-    return items;
-  });
-
-  const columnRange = computed(() => {
-    // eslint-disable-next-line ts/no-unused-expressions
-    treeUpdateFlag.value;
-
-    const totalCols = props.value.columnCount || 0;
-
-    if (!totalCols) {
-      return { start: 0, end: 0, padStart: 0, padEnd: 0 };
-    }
-
-    if ((!isHydrated.value || isHydrating.value) && props.value.ssrRange) {
-      const { colStart = 0, colEnd = 0 } = props.value.ssrRange;
-      const safeStart = Math.max(0, colStart);
-      const safeEnd = Math.min(totalCols, colEnd || totalCols);
-      return {
-        start: safeStart,
-        end: safeEnd,
-        padStart: 0,
-        padEnd: 0,
-      };
-    }
 
-    const start = columnSizes.findLowerBound(relativeScrollX.value);
-    let currentX = columnSizes.query(start);
-    let end = start;
+      const offsetX = isHydrated.value
+        ? (internalScrollX.value / scaleX.value + (originalX + itemsStartVU_X - internalScrollX.value)) - wrapperStartDU_X
+        : (originalX - ssrOffsetX);
+      const offsetY = isHydrated.value
+        ? (internalScrollY.value / scaleY.value + (originalY + itemsStartVU_Y - internalScrollY.value)) - wrapperStartDU_Y
+        : (originalY - ssrOffsetY);
+      const last = lastItemsMap.get(i);
 
-    while (end < totalCols && currentX < relativeScrollX.value + viewportWidth.value) {
-      currentX = columnSizes.query(++end);
+      if (
+        last
+        && last.item === item
+        && last.offset.x === offsetX
+        && last.offset.y === offsetY
+        && last.size.width === width
+        && last.size.height === height
+        && last.isSticky === isSticky
+        && last.isStickyActive === isStickyActive
+        && last.stickyOffset.x === stickyOffset.x
+        && last.stickyOffset.y === stickyOffset.y
+      ) {
+        items.push(last);
+      } else {
+        items.push({
+          item,
+          index: i,
+          offset: { x: offsetX, y: offsetY },
+          size: { width, height },
+          originalX,
+          originalY,
+          isSticky,
+          isStickyActive,
+          stickyOffset: {
+            x: stickyOffset.x,
+            y: stickyOffset.y,
+          },
+        });
+      }
     }
 
-    const colBuffer = (props.value.ssrRange && !isScrolling.value) ? 0 : 2;
-
-    // Add buffer of columns
-    const safeStart = Math.max(0, start - colBuffer);
-    const safeEnd = Math.min(totalCols, end + colBuffer);
+    lastRenderedItems = items;
 
-    const padStart = columnSizes.query(safeStart);
-
-    return {
-      start: safeStart,
-      end: safeEnd,
-      padStart,
-      padEnd: columnSizes.query(totalCols) - columnSizes.query(safeEnd),
-    };
+    return items;
   });
 
-  /**
-   * Detailed information about the current scroll state.
-   */
   const scrollDetails = computed<ScrollDetails<T>>(() => {
     // eslint-disable-next-line ts/no-unused-expressions
     treeUpdateFlag.value;
 
-    const fixedSize = fixedItemSize.value;
-    const columnGap = props.value.columnGap || 0;
+    const currentScrollX = relativeScrollX.value + stickyStartX.value;
+    const currentScrollY = relativeScrollY.value + stickyStartY.value;
 
-    let currentColIndex = 0;
-    if (props.value.direction === 'horizontal' || props.value.direction === 'both') {
-      if (fixedSize !== null) {
-        currentColIndex = Math.floor(relativeScrollX.value / (fixedSize + columnGap));
-      } else {
-        currentColIndex = itemSizesX.findLowerBound(relativeScrollX.value);
-      }
-    }
+    const currentEndScrollX = relativeScrollX.value + (viewportWidth.value - stickyEndX.value) - 1;
+    const currentEndScrollY = relativeScrollY.value + (viewportHeight.value - stickyEndY.value) - 1;
+
+    const currentColIndex = getColIndexAt(currentScrollX);
+    const currentRowIndex = getRowIndexAt(currentScrollY);
+    const currentEndIndex = getRowIndexAt(direction.value === 'horizontal' ? currentEndScrollX : currentEndScrollY);
+    const currentEndColIndex = getColIndexAt(currentEndScrollX);
 
     return {
       items: renderedItems.value,
-      currentIndex: currentIndex.value,
+      currentIndex: currentRowIndex,
       currentColIndex,
-      scrollOffset: { x: relativeScrollX.value, y: relativeScrollY.value },
-      viewportSize: { width: viewportWidth.value, height: viewportHeight.value },
-      totalSize: { width: totalWidth.value, height: totalHeight.value },
+      currentEndIndex,
+      currentEndColIndex,
+      scrollOffset: {
+        x: internalScrollX.value,
+        y: internalScrollY.value,
+      },
+      displayScrollOffset: {
+        x: isRtl.value ? Math.abs(scrollX.value + hostRefOffset.x) : Math.max(0, scrollX.value - hostRefOffset.x),
+        y: Math.max(0, scrollY.value - hostRefOffset.y),
+      },
+      viewportSize: {
+        width: viewportWidth.value,
+        height: viewportHeight.value,
+      },
+      displayViewportSize: {
+        width: viewportWidth.value,
+        height: viewportHeight.value,
+      },
+      totalSize: {
+        width: totalWidth.value,
+        height: totalHeight.value,
+      },
       isScrolling: isScrolling.value,
       isProgrammaticScroll: isProgrammaticScroll.value,
       range: range.value,
@@ -1184,14 +1232,24 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       return;
     }
 
+    updateDirection();
+
     if (target === window || target === document) {
       scrollX.value = window.scrollX;
       scrollY.value = window.scrollY;
+      viewportWidth.value = document.documentElement.clientWidth;
+      viewportHeight.value = document.documentElement.clientHeight;
     } else if (isScrollableElement(target)) {
       scrollX.value = target.scrollLeft;
       scrollY.value = target.scrollTop;
+      viewportWidth.value = target.clientWidth;
+      viewportHeight.value = target.clientHeight;
     }
 
+    const scrollValueX = isRtl.value ? Math.abs(scrollX.value) : scrollX.value;
+    internalScrollX.value = displayToVirtual(scrollValueX, componentOffset.x, scaleX.value);
+    internalScrollY.value = displayToVirtual(scrollY.value, componentOffset.y, scaleY.value);
+
     if (!isScrolling.value) {
       if (!isProgrammaticScroll.value) {
         pendingScroll.value = null;
@@ -1212,41 +1270,57 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
    */
   const updateItemSizes = (updates: Array<{ index: number; inlineSize: number; blockSize: number; element?: HTMLElement | undefined; }>) => {
     let needUpdate = false;
+    let deltaX = 0;
+    let deltaY = 0;
     const gap = props.value.gap || 0;
     const columnGap = props.value.columnGap || 0;
 
+    const currentRelX = relativeScrollX.value;
+    const currentRelY = relativeScrollY.value;
+
+    const firstRowIndex = getRowIndexAt(direction.value === 'horizontal' ? currentRelX : currentRelY);
+    const firstColIndex = getColIndexAt(currentRelX);
+
+    const isHorizontalMode = direction.value === 'horizontal';
+    const isBothMode = direction.value === 'both';
+
+    const processedRows = new Set<number>();
+    const processedCols = new Set<number>();
+
     for (const { index, inlineSize, blockSize, element } of updates) {
+      // Ignore 0-size measurements as they usually indicate hidden/detached elements
+      if (inlineSize <= 0 && blockSize <= 0) {
+        continue;
+      }
+
       const isMeasurable = isDynamicItemSize.value || typeof props.value.itemSize === 'function';
-      if (isMeasurable && index >= 0) {
-        if (props.value.direction === 'horizontal') {
+      if (index >= 0 && !processedRows.has(index) && isMeasurable && blockSize > 0) {
+        processedRows.add(index);
+        if (isHorizontalMode && inlineSize > 0) {
           const oldWidth = itemSizesX.get(index);
           const targetWidth = inlineSize + columnGap;
-          // Apply if:
-          // 1. It's the first measurement (measuredItemsX[index] is 0)
-          // 2. It's a significant change (> 0.5px)
-          /* v8 ignore else -- @preserve */
-          if (!measuredItemsX[ index ] || Math.abs(targetWidth - oldWidth) > 0.5) {
-            itemSizesX.update(index, targetWidth - oldWidth);
+          if (!measuredItemsX[ index ] || Math.abs(targetWidth - oldWidth) > 0.1) {
+            const d = targetWidth - oldWidth;
+            itemSizesX.update(index, d);
             measuredItemsX[ index ] = 1;
             needUpdate = true;
+            if (index < firstRowIndex) {
+              deltaX += d;
+            }
           }
         }
-        if (props.value.direction === 'vertical' || props.value.direction === 'both') {
+        if (!isHorizontalMode) {
           const oldHeight = itemSizesY.get(index);
           const targetHeight = blockSize + gap;
 
-          if (props.value.direction === 'both') {
-            // For grid, we should be careful with decreases because a row height is the max of all its cells.
-            /* v8 ignore else -- @preserve */
-            if (!measuredItemsY[ index ] || Math.abs(targetHeight - oldHeight) > 0.5) {
-              itemSizesY.update(index, targetHeight - oldHeight);
-              measuredItemsY[ index ] = 1;
-              needUpdate = true;
-            }
-          } else if (!measuredItemsY[ index ] || Math.abs(targetHeight - oldHeight) > 0.5) {
-            itemSizesY.update(index, targetHeight - oldHeight);
+          if (!measuredItemsY[ index ] || Math.abs(targetHeight - oldHeight) > 0.1) {
+            const d = targetHeight - oldHeight;
+            itemSizesY.update(index, d);
             measuredItemsY[ index ] = 1;
             needUpdate = true;
+            if (index < firstRowIndex) {
+              deltaY += d;
+            }
           }
         }
       }
@@ -1254,27 +1328,58 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       // Dynamic column width measurement
       const isColMeasurable = isDynamicColumnWidth.value || typeof props.value.columnWidth === 'function';
       if (
-        props.value.direction === 'both'
+        isBothMode
         && element
         && props.value.columnCount
         && isColMeasurable
+        && (inlineSize > 0 || element.dataset.colIndex === undefined)
       ) {
-        const cells = element.dataset.colIndex !== undefined
-          ? [ element ]
-          : Array.from(element.querySelectorAll('[data-col-index]')) as HTMLElement[];
-
-        for (const child of cells) {
-          const colIndex = Number.parseInt(child.dataset.colIndex!, 10);
-
-          /* v8 ignore else -- @preserve */
-          if (colIndex >= 0 && colIndex < (props.value.columnCount || 0)) {
-            const w = child.offsetWidth;
+        const colIndexAttr = element.dataset.colIndex;
+        if (colIndexAttr != null) {
+          const colIndex = Number.parseInt(colIndexAttr, 10);
+          if (colIndex >= 0 && colIndex < (props.value.columnCount || 0) && !processedCols.has(colIndex)) {
+            processedCols.add(colIndex);
             const oldW = columnSizes.get(colIndex);
-            const targetW = w + columnGap;
-            if (Math.abs(oldW - targetW) > 0.5) {
-              columnSizes.update(colIndex, targetW - oldW);
+            const targetW = inlineSize + columnGap;
+
+            if (!measuredColumns[ colIndex ] || Math.abs(oldW - targetW) > 0.1) {
+              const d = targetW - oldW;
+              if (Math.abs(d) > 0.1) {
+                columnSizes.update(colIndex, d);
+                needUpdate = true;
+                if (colIndex < firstColIndex) {
+                  deltaX += d;
+                }
+              }
               measuredColumns[ colIndex ] = 1;
-              needUpdate = true;
+            }
+          }
+        } else {
+          // If the element is a row, try to find cells with data-col-index
+          const cells = element.dataset.colIndex !== undefined
+            ? [ element ]
+            : Array.from(element.querySelectorAll('[data-col-index]')) as HTMLElement[];
+
+          for (const child of cells) {
+            const colIndex = Number.parseInt(child.dataset.colIndex!, 10);
+
+            if (colIndex >= 0 && colIndex < (props.value.columnCount || 0) && !processedCols.has(colIndex)) {
+              processedCols.add(colIndex);
+              const rect = child.getBoundingClientRect();
+              const w = rect.width;
+              const oldW = columnSizes.get(colIndex);
+              const targetW = w + columnGap;
+              if (!measuredColumns[ colIndex ] || Math.abs(oldW - targetW) > 0.1) {
+                const d = targetW - oldW;
+                if (Math.abs(d) > 0.1) {
+                  columnSizes.update(colIndex, d);
+                  needUpdate = true;
+                  if (colIndex < firstColIndex) {
+                    deltaX += d;
+                  }
+                }
+                measuredColumns[ colIndex ] = 1;
+              }
             }
           }
         }
@@ -1283,6 +1388,19 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
 
     if (needUpdate) {
       treeUpdateFlag.value++;
+      // Only compensate if not in a programmatic scroll,
+      // as it would interrupt the browser animation or explicit alignment.
+      const hasPendingScroll = pendingScroll.value !== null || isProgrammaticScroll.value;
+
+      if (!hasPendingScroll && (deltaX !== 0 || deltaY !== 0)) {
+        const contentStartLogicalX = flowStartX.value + stickyStartX.value + paddingStartX.value;
+        const contentStartLogicalY = flowStartY.value + stickyStartY.value + paddingStartY.value;
+        scrollToOffset(
+          deltaX !== 0 ? currentRelX + deltaX + contentStartLogicalX : null,
+          deltaY !== 0 ? currentRelY + deltaY + contentStartLogicalY : null,
+          { behavior: 'auto' },
+        );
+      }
     }
   };
 
@@ -1299,17 +1417,89 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
   };
 
   // --- Scroll Queue / Correction Watchers ---
-  const checkPendingScroll = () => {
+  function checkPendingScroll() {
     if (pendingScroll.value && !isHydrating.value) {
       const { rowIndex, colIndex, options } = pendingScroll.value;
-      const correctionOptions: ScrollToIndexOptions = isScrollToIndexOptions(options)
-        ? { ...options, isCorrection: true }
-        : { align: options as ScrollAlignment | ScrollAlignmentOptions, isCorrection: true };
-      scrollToIndex(rowIndex, colIndex, correctionOptions);
+
+      const isSmooth = isScrollToIndexOptions(options) && options.behavior === 'smooth';
+
+      // If it's a smooth scroll, we wait until it's finished before correcting.
+      if (isSmooth && isScrolling.value) {
+        return;
+      }
+
+      const container = props.value.container || window;
+      const actualScrollX = (typeof window !== 'undefined' && container === window ? window.scrollX : (container as HTMLElement).scrollLeft);
+      const actualScrollY = (typeof window !== 'undefined' && container === window ? window.scrollY : (container as HTMLElement).scrollTop);
+
+      const scrollValueX = isRtl.value ? Math.abs(actualScrollX) : actualScrollX;
+      const scrollValueY = actualScrollY;
+
+      const currentRelX = displayToVirtual(scrollValueX, 0, scaleX.value);
+      const currentRelY = displayToVirtual(scrollValueY, 0, scaleY.value);
+
+      const { targetX, targetY } = calculateScrollTarget({
+        rowIndex,
+        colIndex,
+        options,
+        direction: direction.value,
+        viewportWidth: viewportWidth.value,
+        viewportHeight: viewportHeight.value,
+        totalWidth: virtualWidth.value,
+        totalHeight: virtualHeight.value,
+        gap: props.value.gap || 0,
+        columnGap: props.value.columnGap || 0,
+        fixedSize: fixedItemSize.value,
+        fixedWidth: fixedColumnWidth.value,
+        relativeScrollX: currentRelX,
+        relativeScrollY: currentRelY,
+        getItemSizeY: (idx) => itemSizesY.get(idx),
+        getItemSizeX: (idx) => itemSizesX.get(idx),
+        getItemQueryY: (idx) => itemSizesY.query(idx),
+        getItemQueryX: (idx) => itemSizesX.query(idx),
+        getColumnSize: (idx) => columnSizes.get(idx),
+        getColumnQuery: (idx) => columnSizes.query(idx),
+        scaleX: scaleX.value,
+        scaleY: scaleY.value,
+        hostOffsetX: componentOffset.x,
+        hostOffsetY: componentOffset.y,
+        stickyIndices: sortedStickyIndices.value,
+        stickyStartX: stickyStartX.value,
+        stickyStartY: stickyStartY.value,
+        stickyEndX: stickyEndX.value,
+        stickyEndY: stickyEndY.value,
+        flowPaddingStartX: flowStartX.value,
+        flowPaddingStartY: flowStartY.value,
+        flowPaddingEndX: flowEndX.value,
+        flowPaddingEndY: flowEndY.value,
+        paddingStartX: paddingStartX.value,
+        paddingStartY: paddingStartY.value,
+        paddingEndX: paddingEndX.value,
+        paddingEndY: paddingEndY.value,
+      });
+
+      const toleranceX = 2;
+      const toleranceY = 2;
+      const reachedX = (colIndex === null || colIndex === undefined) || Math.abs(currentRelX - targetX) < toleranceX;
+      const reachedY = (rowIndex === null || rowIndex === undefined) || Math.abs(currentRelY - targetY) < toleranceY;
+
+      const isMeasuredX = colIndex == null || colIndex === undefined || measuredColumns[ colIndex ] === 1;
+      const isMeasuredY = rowIndex == null || rowIndex === undefined || measuredItemsY[ rowIndex ] === 1;
+
+      if (reachedX && reachedY) {
+        if (isMeasuredX && isMeasuredY && !isScrolling.value && !isProgrammaticScroll.value) {
+          pendingScroll.value = null;
+        }
+      } else {
+        const correctionOptions: ScrollToIndexOptions = isScrollToIndexOptions(options)
+          ? { ...options, isCorrection: true }
+          : { align: options as ScrollAlignment | ScrollAlignmentOptions, isCorrection: true };
+        scrollToIndex(rowIndex, colIndex, correctionOptions);
+      }
     }
-  };
+  }
 
-  watch(treeUpdateFlag, checkPendingScroll);
+  watch([ treeUpdateFlag, viewportWidth, viewportHeight ], checkPendingScroll);
 
   watch(isScrolling, (scrolling) => {
     if (!scrolling) {
@@ -1318,6 +1508,8 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
   });
 
   let resizeObserver: ResizeObserver | null = null;
+  let directionObserver: MutationObserver | null = null;
+  let directionInterval: ReturnType<typeof setInterval> | undefined;
 
   const attachEvents = (container: HTMLElement | Window | null) => {
     if (!container || typeof window === 'undefined') {
@@ -1326,21 +1518,34 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
     const scrollTarget = container === window ? document : container;
     scrollTarget.addEventListener('scroll', handleScroll, { passive: true });
 
+    computedStyle = null;
+    updateDirection();
+
+    if (isElement(container)) {
+      directionObserver = new MutationObserver(() => updateDirection());
+      directionObserver.observe(container, { attributes: true, attributeFilter: [ 'dir', 'style' ] });
+    }
+
+    directionInterval = setInterval(updateDirection, 1000);
+
     if (container === window) {
-      viewportWidth.value = window.innerWidth;
-      viewportHeight.value = window.innerHeight;
+      viewportWidth.value = document.documentElement.clientWidth;
+      viewportHeight.value = document.documentElement.clientHeight;
       scrollX.value = window.scrollX;
       scrollY.value = window.scrollY;
 
       const onResize = () => {
-        viewportWidth.value = window.innerWidth;
-        viewportHeight.value = window.innerHeight;
+        updateDirection();
+        viewportWidth.value = document.documentElement.clientWidth;
+        viewportHeight.value = document.documentElement.clientHeight;
         updateHostOffset();
       };
       window.addEventListener('resize', onResize);
       return () => {
         scrollTarget.removeEventListener('scroll', handleScroll);
         window.removeEventListener('resize', onResize);
+        clearInterval(directionInterval);
+        computedStyle = null;
       };
     } else {
       viewportWidth.value = (container as HTMLElement).clientWidth;
@@ -1349,8 +1554,8 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       scrollY.value = (container as HTMLElement).scrollTop;
 
       resizeObserver = new ResizeObserver((entries) => {
+        updateDirection();
         for (const entry of entries) {
-          /* v8 ignore else -- @preserve */
           if (entry.target === container) {
             viewportWidth.value = (container as HTMLElement).clientWidth;
             viewportHeight.value = (container as HTMLElement).clientHeight;
@@ -1362,6 +1567,9 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
       return () => {
         scrollTarget.removeEventListener('scroll', handleScroll);
         resizeObserver?.disconnect();
+        directionObserver?.disconnect();
+        clearInterval(directionInterval);
+        computedStyle = null;
       };
     }
   };
@@ -1371,6 +1579,7 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
   if (getCurrentInstance()) {
     onMounted(() => {
       isMounted.value = true;
+      updateDirection();
 
       watch(() => props.value.container, (newContainer) => {
         cleanup?.();
@@ -1379,15 +1588,16 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
 
       updateHostOffset();
 
-      if (props.value.ssrRange || props.value.initialScrollIndex !== undefined) {
-        nextTick(() => {
-          updateHostOffset();
+      // Ensure we have a layout cycle before considering it hydrated
+      // and starting virtualization. This avoids issues with 0-size viewports.
+      nextTick(() => {
+        updateHostOffset();
+        if (props.value.ssrRange || props.value.initialScrollIndex !== undefined) {
           const initialIndex = props.value.initialScrollIndex !== undefined
             ? props.value.initialScrollIndex
             : props.value.ssrRange?.start;
           const initialAlign = props.value.initialScrollAlign || 'start';
 
-          /* v8 ignore else -- @preserve */
           if (initialIndex !== undefined && initialIndex !== null) {
             scrollToIndex(initialIndex, props.value.ssrRange?.colStart, { align: initialAlign, behavior: 'auto' });
           }
@@ -1397,10 +1607,10 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
           nextTick(() => {
             isHydrating.value = false;
           });
-        });
-      } else {
-        isHydrated.value = true;
-      }
+        } else {
+          isHydrated.value = true;
+        }
+      });
     });
 
     onUnmounted(() => {
@@ -1411,6 +1621,10 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
   /**
    * The list of items currently rendered in the DOM.
    */
+  /**
+   * Resets all dynamic measurements and re-initializes from current props.
+   * Useful if item source data has changed in a way that affects sizes without changing the items array reference.
+   */
   const refresh = () => {
     itemSizesX.resize(0);
     itemSizesY.resize(0);
@@ -1423,73 +1637,203 @@ export function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>)
 
   return {
     /**
-     * Array of items to be rendered with their calculated offsets and sizes.
+     * Array of items currently rendered in the DOM with their calculated offsets and sizes.
+     * Offsets are in Display Units (DU), sizes are in Virtual Units (VU).
+     * @see RenderedItem
      */
     renderedItems,
+
     /**
-     * Total calculated width of all items including gaps.
+     * Total calculated width of all items including gaps (in VU).
      */
     totalWidth,
+
     /**
-     * Total calculated height of all items including gaps.
+     * Total calculated height of all items including gaps (in VU).
      */
     totalHeight,
+
+    /**
+     * Total width to be rendered in the DOM (clamped to browser limits, in DU).
+     */
+    renderedWidth,
+
+    /**
+     * Total height to be rendered in the DOM (clamped to browser limits, in DU).
+     */
+    renderedHeight,
+
     /**
      * Detailed information about the current scroll state.
-     * Includes currentIndex, scrollOffset, viewportSize, totalSize, and isScrolling.
+     * Includes currentIndex, scrollOffset (VU), displayScrollOffset (DU), viewportSize (DU), totalSize (VU), and scrolling status.
+     * @see ScrollDetails
      */
     scrollDetails,
+
+    /**
+     * Helper to get the height of a specific row based on current configuration and measurements.
+     *
+     * @param index - The row index.
+     * @returns The height in VU (excluding gap).
+     */
+    getRowHeight,
+
+    /**
+     * Helper to get the width of a specific column based on current configuration and measurements.
+     *
+     * @param index - The column index.
+     * @returns The width in VU (excluding gap).
+     */
+    getColumnWidth,
+
+    /**
+     * Helper to get the virtual offset of a specific row.
+     *
+     * @param index - The row index.
+     * @returns The virtual offset in VU.
+     */
+    getRowOffset: (index: number) => (flowStartY.value + stickyStartY.value + paddingStartY.value) + itemSizesY.query(index),
+
+    /**
+     * Helper to get the virtual offset of a specific column.
+     *
+     * @param index - The column index.
+     * @returns The virtual offset in VU.
+     */
+    getColumnOffset: (index: number) => (flowStartX.value + stickyStartX.value + paddingStartX.value) + columnSizes.query(index),
+
+    /**
+     * Helper to get the virtual offset of a specific item along the scroll axis.
+     *
+     * @param index - The item index.
+     * @returns The virtual offset in VU.
+     */
+    getItemOffset: (index: number) => (direction.value === 'horizontal' ? (flowStartX.value + stickyStartX.value + paddingStartX.value) + itemSizesX.query(index) : (flowStartY.value + stickyStartY.value + paddingStartY.value) + itemSizesY.query(index)),
+
+    /**
+     * Helper to get the size of a specific item along the scroll axis.
+     *
+     * @param index - The item index.
+     * @returns The size in VU (excluding gap).
+     */
+    getItemSize: (index: number) => {
+      if (direction.value === 'horizontal') {
+        return Math.max(0, itemSizesX.get(index) - (props.value.columnGap || 0));
+      }
+      const itemSize = props.value.itemSize;
+      if (typeof itemSize === 'number' && itemSize > 0) {
+        return itemSize;
+      }
+      if (typeof itemSize === 'function') {
+        const item = props.value.items[ index ];
+        return item !== undefined ? itemSize(item, index) : (props.value.defaultItemSize || DEFAULT_ITEM_SIZE);
+      }
+      return Math.max(0, itemSizesY.get(index) - (props.value.gap || 0));
+    },
+
     /**
      * Programmatically scroll to a specific row and/or column.
-     * @param rowIndex - The row index to scroll to
-     * @param colIndex - The column index to scroll to
-     * @param options - Alignment and behavior options
+     *
+     * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally.
+     * @param colIndex - The column index to scroll to. Pass null to only scroll vertically.
+     * @param options - Alignment and behavior options.
+     * @see ScrollAlignment
+     * @see ScrollToIndexOptions
      */
     scrollToIndex,
+
     /**
-     * Programmatically scroll to a specific pixel offset.
-     * @param x - The pixel offset to scroll to on the X axis
-     * @param y - The pixel offset to scroll to on the Y axis
-     * @param options - Behavior options
+     * Programmatically scroll to a specific pixel offset relative to the content start.
+     *
+     * @param x - The pixel offset to scroll to on the X axis (VU). Pass null to keep current position.
+     * @param y - The pixel offset to scroll to on the Y axis (VU). Pass null to keep current position.
+     * @param options - Scroll options (behavior).
      */
     scrollToOffset,
+
     /**
-     * Stops any currently active programmatic scroll and clears pending corrections.
+     * Stops any currently active smooth scroll animation and clears pending corrections.
      */
     stopProgrammaticScroll,
+
     /**
      * Updates the stored size of an item. Should be called when an item is measured (e.g., via ResizeObserver).
-     * @param index - The item index
-     * @param width - The measured width
-     * @param height - The measured height
-     * @param element - The measured element (optional, used for grid column detection)
+     *
+     * @param index - The item index.
+     * @param width - The measured inlineSize (width in DU).
+     * @param height - The measured blockSize (height in DU).
+     * @param element - The measured element (optional, used for robust grid column detection).
      */
     updateItemSize,
+
     /**
-     * Updates the stored size of multiple items. Should be called when items are measured (e.g., via ResizeObserver).
-     * @param updates - Array of item updates
+     * Updates the stored size of multiple items simultaneously.
+     *
+     * @param updates - Array of measurement updates (sizes in DU).
      */
     updateItemSizes,
+
     /**
      * Recalculates the host element's offset relative to the scroll container.
+     * Useful if the container or host moves without a resize event.
      */
     updateHostOffset,
+
     /**
-     * Information about the current visible range of columns.
+     * Detects the current direction (LTR/RTL) of the scroll container.
      */
-    columnRange,
+    updateDirection,
+
     /**
-     * Helper to get the width of a specific column based on current configuration.
-     * @param index - The column index
+     * Information about the current visible range of columns and their paddings.
+     * @see ColumnRange
      */
-    getColumnWidth,
+    columnRange,
+
     /**
      * Resets all dynamic measurements and re-initializes from props.
+     * Useful if item sizes have changed externally.
      */
     refresh,
+
     /**
      * Whether the component has finished its first client-side mount and hydration.
      */
     isHydrated,
+
+    /**
+     * Whether the container is the window or body.
+     */
+    isWindowContainer,
+
+    /**
+     * Whether the scroll container is in Right-to-Left (RTL) mode.
+     */
+    isRtl,
+
+    /**
+     * Coordinate scaling factor for X axis (VU/DU).
+     */
+    scaleX,
+
+    /**
+     * Coordinate scaling factor for Y axis (VU/DU).
+     */
+    scaleY,
+
+    /**
+     * Absolute offset of the component within its container (DU).
+     */
+    componentOffset,
+
+    /**
+     * Physical width of the items wrapper in the DOM (clamped to browser limits, in DU).
+     */
+    renderedVirtualWidth,
+
+    /**
+     * Physical height of the items wrapper in the DOM (clamped to browser limits, in DU).
+     */
+    renderedVirtualHeight,
   };
 }