clear-virtualizer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Bubnov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# clear-virtualizer
+
+One hook for vertical virtualized lists and tables with dynamic row heights. Rows are measured automatically via `ResizeObserver` — no manual measuring, no fixed heights. Works for an unlimited number of rows.
+
+## Install
+
+```sh
+npm i clear-virtualizer
+```
+
+## Exports
+
+```ts
+import { useVirtualizer, type Options, type ScrollAlign, type VirtualItem } from 'clear-virtualizer';
+```
+
+## API
+
+```ts
+const { virtualItems, scrollHeight, scrollRef, getMeasureRef, scrollToIndex } = useVirtualizer({
+  count: 100000,
+  estimateSize: () => 44,
+  overscan: 10,
+});
+```
+
+| Option         | Type                                       | Description                                              |
+| -------------- |--------------------------------------------| -------------------------------------------------------- |
+| `count`        | `number`                                   | Total number of rows                                     |
+| `estimateSize` | `((index: number) => number) \| undefined` | Approximate row height in px, used until a row is measured |
+| `overscan`     | `number \| undefined`                      | Extra rows rendered above/below the viewport (default: 3) |
+
+| Return value    | Type                                          | Description                                             |
+| --------------- | --------------------------------------------- | ------------------------------------------------------- |
+| `virtualItems`  | `VirtualItem[]`                               | Rows to render: `{ index, start, size, end }` (px)      |
+| `scrollHeight`  | `number`                                      | Total scrollable height (px)                            |
+| `scrollRef`     | `(el: HTMLElement \| null) => void`           | Callback ref — attach to the scroll container           |
+| `getMeasureRef` | `(index: number) => (el: HTMLElement \| null) => void` | Attach the returned ref to each row for measuring |
+| `scrollToIndex` | `(index: number, options?: { align?: ScrollAlign }) => void` | Scroll to a row |
+
+Do not set a fixed `height` on rows — let them size naturally so `getMeasureRef` measures the real height. Position rows with `transform: translateY(...)`.
+
+## List example
+
+```tsx
+import { CSSProperties, ReactNode } from 'react';
+import { useVirtualizer } from 'clear-virtualizer';
+
+export type VirtualizeListProps = {
+	count: number;
+	renderItem: (index: number) => ReactNode;
+	height: CSSProperties['height'];
+	estimateSize?: (index: number) => number;
+	className?: string;
+	overscan?: number;
+	width?: CSSProperties['width'];
+	style?: CSSProperties;
+};
+
+export const VirtualizedList = ({
+	count,
+	renderItem,
+	height,
+	className,
+	style,
+	overscan,
+	estimateSize,
+	width = 'auto',
+}: VirtualizeListProps) => {
+	const { virtualItems, scrollHeight, scrollRef, getMeasureRef } = useVirtualizer({
+		count,
+		estimateSize,
+		overscan,
+	});
+
+	return (
+		<div
+			ref={scrollRef}
+			style={{ height, width, overflow: 'auto', lineHeight: 1.5, ...style }}
+			className={className}
+		>
+			<div style={{ position: 'relative', height: scrollHeight }}>
+				{virtualItems.map(item => (
+					<div
+						key={item.index}
+						ref={getMeasureRef(item.index)}
+						style={{
+							position: 'absolute',
+							top: 0,
+							left: 0,
+							width: '100%',
+							transform: `translateY(${item.start}px)`,
+						}}
+					>
+						{renderItem(item.index)}
+					</div>
+				))}
+			</div>
+		</div>
+	);
+};
+```
+
+## Table example (with @tanstack/react-table and expandable rows)
+
+Column widths must be set on both header and body cells (`header.getSize()` / `cell.column.getSize()` with `flexShrink: 0`) so columns stay aligned. The header is `position: sticky`. Expanding a row changes its height — it gets re-measured automatically.
+
+```tsx
+import { useState } from 'react';
+import {
+	useReactTable,
+	getCoreRowModel,
+	getExpandedRowModel,
+	flexRender,
+	createColumnHelper,
+} from '@tanstack/react-table';
+import { useVirtualizer } from 'clear-virtualizer';
+
+type User = { id: number; name: string; email: string; role: string };
+
+const data: User[] = Array.from({ length: 100_000 }, (_, i) => ({
+	id: i + 1,
+	name: `User ${i + 1}`,
+	email: `user${i + 1}@example.com`,
+	role: ['Admin', 'Editor', 'Viewer'][i % 3],
+}));
+
+const columnHelper = createColumnHelper<User>();
+
+const columns = [
+	columnHelper.display({
+		id: 'expand',
+		size: 40,
+		cell: ({ row }) => (
+			<button onClick={() => row.toggleExpanded()}>{row.getIsExpanded() ? '▼' : '▶'}</button>
+		),
+	}),
+	columnHelper.accessor('id', { header: 'ID', size: 60 }),
+	columnHelper.accessor('name', { header: 'Name', size: 150 }),
+	columnHelper.accessor('email', { header: 'Email', size: 200 }),
+	columnHelper.accessor('role', { header: 'Role', size: 100 }),
+];
+
+export const VirtualTable = () => {
+	const [expanded, setExpanded] = useState<Record<string, boolean>>({});
+	const table = useReactTable({
+		data,
+		columns,
+		state: { expanded },
+		onExpandedChange: old => setExpanded(old as Record<string, boolean>),
+		getExpandedRowModel: getExpandedRowModel(),
+		getCoreRowModel: getCoreRowModel(),
+	});
+	const rows = table.getRowModel().rows;
+	const { virtualItems, scrollHeight, scrollRef, getMeasureRef } = useVirtualizer({
+		count: rows.length,
+		estimateSize: () => 44,
+		overscan: 10,
+	});
+
+	return (
+		<div ref={scrollRef} style={{ height: 550, overflow: 'auto' }}>
+			<div style={{ position: 'relative', height: scrollHeight }}>
+				{table.getHeaderGroups().map(headerGroup => (
+					<div
+						key={headerGroup.id}
+						style={{ position: 'sticky', top: 0, zIndex: 1, display: 'flex', background: '#f5f5f5' }}
+					>
+						{headerGroup.headers.map(header => (
+							<div
+								key={header.id}
+								style={{ width: header.getSize(), padding: '8px 12px', flexShrink: 0 }}
+							>
+								{flexRender(header.column.columnDef.header, header.getContext())}
+							</div>
+						))}
+					</div>
+				))}
+				{virtualItems.map(virtualRow => {
+					const row = rows[virtualRow.index];
+					return (
+						<div
+							key={row.id}
+							ref={getMeasureRef(virtualRow.index)}
+							style={{
+								position: 'absolute',
+								top: 0,
+								left: 0,
+								width: '100%',
+								transform: `translateY(${virtualRow.start}px)`,
+							}}
+						>
+							<div style={{ display: 'flex' }}>
+								{row.getVisibleCells().map(cell => (
+									<div
+										key={cell.id}
+										style={{ width: cell.column.getSize(), padding: '8px 12px', flexShrink: 0 }}
+									>
+										{flexRender(cell.column.columnDef.cell, cell.getContext())}
+									</div>
+								))}
+							</div>
+							{row.getIsExpanded() && (
+								<div style={{ padding: '8px 16px' }}>Details for {row.original.name}</div>
+							)}
+						</div>
+					);
+				})}
+			</div>
+		</div>
+	);
+};
+```
+
+## scrollToIndex
+
+```ts
+scrollToIndex(34567); // align defaults to 'start'
+scrollToIndex(34567, { align: 'center' });
+scrollToIndex(34567, { align: 'end' });
+```
+
+| `align`  | Positions the row...              |
+| -------- | --------------------------------- |
+| `start`  | At the top of the viewport (default) |
+| `center` | In the middle of the viewport     |
+| `end`    | At the bottom of the viewport     |
+
+If the row is far away and its neighbors were never measured, the hook first jumps to the estimated position, measures the rows around the target, and corrects the position. A manual scroll during that correction cancels it and hands control back to the user.
+
+## estimateSize
+
+`estimateSize` is only a starting guess until real measurements arrive. The closer it is to reality, the less rows visually shift on fast scroll through unmeasured regions: underestimated rows overlap until measured, overestimated ones leave temporary gaps. Pass a value near your average row height.
+
+## Limitations
+
+- Vertical scrolling only — no horizontal virtualization, no sticky columns.
+- The internal offset tree keeps one `float64` per row (~8 MB per million rows).
+- Server-side rendering is not covered by tests.
+
+## License
+
+MIT

package/lib/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_OVERSCAN = 3;
+export declare const SCROLL_CONVERGED_THRESHOLD = 0.5;
+export declare const SETTLE_QUIET_FRAMES = 3;
+export declare const SETTLE_MAX_FRAMES = 180;
+export declare const SETTLE_WINDOW = 40;

package/lib/fenwickTree.d.ts

@@ -0,0 +1,10 @@
+export declare class FenwickTree {
+    private tree;
+    private n;
+    private logn;
+    constructor(sizes: Float64Array);
+    update(i: number, delta: number): void;
+    prefixSum(i: number): number;
+    total(): number;
+    findByPrefixSum(target: number): number;
+}

package/lib/hooks/useLatest.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="react" />
+export declare const useLatest: <T>(value: T) => import("react").MutableRefObject<T>;

package/lib/hooks/useVirtualizer.d.ts

@@ -0,0 +1,21 @@
+export type VirtualItem = {
+    index: number;
+    start: number;
+    size: number;
+    end: number;
+};
+export type Options = {
+    count: number;
+    estimateSize?: (index: number) => number;
+    overscan?: number;
+};
+export type ScrollAlign = 'start' | 'center' | 'end';
+export declare function useVirtualizer({ count, estimateSize, overscan }: Options): {
+    virtualItems: VirtualItem[];
+    scrollHeight: number;
+    scrollToIndex: (index: number, options?: {
+        align?: ScrollAlign;
+    }) => void;
+    scrollRef: (element: HTMLElement | null) => void;
+    getMeasureRef: (index: number) => (el: HTMLElement | null) => void;
+};

package/lib/index.cjs

@@ -0,0 +1,410 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const useLatest = (value) => {
+  const ref = react.useRef(value);
+  react.useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+};
+class FenwickTree {
+  constructor(sizes) {
+    __publicField(this, "tree");
+    __publicField(this, "n");
+    __publicField(this, "logn");
+    this.n = sizes.length;
+    this.tree = new Float64Array(this.n + 1);
+    for (let i = 0; i < this.n; i++)
+      this.tree[i + 1] = sizes[i];
+    for (let x = 1; x <= this.n; x++) {
+      const parent = x + (x & -x);
+      if (parent <= this.n)
+        this.tree[parent] += this.tree[x];
+    }
+    this.logn = this.n > 0 ? Math.floor(Math.log2(this.n)) : 0;
+  }
+  update(i, delta) {
+    for (let x = i + 1; x <= this.n; x += x & -x)
+      this.tree[x] += delta;
+  }
+  prefixSum(i) {
+    let sum = 0;
+    for (let x = i; x > 0; x -= x & -x)
+      sum += this.tree[x];
+    return sum;
+  }
+  total() {
+    return this.prefixSum(this.n);
+  }
+  findByPrefixSum(target) {
+    let pos = 0;
+    let remaining = target;
+    const EPS = 1e-6;
+    for (let pw = 1 << this.logn; pw > 0; pw >>= 1) {
+      const next = pos + pw;
+      if (next <= this.n && this.tree[next] <= remaining + EPS) {
+        pos = next;
+        remaining -= this.tree[next];
+      }
+    }
+    return pos;
+  }
+}
+const DEFAULT_OVERSCAN = 3;
+const SCROLL_CONVERGED_THRESHOLD = 0.5;
+const SETTLE_QUIET_FRAMES = 3;
+const SETTLE_MAX_FRAMES = 180;
+const SETTLE_WINDOW = 40;
+const DEFAULT_SIZE = 24;
+const SAFE_MAX_HEIGHT = 15e6;
+const getScale = (logicalTotal) => {
+  if (logicalTotal <= SAFE_MAX_HEIGHT)
+    return { scale: 1, physicalTotal: logicalTotal };
+  return { scale: SAFE_MAX_HEIGHT / logicalTotal, physicalTotal: SAFE_MAX_HEIGHT };
+};
+const getFenwickTree = (count, estimateSize) => {
+  const sizes = new Float64Array(count);
+  for (let i = 0; i < count; i++)
+    sizes[i] = estimateSize?.(i) || DEFAULT_SIZE;
+  return new FenwickTree(sizes);
+};
+const classifySettleScroll = (scrollTop, targetScrollTop, version, baseVersion) => {
+  if (Math.abs(scrollTop - targetScrollTop) <= SCROLL_CONVERGED_THRESHOLD)
+    return "converged";
+  return version !== baseVersion ? "stale-tree" : "user";
+};
+const getViewportRange = (tree, logicalScrollOffset, containerHeight, scale, overscanValue, countValue) => {
+  const viewportStart = tree.findByPrefixSum(logicalScrollOffset);
+  const viewportEnd = tree.findByPrefixSum(logicalScrollOffset + containerHeight / scale);
+  return {
+    startIndex: Math.max(viewportStart - overscanValue, 0),
+    endIndex: Math.min(viewportEnd + overscanValue + 1, countValue),
+    viewportStart,
+    viewportEnd
+  };
+};
+const computeTargetScrollTop = (tree, index, align, containerHeight, scale, count) => {
+  const targetIndex = Math.max(0, Math.min(index, count - 1));
+  const targetOffset = tree.prefixSum(targetIndex);
+  const itemLogicalSize = tree.prefixSum(targetIndex + 1) - targetOffset;
+  let logicalScrollOffset;
+  switch (align) {
+    case "center":
+      logicalScrollOffset = targetOffset + (itemLogicalSize - containerHeight / scale) / 2;
+      break;
+    case "end":
+      logicalScrollOffset = targetOffset + itemLogicalSize - containerHeight / scale;
+      break;
+    default:
+      logicalScrollOffset = targetOffset;
+  }
+  return { targetScrollTop: Math.max(0, logicalScrollOffset * scale), logicalScrollOffset };
+};
+function useVirtualizer({ count, estimateSize, overscan = DEFAULT_OVERSCAN }) {
+  const [scrollOffset, setScrollOffset] = react.useState({ value: 0 });
+  const [forcedRange, setForcedRange] = react.useState(null);
+  const scrollElementRef = react.useRef(null);
+  const rafRef = react.useRef(null);
+  const observersRef = react.useRef(/* @__PURE__ */ new Map());
+  const containerObserverRef = react.useRef(null);
+  const prevCountRef = react.useRef(count);
+  const fenwickRef = react.useRef(null);
+  const refCacheRef = react.useRef(/* @__PURE__ */ new Map());
+  const countRef = useLatest(count);
+  const overscanRef = useLatest(overscan);
+  const pendingTargetRef = react.useRef(null);
+  const tickRafRef = react.useRef(null);
+  const settleFramesRef = react.useRef(0);
+  const quietFramesRef = react.useRef(0);
+  const treeVersionRef = react.useRef(0);
+  const versionAtJumpRef = react.useRef(0);
+  if (fenwickRef.current === null || !fenwickRef.current.total())
+    fenwickRef.current = getFenwickTree(count, estimateSize);
+  if (prevCountRef.current !== count) {
+    fenwickRef.current = getFenwickTree(count, estimateSize);
+    prevCountRef.current = count;
+  }
+  const computeItems = react.useCallback(
+    (physicalScrollOffset) => {
+      const el = scrollElementRef.current;
+      const tree = fenwickRef.current;
+      if (!el || count === 0 || !tree)
+        return { virtualItems: [], scrollHeight: 0 };
+      const containerHeight = el.clientHeight;
+      const logicalTotal = tree.total();
+      const { scale, physicalTotal } = getScale(logicalTotal);
+      const pendingTarget = pendingTargetRef.current;
+      let logicalScrollOffset;
+      if (pendingTarget !== null) {
+        const { targetScrollTop, logicalScrollOffset: targetLogicalOffset } = computeTargetScrollTop(
+          tree,
+          pendingTarget.index,
+          pendingTarget.align,
+          containerHeight,
+          scale,
+          count
+        );
+        logicalScrollOffset = targetLogicalOffset;
+        if (Math.abs(el.scrollTop - targetScrollTop) > SCROLL_CONVERGED_THRESHOLD) {
+          el.scrollTop = targetScrollTop;
+        }
+      } else {
+        logicalScrollOffset = physicalScrollOffset / scale;
+      }
+      let startIndex;
+      let endIndex;
+      if (forcedRange) {
+        startIndex = forcedRange.start;
+        endIndex = forcedRange.end;
+      } else {
+        const { startIndex: viewportStartIndex, endIndex: viewportEndIndex } = getViewportRange(
+          tree,
+          logicalScrollOffset,
+          containerHeight,
+          scale,
+          overscan,
+          count
+        );
+        startIndex = viewportStartIndex;
+        endIndex = viewportEndIndex;
+      }
+      const startOffsetLogical = tree.prefixSum(startIndex);
+      const startOffsetPhysical = (pendingTarget !== null ? logicalScrollOffset * scale : physicalScrollOffset) + (startOffsetLogical - logicalScrollOffset) * scale;
+      const virtualItems2 = [];
+      let offset = startOffsetPhysical;
+      for (let i = startIndex; i < endIndex; i++) {
+        const size = (tree.prefixSum(i + 1) - tree.prefixSum(i)) * scale;
+        virtualItems2.push({ index: i, start: offset, size, end: offset + size });
+        offset += size;
+      }
+      return { virtualItems: virtualItems2, scrollHeight: physicalTotal };
+    },
+    [count, forcedRange, overscan]
+  );
+  const measureElement = react.useCallback((element, index) => {
+    if (!element) {
+      const entry = observersRef.current.get(index);
+      if (entry) {
+        entry.observer.disconnect();
+        observersRef.current.delete(index);
+      }
+      return;
+    }
+    const existing = observersRef.current.get(index);
+    if (existing && existing.element === element)
+      return;
+    if (existing) {
+      existing.observer.disconnect();
+      observersRef.current.delete(index);
+    }
+    const observer = new ResizeObserver(([entry]) => {
+      const height = entry?.borderBoxSize[0]?.blockSize;
+      if (height == null || !fenwickRef.current)
+        return;
+      const tree = fenwickRef.current;
+      const { scale } = getScale(tree.total());
+      const logicalHeight = height / scale;
+      const prevSize = tree.prefixSum(index + 1) - tree.prefixSum(index);
+      if (Math.abs(prevSize - logicalHeight) < 0.5)
+        return;
+      tree.update(index, logicalHeight - prevSize);
+      treeVersionRef.current += 1;
+      setScrollOffset((prevState) => ({ ...prevState }));
+    });
+    observer.observe(element);
+    observersRef.current.set(index, { observer, element });
+  }, []);
+  const getMeasureRef = react.useCallback(
+    (index) => {
+      let fn = refCacheRef.current.get(index);
+      if (!fn) {
+        fn = (el) => {
+          measureElement(el, index);
+          if (el === null)
+            refCacheRef.current.delete(index);
+        };
+        refCacheRef.current.set(index, fn);
+      }
+      return fn;
+    },
+    [measureElement]
+  );
+  const releaseSettle = react.useCallback((scrollTop) => {
+    if (tickRafRef.current !== null) {
+      cancelAnimationFrame(tickRafRef.current);
+      tickRafRef.current = null;
+    }
+    pendingTargetRef.current = null;
+    setForcedRange(null);
+    setScrollOffset({ value: scrollTop });
+  }, []);
+  const scheduleTick = react.useCallback(() => {
+    if (tickRafRef.current !== null)
+      return;
+    tickRafRef.current = requestAnimationFrame(() => {
+      tickRafRef.current = null;
+      const el = scrollElementRef.current;
+      const tree = fenwickRef.current;
+      const pending = pendingTargetRef.current;
+      if (!el || !tree || !pending)
+        return;
+      const countValue = countRef.current;
+      const overscanValue = overscanRef.current;
+      settleFramesRef.current += 1;
+      if (settleFramesRef.current > SETTLE_MAX_FRAMES) {
+        releaseSettle(el.scrollTop);
+        return;
+      }
+      const { scale } = getScale(tree.total());
+      const { targetScrollTop } = computeTargetScrollTop(
+        tree,
+        pending.index,
+        pending.align,
+        el.clientHeight,
+        scale,
+        countValue
+      );
+      const kind = classifySettleScroll(
+        el.scrollTop,
+        targetScrollTop,
+        treeVersionRef.current,
+        versionAtJumpRef.current
+      );
+      if (kind === "user") {
+        releaseSettle(el.scrollTop);
+        return;
+      }
+      if (kind === "stale-tree") {
+        versionAtJumpRef.current = treeVersionRef.current;
+        quietFramesRef.current = 0;
+        setScrollOffset((prevState) => ({ ...prevState }));
+        scheduleTick();
+        return;
+      }
+      if (treeVersionRef.current !== versionAtJumpRef.current) {
+        versionAtJumpRef.current = treeVersionRef.current;
+        quietFramesRef.current = 0;
+      } else {
+        quietFramesRef.current += 1;
+      }
+      if (quietFramesRef.current < SETTLE_QUIET_FRAMES) {
+        scheduleTick();
+        return;
+      }
+      const { startIndex, endIndex } = getViewportRange(
+        tree,
+        el.scrollTop / scale,
+        el.clientHeight,
+        scale,
+        overscanValue,
+        countValue
+      );
+      const targetIndex = Math.max(0, Math.min(pending.index, countValue - 1));
+      if (targetIndex < startIndex || targetIndex > endIndex) {
+        releaseSettle(el.scrollTop);
+        return;
+      }
+      releaseSettle(el.scrollTop);
+    });
+  }, [releaseSettle, countRef, overscanRef]);
+  const handleScroll = react.useCallback(() => {
+    if (rafRef.current !== null)
+      cancelAnimationFrame(rafRef.current);
+    rafRef.current = requestAnimationFrame(() => {
+      rafRef.current = null;
+      const el = scrollElementRef.current;
+      const tree = fenwickRef.current;
+      if (!el || !tree)
+        return;
+      const pending = pendingTargetRef.current;
+      if (pending !== null) {
+        const { scale } = getScale(tree.total());
+        const { targetScrollTop } = computeTargetScrollTop(
+          tree,
+          pending.index,
+          pending.align,
+          el.clientHeight,
+          scale,
+          countRef.current
+        );
+        const kind = classifySettleScroll(
+          el.scrollTop,
+          targetScrollTop,
+          treeVersionRef.current,
+          versionAtJumpRef.current
+        );
+        if (kind === "user") {
+          releaseSettle(el.scrollTop);
+          return;
+        }
+        if (kind === "stale-tree")
+          versionAtJumpRef.current = treeVersionRef.current;
+      }
+      setScrollOffset({ value: el.scrollTop });
+    });
+  }, [releaseSettle, countRef]);
+  const scrollRef = react.useCallback(
+    (element) => {
+      if (scrollElementRef.current)
+        scrollElementRef.current.removeEventListener("scroll", handleScroll);
+      containerObserverRef.current?.disconnect();
+      containerObserverRef.current = null;
+      scrollElementRef.current = element;
+      if (element) {
+        element.addEventListener("scroll", handleScroll, { passive: true });
+        if (typeof ResizeObserver !== "undefined") {
+          const observer = new ResizeObserver(() => {
+            setScrollOffset((prevState) => ({ ...prevState }));
+          });
+          observer.observe(element);
+          containerObserverRef.current = observer;
+        }
+      }
+      setScrollOffset(element ? { value: element?.scrollTop } : { value: 0 });
+    },
+    [handleScroll]
+  );
+  const { virtualItems, scrollHeight } = react.useMemo(
+    () => computeItems(scrollOffset.value),
+    [computeItems, scrollOffset]
+  );
+  const jumpToIndex = react.useCallback(
+    (index, align) => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+      if (tickRafRef.current !== null) {
+        cancelAnimationFrame(tickRafRef.current);
+        tickRafRef.current = null;
+      }
+      settleFramesRef.current = 0;
+      quietFramesRef.current = 0;
+      pendingTargetRef.current = { index, align };
+      versionAtJumpRef.current = treeVersionRef.current;
+      const rangeStart = Math.max(index - SETTLE_WINDOW, 0);
+      const rangeEnd = Math.min(index + SETTLE_WINDOW + 1, count);
+      setForcedRange({ start: rangeStart, end: rangeEnd });
+      setScrollOffset((prevState) => ({ ...prevState }));
+      scheduleTick();
+    },
+    [count, scheduleTick]
+  );
+  const scrollToIndex = react.useCallback(
+    (index, options) => {
+      if (index < 0 || index >= count)
+        return;
+      jumpToIndex(index, options?.align ?? "start");
+    },
+    [count, jumpToIndex]
+  );
+  return { virtualItems: virtualItems ?? [], scrollHeight, scrollToIndex, scrollRef, getMeasureRef };
+}
+exports.useVirtualizer = useVirtualizer;

package/lib/index.d.ts

@@ -0,0 +1 @@
+export { useVirtualizer, type Options, type ScrollAlign, type VirtualItem } from './hooks/useVirtualizer';

package/lib/index.js

@@ -0,0 +1,410 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+import { useRef, useEffect, useState, useCallback, useMemo } from "react";
+const useLatest = (value) => {
+  const ref = useRef(value);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+};
+class FenwickTree {
+  constructor(sizes) {
+    __publicField(this, "tree");
+    __publicField(this, "n");
+    __publicField(this, "logn");
+    this.n = sizes.length;
+    this.tree = new Float64Array(this.n + 1);
+    for (let i = 0; i < this.n; i++)
+      this.tree[i + 1] = sizes[i];
+    for (let x = 1; x <= this.n; x++) {
+      const parent = x + (x & -x);
+      if (parent <= this.n)
+        this.tree[parent] += this.tree[x];
+    }
+    this.logn = this.n > 0 ? Math.floor(Math.log2(this.n)) : 0;
+  }
+  update(i, delta) {
+    for (let x = i + 1; x <= this.n; x += x & -x)
+      this.tree[x] += delta;
+  }
+  prefixSum(i) {
+    let sum = 0;
+    for (let x = i; x > 0; x -= x & -x)
+      sum += this.tree[x];
+    return sum;
+  }
+  total() {
+    return this.prefixSum(this.n);
+  }
+  findByPrefixSum(target) {
+    let pos = 0;
+    let remaining = target;
+    const EPS = 1e-6;
+    for (let pw = 1 << this.logn; pw > 0; pw >>= 1) {
+      const next = pos + pw;
+      if (next <= this.n && this.tree[next] <= remaining + EPS) {
+        pos = next;
+        remaining -= this.tree[next];
+      }
+    }
+    return pos;
+  }
+}
+const DEFAULT_OVERSCAN = 3;
+const SCROLL_CONVERGED_THRESHOLD = 0.5;
+const SETTLE_QUIET_FRAMES = 3;
+const SETTLE_MAX_FRAMES = 180;
+const SETTLE_WINDOW = 40;
+const DEFAULT_SIZE = 24;
+const SAFE_MAX_HEIGHT = 15e6;
+const getScale = (logicalTotal) => {
+  if (logicalTotal <= SAFE_MAX_HEIGHT)
+    return { scale: 1, physicalTotal: logicalTotal };
+  return { scale: SAFE_MAX_HEIGHT / logicalTotal, physicalTotal: SAFE_MAX_HEIGHT };
+};
+const getFenwickTree = (count, estimateSize) => {
+  const sizes = new Float64Array(count);
+  for (let i = 0; i < count; i++)
+    sizes[i] = estimateSize?.(i) || DEFAULT_SIZE;
+  return new FenwickTree(sizes);
+};
+const classifySettleScroll = (scrollTop, targetScrollTop, version, baseVersion) => {
+  if (Math.abs(scrollTop - targetScrollTop) <= SCROLL_CONVERGED_THRESHOLD)
+    return "converged";
+  return version !== baseVersion ? "stale-tree" : "user";
+};
+const getViewportRange = (tree, logicalScrollOffset, containerHeight, scale, overscanValue, countValue) => {
+  const viewportStart = tree.findByPrefixSum(logicalScrollOffset);
+  const viewportEnd = tree.findByPrefixSum(logicalScrollOffset + containerHeight / scale);
+  return {
+    startIndex: Math.max(viewportStart - overscanValue, 0),
+    endIndex: Math.min(viewportEnd + overscanValue + 1, countValue),
+    viewportStart,
+    viewportEnd
+  };
+};
+const computeTargetScrollTop = (tree, index, align, containerHeight, scale, count) => {
+  const targetIndex = Math.max(0, Math.min(index, count - 1));
+  const targetOffset = tree.prefixSum(targetIndex);
+  const itemLogicalSize = tree.prefixSum(targetIndex + 1) - targetOffset;
+  let logicalScrollOffset;
+  switch (align) {
+    case "center":
+      logicalScrollOffset = targetOffset + (itemLogicalSize - containerHeight / scale) / 2;
+      break;
+    case "end":
+      logicalScrollOffset = targetOffset + itemLogicalSize - containerHeight / scale;
+      break;
+    default:
+      logicalScrollOffset = targetOffset;
+  }
+  return { targetScrollTop: Math.max(0, logicalScrollOffset * scale), logicalScrollOffset };
+};
+function useVirtualizer({ count, estimateSize, overscan = DEFAULT_OVERSCAN }) {
+  const [scrollOffset, setScrollOffset] = useState({ value: 0 });
+  const [forcedRange, setForcedRange] = useState(null);
+  const scrollElementRef = useRef(null);
+  const rafRef = useRef(null);
+  const observersRef = useRef(/* @__PURE__ */ new Map());
+  const containerObserverRef = useRef(null);
+  const prevCountRef = useRef(count);
+  const fenwickRef = useRef(null);
+  const refCacheRef = useRef(/* @__PURE__ */ new Map());
+  const countRef = useLatest(count);
+  const overscanRef = useLatest(overscan);
+  const pendingTargetRef = useRef(null);
+  const tickRafRef = useRef(null);
+  const settleFramesRef = useRef(0);
+  const quietFramesRef = useRef(0);
+  const treeVersionRef = useRef(0);
+  const versionAtJumpRef = useRef(0);
+  if (fenwickRef.current === null || !fenwickRef.current.total())
+    fenwickRef.current = getFenwickTree(count, estimateSize);
+  if (prevCountRef.current !== count) {
+    fenwickRef.current = getFenwickTree(count, estimateSize);
+    prevCountRef.current = count;
+  }
+  const computeItems = useCallback(
+    (physicalScrollOffset) => {
+      const el = scrollElementRef.current;
+      const tree = fenwickRef.current;
+      if (!el || count === 0 || !tree)
+        return { virtualItems: [], scrollHeight: 0 };
+      const containerHeight = el.clientHeight;
+      const logicalTotal = tree.total();
+      const { scale, physicalTotal } = getScale(logicalTotal);
+      const pendingTarget = pendingTargetRef.current;
+      let logicalScrollOffset;
+      if (pendingTarget !== null) {
+        const { targetScrollTop, logicalScrollOffset: targetLogicalOffset } = computeTargetScrollTop(
+          tree,
+          pendingTarget.index,
+          pendingTarget.align,
+          containerHeight,
+          scale,
+          count
+        );
+        logicalScrollOffset = targetLogicalOffset;
+        if (Math.abs(el.scrollTop - targetScrollTop) > SCROLL_CONVERGED_THRESHOLD) {
+          el.scrollTop = targetScrollTop;
+        }
+      } else {
+        logicalScrollOffset = physicalScrollOffset / scale;
+      }
+      let startIndex;
+      let endIndex;
+      if (forcedRange) {
+        startIndex = forcedRange.start;
+        endIndex = forcedRange.end;
+      } else {
+        const { startIndex: viewportStartIndex, endIndex: viewportEndIndex } = getViewportRange(
+          tree,
+          logicalScrollOffset,
+          containerHeight,
+          scale,
+          overscan,
+          count
+        );
+        startIndex = viewportStartIndex;
+        endIndex = viewportEndIndex;
+      }
+      const startOffsetLogical = tree.prefixSum(startIndex);
+      const startOffsetPhysical = (pendingTarget !== null ? logicalScrollOffset * scale : physicalScrollOffset) + (startOffsetLogical - logicalScrollOffset) * scale;
+      const virtualItems2 = [];
+      let offset = startOffsetPhysical;
+      for (let i = startIndex; i < endIndex; i++) {
+        const size = (tree.prefixSum(i + 1) - tree.prefixSum(i)) * scale;
+        virtualItems2.push({ index: i, start: offset, size, end: offset + size });
+        offset += size;
+      }
+      return { virtualItems: virtualItems2, scrollHeight: physicalTotal };
+    },
+    [count, forcedRange, overscan]
+  );
+  const measureElement = useCallback((element, index) => {
+    if (!element) {
+      const entry = observersRef.current.get(index);
+      if (entry) {
+        entry.observer.disconnect();
+        observersRef.current.delete(index);
+      }
+      return;
+    }
+    const existing = observersRef.current.get(index);
+    if (existing && existing.element === element)
+      return;
+    if (existing) {
+      existing.observer.disconnect();
+      observersRef.current.delete(index);
+    }
+    const observer = new ResizeObserver(([entry]) => {
+      const height = entry?.borderBoxSize[0]?.blockSize;
+      if (height == null || !fenwickRef.current)
+        return;
+      const tree = fenwickRef.current;
+      const { scale } = getScale(tree.total());
+      const logicalHeight = height / scale;
+      const prevSize = tree.prefixSum(index + 1) - tree.prefixSum(index);
+      if (Math.abs(prevSize - logicalHeight) < 0.5)
+        return;
+      tree.update(index, logicalHeight - prevSize);
+      treeVersionRef.current += 1;
+      setScrollOffset((prevState) => ({ ...prevState }));
+    });
+    observer.observe(element);
+    observersRef.current.set(index, { observer, element });
+  }, []);
+  const getMeasureRef = useCallback(
+    (index) => {
+      let fn = refCacheRef.current.get(index);
+      if (!fn) {
+        fn = (el) => {
+          measureElement(el, index);
+          if (el === null)
+            refCacheRef.current.delete(index);
+        };
+        refCacheRef.current.set(index, fn);
+      }
+      return fn;
+    },
+    [measureElement]
+  );
+  const releaseSettle = useCallback((scrollTop) => {
+    if (tickRafRef.current !== null) {
+      cancelAnimationFrame(tickRafRef.current);
+      tickRafRef.current = null;
+    }
+    pendingTargetRef.current = null;
+    setForcedRange(null);
+    setScrollOffset({ value: scrollTop });
+  }, []);
+  const scheduleTick = useCallback(() => {
+    if (tickRafRef.current !== null)
+      return;
+    tickRafRef.current = requestAnimationFrame(() => {
+      tickRafRef.current = null;
+      const el = scrollElementRef.current;
+      const tree = fenwickRef.current;
+      const pending = pendingTargetRef.current;
+      if (!el || !tree || !pending)
+        return;
+      const countValue = countRef.current;
+      const overscanValue = overscanRef.current;
+      settleFramesRef.current += 1;
+      if (settleFramesRef.current > SETTLE_MAX_FRAMES) {
+        releaseSettle(el.scrollTop);
+        return;
+      }
+      const { scale } = getScale(tree.total());
+      const { targetScrollTop } = computeTargetScrollTop(
+        tree,
+        pending.index,
+        pending.align,
+        el.clientHeight,
+        scale,
+        countValue
+      );
+      const kind = classifySettleScroll(
+        el.scrollTop,
+        targetScrollTop,
+        treeVersionRef.current,
+        versionAtJumpRef.current
+      );
+      if (kind === "user") {
+        releaseSettle(el.scrollTop);
+        return;
+      }
+      if (kind === "stale-tree") {
+        versionAtJumpRef.current = treeVersionRef.current;
+        quietFramesRef.current = 0;
+        setScrollOffset((prevState) => ({ ...prevState }));
+        scheduleTick();
+        return;
+      }
+      if (treeVersionRef.current !== versionAtJumpRef.current) {
+        versionAtJumpRef.current = treeVersionRef.current;
+        quietFramesRef.current = 0;
+      } else {
+        quietFramesRef.current += 1;
+      }
+      if (quietFramesRef.current < SETTLE_QUIET_FRAMES) {
+        scheduleTick();
+        return;
+      }
+      const { startIndex, endIndex } = getViewportRange(
+        tree,
+        el.scrollTop / scale,
+        el.clientHeight,
+        scale,
+        overscanValue,
+        countValue
+      );
+      const targetIndex = Math.max(0, Math.min(pending.index, countValue - 1));
+      if (targetIndex < startIndex || targetIndex > endIndex) {
+        releaseSettle(el.scrollTop);
+        return;
+      }
+      releaseSettle(el.scrollTop);
+    });
+  }, [releaseSettle, countRef, overscanRef]);
+  const handleScroll = useCallback(() => {
+    if (rafRef.current !== null)
+      cancelAnimationFrame(rafRef.current);
+    rafRef.current = requestAnimationFrame(() => {
+      rafRef.current = null;
+      const el = scrollElementRef.current;
+      const tree = fenwickRef.current;
+      if (!el || !tree)
+        return;
+      const pending = pendingTargetRef.current;
+      if (pending !== null) {
+        const { scale } = getScale(tree.total());
+        const { targetScrollTop } = computeTargetScrollTop(
+          tree,
+          pending.index,
+          pending.align,
+          el.clientHeight,
+          scale,
+          countRef.current
+        );
+        const kind = classifySettleScroll(
+          el.scrollTop,
+          targetScrollTop,
+          treeVersionRef.current,
+          versionAtJumpRef.current
+        );
+        if (kind === "user") {
+          releaseSettle(el.scrollTop);
+          return;
+        }
+        if (kind === "stale-tree")
+          versionAtJumpRef.current = treeVersionRef.current;
+      }
+      setScrollOffset({ value: el.scrollTop });
+    });
+  }, [releaseSettle, countRef]);
+  const scrollRef = useCallback(
+    (element) => {
+      if (scrollElementRef.current)
+        scrollElementRef.current.removeEventListener("scroll", handleScroll);
+      containerObserverRef.current?.disconnect();
+      containerObserverRef.current = null;
+      scrollElementRef.current = element;
+      if (element) {
+        element.addEventListener("scroll", handleScroll, { passive: true });
+        if (typeof ResizeObserver !== "undefined") {
+          const observer = new ResizeObserver(() => {
+            setScrollOffset((prevState) => ({ ...prevState }));
+          });
+          observer.observe(element);
+          containerObserverRef.current = observer;
+        }
+      }
+      setScrollOffset(element ? { value: element?.scrollTop } : { value: 0 });
+    },
+    [handleScroll]
+  );
+  const { virtualItems, scrollHeight } = useMemo(
+    () => computeItems(scrollOffset.value),
+    [computeItems, scrollOffset]
+  );
+  const jumpToIndex = useCallback(
+    (index, align) => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+      if (tickRafRef.current !== null) {
+        cancelAnimationFrame(tickRafRef.current);
+        tickRafRef.current = null;
+      }
+      settleFramesRef.current = 0;
+      quietFramesRef.current = 0;
+      pendingTargetRef.current = { index, align };
+      versionAtJumpRef.current = treeVersionRef.current;
+      const rangeStart = Math.max(index - SETTLE_WINDOW, 0);
+      const rangeEnd = Math.min(index + SETTLE_WINDOW + 1, count);
+      setForcedRange({ start: rangeStart, end: rangeEnd });
+      setScrollOffset((prevState) => ({ ...prevState }));
+      scheduleTick();
+    },
+    [count, scheduleTick]
+  );
+  const scrollToIndex = useCallback(
+    (index, options) => {
+      if (index < 0 || index >= count)
+        return;
+      jumpToIndex(index, options?.align ?? "start");
+    },
+    [count, jumpToIndex]
+  );
+  return { virtualItems: virtualItems ?? [], scrollHeight, scrollToIndex, scrollRef, getMeasureRef };
+}
+export {
+  useVirtualizer
+};

package/lib/utils.d.ts

@@ -0,0 +1,19 @@
+import { FenwickTree } from './fenwickTree';
+type SettleScroll = 'converged' | 'stale-tree' | 'user';
+export declare const getScale: (logicalTotal: number) => {
+    scale: number;
+    physicalTotal: number;
+};
+export declare const getFenwickTree: (count: number, estimateSize?: ((index: number) => number) | undefined) => FenwickTree;
+export declare const classifySettleScroll: (scrollTop: number, targetScrollTop: number, version: number, baseVersion: number) => SettleScroll;
+export declare const getViewportRange: (tree: FenwickTree, logicalScrollOffset: number, containerHeight: number, scale: number, overscanValue: number, countValue: number) => {
+    startIndex: number;
+    endIndex: number;
+    viewportStart: number;
+    viewportEnd: number;
+};
+export declare const computeTargetScrollTop: (tree: FenwickTree, index: number, align: 'start' | 'center' | 'end', containerHeight: number, scale: number, count: number) => {
+    targetScrollTop: number;
+    logicalScrollOffset: number;
+};
+export {};

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "clear-virtualizer",
+  "version": "0.1.0",
+  "description": "A lightweight React hook for virtualized lists and tables with dynamic row heights, measured automatically",
+  "type": "module",
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "author": {
+    "name": "Andrew Bubnov"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/AndrewBubnov/virtualize#readme",
+  "bugs": {
+    "url": "https://github.com/AndrewBubnov/virtualize/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndrewBubnov/virtualize.git"
+  },
+  "keywords": [
+    "react",
+    "virtualized",
+    "virtualization",
+    "virtual-list",
+    "react-virtualized",
+    "react-window",
+    "windowing",
+    "infinite-scroll",
+    "large-lists",
+    "performance",
+    "scroll",
+    "dom-virtualization",
+    "resize-observer",
+    "dynamic-heights",
+    "layout-engine",
+    "ui-performance",
+    "frontend",
+    "react-components",
+    "list-rendering",
+    "overscan",
+    "table"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:lib": "vite build --config src/vite.config.ts && tsc --emitDeclarationOnly -p tsconfig.lib.json",
+    "prepublishOnly": "npm run build:lib",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "node src/__tests__/e2e/repro-scroll.mjs"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@tanstack/react-table": "^8.21.3",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/node": "^26.6.2",
+    "@types/react": "^18.2.15",
+    "@types/react-dom": "^18.2.7",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitejs/plugin-react": "^4.0.3",
+    "eslint": "^8.45.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.3",
+    "jsdom": "^30.0.1",
+    "lorem-ipsum": "^2.0.8",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.0.2",
+    "vite": "^4.4.5",
+    "vite-plugin-eslint": "^1.8.1",
+    "vite-tsconfig-paths": "^4.2.0",
+    "vitest": "^1.6.1"
+  }
+}