@aiquants/virtualscroll 1.18.5 → 1.19.0

package/src/VirtualScroll.spec.ts

@@ -0,0 +1,623 @@
+/**
+ * Provides regression tests for VirtualScroll range calculations.
+ *
+ * VirtualScroll のレンジ計算に関する回帰テストを提供。
+ */
+import { act, render } from "@testing-library/react"
+import React from "react"
+import { createRoot } from "react-dom/client"
+import { describe, expect, it, vi } from "vitest"
+import { FenwickMapTree } from "./useFenwickMapTree.ts"
+import { computeRenderingRanges, VirtualScroll, type VirtualScrollHandle } from "./VirtualScroll.tsx"
+
+/**
+ * Produces a uniform height resolver for testing.
+ *
+ * テスト用に一定の高さを返却する関数を生成。
+ */
+const createUniformHeightGetter = (height: number) => (_index: number) => height
+// const LARGE_ITEM_COUNT = 9_007_199_254_740_991
+const LARGE_ITEM_COUNT = Number.MAX_SAFE_INTEGER
+// const LARGE_ITEM_COUNT = 1_0_000_000_000_000_000
+// const LARGE_ITEM_COUNT = 1_000_000_000_000_000_000
+
+/**
+ * Ensures the range computation clamps scroll offsets that exceed total height.
+ *
+ * レンジ計算が合計高さを超えるスクロールオフセットを抑制することを確認。
+ */
+const clampScenario = () => {
+    const itemCount = 10
+    const itemHeight = 30
+    const viewportSize = 120
+    const overscanCount = 0
+    const fenwick = new FenwickMapTree(itemCount, itemHeight, { materialize: true })
+    const getter = createUniformHeightGetter(itemHeight)
+    const ranges = computeRenderingRanges(9999, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+    const expectedVisibleCount = Math.ceil(viewportSize / itemHeight)
+    expect(ranges.visibleEndIndex).toBe(itemCount - 1)
+    expect(ranges.visibleStartIndex).toBeGreaterThanOrEqual(itemCount - expectedVisibleCount)
+    expect(ranges.renderingEndIndex).toBe(itemCount - 1)
+}
+
+/**
+ * Custom Fenwick tree that always yields a missing index to force fallback.
+ *
+ * フォールバック動作を強制するために常にインデックス未発見を返す Fenwick 木。
+ */
+class ForceFallbackFenwick extends FenwickMapTree {
+    /**
+     * Always reports an unfound index to exercise fallback handling.
+     *
+     * フォールバック処理を動作させるため常に未発見インデックスを返却。
+     */
+    findIndexAtOrAfter(..._args: Parameters<FenwickMapTree["findIndexAtOrAfter"]>): { index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined } {
+        return { index: -1, total: this.getTotal(), cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+    }
+}
+
+/**
+ * Confirms that the fallback snaps ranges to the tail when no index is located.
+ *
+ * インデックスが見つからない場合にレンジが末尾へ寄ることを確認。
+ */
+const fallbackScenario = () => {
+    const itemCount = 6
+    const itemHeight = 40
+    const viewportSize = 160
+    const overscanCount = 2
+    const fenwick = new ForceFallbackFenwick(itemCount, itemHeight, { materialize: true })
+    const getter = createUniformHeightGetter(itemHeight)
+    const ranges = computeRenderingRanges(500, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+    const expectedVisibleCount = Math.ceil(viewportSize / itemHeight)
+    const expectedVisibleStart = Math.max(0, itemCount - expectedVisibleCount)
+    expect(ranges.visibleStartIndex).toBe(expectedVisibleStart)
+    expect(ranges.visibleEndIndex).toBe(itemCount - 1)
+    expect(ranges.renderingStartIndex).toBe(Math.max(0, expectedVisibleStart - overscanCount))
+}
+
+/**
+ * Ensures clamp logic remains efficient with extremely large datasets.
+ *
+ * 超大規模データセットでもクランプ処理が有効であることを確認。
+ */
+const clampScenarioLarge = () => {
+    const itemCount = LARGE_ITEM_COUNT
+    const itemHeight = 30
+    const viewportSize = 240
+    const overscanCount = 1
+    const fenwick = new FenwickMapTree(itemCount, itemHeight)
+    const getter = createUniformHeightGetter(itemHeight)
+    const overscrollPosition = fenwick.getTotal() * 1.01
+    const ranges = computeRenderingRanges(overscrollPosition, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+    const expectedVisibleCount = Math.ceil(viewportSize / itemHeight)
+    const expectedVisibleStart = Math.max(0, itemCount - expectedVisibleCount)
+    expect(ranges.visibleEndIndex).toBe(itemCount - 1)
+    expect(ranges.visibleStartIndex).toBe(expectedVisibleStart)
+    expect(ranges.renderingEndIndex).toBe(itemCount - 1)
+    expect(ranges.renderingStartIndex).toBe(Math.max(0, expectedVisibleStart - overscanCount))
+}
+
+/**
+ * Confirms fallback remains tail-aligned for massive inputs.
+ *
+ * 超大規模データでもフォールバックが末尾寄せのままであることを確認。
+ */
+const fallbackScenarioLarge = () => {
+    const itemCount = LARGE_ITEM_COUNT
+    const itemHeight = 40
+    const viewportSize = 200
+    const overscanCount = 3
+    const fenwick = new ForceFallbackFenwick(itemCount, itemHeight)
+    const getter = createUniformHeightGetter(itemHeight)
+    const ranges = computeRenderingRanges(Number.MAX_SAFE_INTEGER, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+    const expectedVisibleCount = Math.ceil(viewportSize / itemHeight)
+    const expectedVisibleStart = Math.max(0, itemCount - expectedVisibleCount)
+    expect(ranges.visibleStartIndex).toBe(expectedVisibleStart)
+    expect(ranges.visibleEndIndex).toBe(itemCount - 1)
+    expect(ranges.renderingStartIndex).toBe(Math.max(0, expectedVisibleStart - overscanCount))
+}
+
+/**
+ * Validates head clamp with extremely large collections.
+ *
+ * 超大規模データで下限クランプが先頭位置を維持することを確認。
+ */
+const underflowScenarioLarge = () => {
+    const itemCount = LARGE_ITEM_COUNT
+    const itemHeight = 25
+    const viewportSize = 125
+    const overscanCount = 4
+    const fenwick = new FenwickMapTree(itemCount, itemHeight)
+    const getter = createUniformHeightGetter(itemHeight)
+    const ranges = computeRenderingRanges(-Number.MAX_SAFE_INTEGER, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+    const expectedVisibleCount = Math.ceil(viewportSize / itemHeight)
+    const expectedVisibleEnd = Math.min(itemCount - 1, expectedVisibleCount - 1)
+    expect(ranges.visibleStartIndex).toBe(0)
+    expect(ranges.renderingStartIndex).toBe(0)
+    expect(ranges.visibleEndIndex).toBe(expectedVisibleEnd)
+    expect(ranges.renderingEndIndex).toBe(Math.min(itemCount - 1, expectedVisibleEnd + overscanCount))
+}
+
+/**
+ * Verifies that underflowing scroll offsets clamp to the head range.
+ *
+ * スクロールオフセットの下限越えが先頭レンジに丸められることを確認。
+ */
+const underflowScenario = () => {
+    const itemCount = 8
+    const itemHeight = 25
+    const viewportSize = 100
+    const overscanCount = 3
+    const fenwick = new FenwickMapTree(itemCount, itemHeight, { materialize: true })
+    const getter = createUniformHeightGetter(itemHeight)
+    const ranges = computeRenderingRanges(-250, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+    const expectedVisibleCount = Math.ceil(viewportSize / itemHeight)
+    const expectedVisibleEnd = Math.min(itemCount - 1, expectedVisibleCount - 1)
+    expect(ranges.visibleStartIndex).toBe(0)
+    expect(ranges.renderingStartIndex).toBe(0)
+    expect(ranges.visibleEndIndex).toBe(expectedVisibleEnd)
+    expect(ranges.renderingEndIndex).toBe(Math.min(itemCount - 1, expectedVisibleEnd + overscanCount))
+}
+
+/**
+ * Ensures partially visible items at the bottom are included in the visible range.
+ *
+ * 下部で部分的に見えているアイテムが可視範囲に含まれることを確認。
+ */
+const partialVisibilityScenario = () => {
+    const itemCount = 10
+    const itemHeight = 100
+    const viewportSize = 300
+    const overscanCount = 0
+    const scrollPosition = 150
+
+    const fenwick = new FenwickMapTree(itemCount, itemHeight, { materialize: true })
+    const getter = (_index: number) => itemHeight
+
+    const ranges = computeRenderingRanges(scrollPosition, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+
+    // Index 0: 0-100
+    // Index 1: 100-200 (visible from 150-200, height 50)
+    // Index 2: 200-300 (visible full, height 100)
+    // Index 3: 300-400 (visible full, height 100)
+    // Index 4: 400-500 (visible from 400-450, height 50)
+
+    // Total visible height needed: 300
+    // 50 (idx 1) + 100 (idx 2) + 100 (idx 3) + 50 (idx 4) = 300
+
+    expect(ranges.visibleStartIndex).toBe(1)
+    expect(ranges.visibleEndIndex).toBe(4)
+}
+
+describe("computeRenderingRanges", () => {
+    it("スクロール上限を超えた場合でも末尾レンジを維持する", () => {
+        clampScenario()
+    })
+
+    it("Fenwick が未発見を返しても末尾にフォールバックする", () => {
+        fallbackScenario()
+    })
+
+    it("スクロール下限を下回っても先頭レンジを維持する", () => {
+        underflowScenario()
+    })
+
+    it("超大規模データでも上限クランプが高速に動作する", () => {
+        clampScenarioLarge()
+    })
+
+    it("超大規模データでもフォールバックが末尾へ寄る", () => {
+        fallbackScenarioLarge()
+    })
+
+    it("超大規模データでも下限クランプが先頭レンジを保つ", () => {
+        underflowScenarioLarge()
+    })
+
+    it("部分的に見えているアイテムも可視範囲に含める", () => {
+        partialVisibilityScenario()
+    })
+
+    /**
+     * Ensures a long run of zero-height (collapsed) rows does not force a full forward scan.
+     *
+     * 高さ0（折りたたみ）の連続行があっても前方走査が全件に膨らまないことを確認。
+     */
+    it("高さ0の折りたたみ行が連続してもビューポート先頭以降を全件走査しない", () => {
+        const itemCount = 100_000
+        const viewportSize = 200
+        const overscanCount = 2
+        // 木は全行 40px と推定 (getter と不一致) のままにして、ジャンプが前進できないケースを再現する。
+        const fenwick = new FenwickMapTree(itemCount, 40, { materialize: true })
+        // index 5..89999 が折りたたみ(高さ0)、それ以外は 40px。
+        const getter = (index: number) => (index < 5 ? 40 : index < 90_000 ? 0 : 40)
+        const ranges = computeRenderingRanges(200, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+        // ジャンプ不能 (木と getter の不一致) の場合でも、連続 0 行の閾値近傍で有界に打ち切られる。
+        // ガードが無いと 90,000 件近くまで走査してしまう。
+        expect(ranges.renderingEndIndex).toBeLessThan(2000)
+    })
+
+    /**
+     * Ensures sporadic zero-height rows inside the viewport do not truncate the forward scan.
+     *
+     * 可視域途中の散発的な高さ0行で前方走査が打ち切られないことを確認 (描画不足回帰の再発防止)。
+     */
+    it("可視域途中の高さ0行があっても以降の可視行が描画される", () => {
+        const itemCount = 100
+        const viewportSize = 300
+        const overscanCount = 2
+        const getter = (index: number) => (index === 5 ? 0 : 30)
+        const fenwick = new FenwickMapTree(itemCount, getter, { materialize: true, sampleRange: { from: 0, to: itemCount - 1 } })
+        const ranges = computeRenderingRanges(0, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+        // 行 0-4 (150px) + 行 5 (0px) + 行 6-10 (150px) で 300px を充足する。
+        expect(ranges.visibleStartIndex).toBe(0)
+        expect(ranges.visibleEndIndex).toBe(10)
+    })
+
+    /**
+     * Ensures the backward fill continues across a zero-height row when scrolled to the tail.
+     *
+     * 末尾スクロール時の後方充填が高さ0行を跨いで継続することを確認 (ビューポート空白化回帰の再発防止)。
+     */
+    it("末尾スクロール時の後方充填が高さ0行を跨いで継続する", () => {
+        const itemCount = 20
+        const viewportSize = 300
+        const overscanCount = 0
+        const getter = (index: number) => (index === 15 ? 0 : 30)
+        const fenwick = new FenwickMapTree(itemCount, getter, { materialize: true, sampleRange: { from: 0, to: itemCount - 1 } })
+        // 総高さ 570px の最下部へスクロール。
+        const ranges = computeRenderingRanges(570, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+        expect(ranges.visibleEndIndex).toBe(19)
+        // 高さ0の行15を跨いで行9まで埋め戻される (打ち切られると行15のみ=被覆0pxになる)。
+        expect(ranges.visibleStartIndex).toBe(9)
+    })
+
+    /**
+     * Ensures a huge contiguous run of zero-height rows is skipped via an O(log n) Fenwick jump.
+     *
+     * 大量連続の高さ0行を Fenwick 木の O(log n) ジャンプで飛び越えて可視域を充足することを確認。
+     */
+    it("大量連続の高さ0行は次の非0行へジャンプして可視域を充足する", () => {
+        const itemCount = 100_000
+        const viewportSize = 200
+        const overscanCount = 2
+        const getter = (index: number) => (index < 5 ? 40 : index < 90_000 ? 0 : 40)
+        // 木にも実際の高さを与える (ジャンプは木の累積和に基づくため)。
+        const fenwick = new FenwickMapTree(itemCount, getter, { materialize: true, sampleRange: { from: 0, to: itemCount - 1 } })
+        const ranges = computeRenderingRanges(200, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+        // 行 5..89999 (高さ0) を飛び越え、行 90000..90004 (200px) で可視域を充足する。
+        expect(ranges.visibleStartIndex).toBe(5)
+        expect(ranges.visibleEndIndex).toBe(90_004)
+    })
+
+    /**
+     * Ensures the backward fill also jumps across a huge zero-height run via the Fenwick tree.
+     *
+     * 後方充填でも大量連続の高さ0行を Fenwick 木のジャンプで飛び越えることを確認。
+     */
+    it("後方充填でも大量連続の高さ0行を飛び越えて埋め戻す", () => {
+        const itemCount = 2010
+        const viewportSize = 300
+        const overscanCount = 0
+        // 行 0..4 と行 2005..2009 が 40px、その間の 2000 行が高さ0。総高さ 400px。
+        const getter = (index: number) => (index < 5 || index >= 2005 ? 40 : 0)
+        const fenwick = new FenwickMapTree(itemCount, getter, { materialize: true, sampleRange: { from: 0, to: itemCount - 1 } })
+        const ranges = computeRenderingRanges(400, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+        expect(ranges.visibleEndIndex).toBe(2009)
+        // 0 行の連続 (5..2004) を後方ジャンプで跨ぎ、行 2 まで埋め戻される。
+        expect(ranges.visibleStartIndex).toBe(2)
+    })
+
+    /**
+     * Ensures the huge (bigint) path also continues across sporadic zero-height rows.
+     *
+     * 巨大サイズ (bigint) パスでも散発的な高さ0行を跨いで前方走査が継続することを確認。
+     */
+    it("超大規模データでも散発的な高さ0行を跨いで前方走査する", () => {
+        const itemCount = LARGE_ITEM_COUNT
+        const viewportSize = 120
+        const overscanCount = 0
+        const getter = (index: number) => (index === 2 ? 0 : 30)
+        const fenwick = new FenwickMapTree(itemCount, getter)
+        const ranges = computeRenderingRanges(0, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+        expect(ranges.visibleStartIndex).toBe(0)
+        // 行 0,1,3,4 (計 120px) + 高さ0の行2 で充足する (行2で打ち切られない)。
+        expect(ranges.visibleEndIndex).toBe(4)
+    })
+
+    /**
+     * Ensures the huge (bigint) path backward fill continues across a zero-height row at the tail.
+     *
+     * 巨大サイズ (bigint) パスの後方充填が末尾付近の高さ0行を跨いで継続することを確認。
+     */
+    it("超大規模データでも末尾付近の高さ0行を跨いで後方充填する", () => {
+        const itemCount = LARGE_ITEM_COUNT
+        const viewportSize = 120
+        const overscanCount = 0
+        const getter = (index: number) => (index === itemCount - 3 ? 0 : 30)
+        const fenwick = new FenwickMapTree(itemCount, getter)
+        const ranges = computeRenderingRanges(fenwick.getTotal() * 1.01, viewportSize, overscanCount, itemCount, getter, fenwick, fenwick.getTotal())
+        expect(ranges.visibleEndIndex).toBe(itemCount - 1)
+        // 高さ0の行 (itemCount-3) を跨いで行 itemCount-5 まで埋め戻される。
+        expect(ranges.visibleStartIndex).toBe(itemCount - 5)
+    })
+})
+
+/**
+ * Regression tests for VirtualScroll DOM behaviors (empty list & coordinate system).
+ *
+ * VirtualScroll の DOM 挙動（空リスト・座標系）に関する回帰テスト。
+ */
+describe("VirtualScroll component", () => {
+    it("itemCount=0 でも scrollToIndex/scrollTo/updateItemSize/focusItemAtIndex が例外を投げない", () => {
+        const ref = React.createRef<VirtualScrollHandle>()
+        render(
+            React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, {
+                ref,
+                itemCount: 0,
+                getItem: (index: number) => `Item ${index}`,
+                getItemHeight: () => 40,
+                viewportSize: 200,
+                children: (item: string) => React.createElement("div", null, item),
+            }),
+        )
+        const handle = ref.current
+        expect(handle).not.toBeNull()
+        if (!handle) {
+            return
+        }
+        expect(() =>
+            act(() => {
+                handle.scrollToIndex(0)
+                handle.scrollTo(0)
+                handle.updateItemSize(0, 100)
+                handle.focusItemAtIndex(0)
+            }),
+        ).not.toThrow()
+    })
+
+    it("上部インセット指定時、行 top はコンテンツ絶対座標（=二重加算なし）でラッパーは transform で追従する", () => {
+        const { container } = render(
+            React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, {
+                itemCount: 20,
+                getItem: (index: number) => `Item ${index}`,
+                getItemHeight: () => 40,
+                viewportSize: 200,
+                contentInsets: { top: 50, bottom: 30 },
+                children: (item: string) => React.createElement("div", { style: { height: 40 } }, item),
+            }),
+        )
+
+        // 先頭行 (index 0) の top はコンテンツ絶対座標 0（旧実装ではインセット二重適用で 50px になっていた）。
+        const firstItem = container.querySelector('[data-index="0"]') as HTMLElement | null
+        expect(firstItem).not.toBeNull()
+        expect(firstItem?.style.top).toBe("0px")
+
+        // ラッパーはインライン position:relative を持たず（CSS の position:absolute を活かす）、transform で移動する。
+        const wrapper = container.querySelector(".aqvs-items-wrapper") as HTMLElement | null
+        expect(wrapper).not.toBeNull()
+        expect(wrapper?.style.position).toBe("")
+        expect(wrapper?.style.transform).toContain("translateY")
+    })
+
+    /**
+     * Extracts the numeric translateY value from a wrapper transform string.
+     *
+     * ラッパーの transform 文字列から translateY の数値を取り出すユーティリティ。
+     */
+    const parseTranslateY = (transform: string): number => {
+        const match = /translateY\((-?[\d.]+)px\)/.exec(transform)
+        expect(match).not.toBeNull()
+        return Number(match?.[1])
+    }
+
+    it("深い initialScrollIndex でも行 top と translateY が量子化アンカーで小さな値に収まり視覚位置が保たれる", () => {
+        const itemCount = 100_000
+        const itemHeight = 40
+        const initialScrollIndex = 50_000
+        const { container } = render(
+            React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, {
+                itemCount,
+                getItem: (index: number) => `Item ${index}`,
+                getItemHeight: () => itemHeight,
+                viewportSize: 200,
+                initialScrollIndex,
+                children: (item: string) => React.createElement("div", { style: { height: itemHeight } }, item),
+            }),
+        )
+
+        const wrapper = container.querySelector(".aqvs-items-wrapper") as HTMLElement | null
+        expect(wrapper).not.toBeNull()
+        if (!wrapper) {
+            return
+        }
+        const translateY = parseTranslateY(wrapper.style.transform)
+        const paneScrollPosition = initialScrollIndex * itemHeight // 2,000,000px (>2^20)
+
+        // ラッパーの translateY はアンカー基準の小さな値に収まる (アンカー無しでは -2,000,000px 級)。
+        expect(Math.abs(translateY)).toBeLessThan(2 ** 20)
+
+        const items = Array.from(container.querySelectorAll("[data-virtualscroll-item]")) as HTMLElement[]
+        expect(items.length).toBeGreaterThan(0)
+        for (const element of items) {
+            const index = Number(element.dataset.index)
+            const top = Number.parseFloat(element.style.top)
+            // 行 top はアンカー基準の小さな値 (アンカー無しでは約 2,000,000px でレイアウト精度を圧迫)。
+            expect(Math.abs(top)).toBeLessThan(2 ** 20)
+            // 視覚位置の恒等式: top + translateY = 絶対座標 - ペイン位置 (インセット 0)。
+            expect(top + translateY).toBeCloseTo(index * itemHeight - paneScrollPosition, 6)
+        }
+    })
+
+    it("可視域より上の行の updateItemSize 後、行 top が最新の prefix 和で再計算される (visibleItems の失効)", () => {
+        const itemCount = 1000
+        const itemHeight = 40
+        const ref = React.createRef<VirtualScrollHandle>()
+        const { container } = render(
+            React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, {
+                ref,
+                itemCount,
+                getItem: (index: number) => `Item ${index}`,
+                getItemHeight: () => itemHeight,
+                viewportSize: 200,
+                children: (item: string) => React.createElement("div", { style: { height: itemHeight } }, item),
+            }),
+        )
+        const handle = ref.current
+        expect(handle).not.toBeNull()
+        if (!handle) {
+            return
+        }
+
+        act(() => {
+            handle.scrollToIndex(100)
+        })
+        const target = container.querySelector('[data-index="100"]') as HTMLElement | null
+        expect(target).not.toBeNull()
+        expect(target?.style.top).toBe("4000px")
+
+        // 可視先頭 (100) より上の行 50 を 40px→140px に拡大するとペインは +100 補正される。
+        // visibleItems メモが失効しないと行 top が古い prefix 和 (4000) のまま残り、全行が 100px ずれる。
+        act(() => {
+            handle.updateItemSize(50, 140)
+        })
+        const updated = container.querySelector('[data-index="100"]') as HTMLElement | null
+        expect(updated?.style.top).toBe("4100px")
+    })
+
+    it("最下部での updateItemSize 補正が旧 contentSize でクランプされても、二段補正でペイン位置と論理位置が収束する", () => {
+        const itemCount = 1000
+        const itemHeight = 40
+        const viewportSize = 200
+        const ref = React.createRef<VirtualScrollHandle>()
+        render(
+            React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, {
+                ref,
+                itemCount,
+                getItem: (index: number) => `Item ${index}`,
+                getItemHeight: () => itemHeight,
+                viewportSize,
+                children: (item: string) => React.createElement("div", { style: { height: itemHeight } }, item),
+            }),
+        )
+        const handle = ref.current
+        expect(handle).not.toBeNull()
+        if (!handle) {
+            return
+        }
+
+        // 最下部へ移動 (max = 1000×40 - 200 = 39800)。
+        const oldMaxScrollPosition = itemCount * itemHeight - viewportSize
+        act(() => {
+            handle.scrollTo(oldMaxScrollPosition)
+        })
+        expect(handle.getScrollPosition()).toBe(oldMaxScrollPosition)
+
+        // 可視域より上の行 10 を 40px→140px に拡大 (delta +100)。補正 scrollTo(39900) は同一同期
+        // バッチ内では ScrollPane の旧 sizeRef (max 39800) でクランプされるが、contentSize コミット後の
+        // 二段補正で新 max (39900) へ再発行され、ペイン位置と論理位置が同値に収束する。
+        act(() => {
+            handle.updateItemSize(10, 140)
+        })
+
+        const newMaxScrollPosition = oldMaxScrollPosition + 100
+        expect(handle.getScrollPosition()).toBe(newMaxScrollPosition)
+        expect(handle.getRange().scrollPosition).toBe(newMaxScrollPosition)
+    })
+
+    it("マウント後の initialScrollIndex 変更で実測済み行高さが破棄されない", () => {
+        const itemCount = 1000
+        const getItemHeight = () => 40
+        const getItem = (index: number) => `Item ${index}`
+        const childrenRenderer = (item: string) => React.createElement("div", null, item)
+        const ref = React.createRef<VirtualScrollHandle>()
+        const buildProps = (initialScrollIndex: number) => ({
+            ref,
+            itemCount,
+            getItem,
+            getItemHeight,
+            viewportSize: 200,
+            initialScrollIndex,
+            children: childrenRenderer,
+        })
+        const { rerender } = render(React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, buildProps(0)))
+        const handle = ref.current
+        expect(handle).not.toBeNull()
+        if (!handle) {
+            return
+        }
+
+        act(() => {
+            handle.updateItemSize(500, 400)
+        })
+        expect(handle.getFenwickTreeTotalHeight()).toBe(40_360)
+
+        // "initial" prop の意味論: マウント後の変更は木の全面リセット (実測破棄) を引き起こさない。
+        rerender(React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, buildProps(10)))
+        expect(handle.getFenwickTreeTotalHeight()).toBe(40_360)
+    })
+
+    it("病的な描画範囲でも描画ノード数が安全上限 (2000) で有界化され警告が出る", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+        try {
+            const { container } = render(
+                React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, {
+                    itemCount: 6000,
+                    getItem: (index: number) => `Item ${index}`,
+                    getItemHeight: () => 40,
+                    viewportSize: 200,
+                    overscanCount: 5000,
+                    children: (item: string) => React.createElement("div", null, item),
+                }),
+            )
+            const items = container.querySelectorAll("[data-virtualscroll-item]")
+            expect(items.length).toBe(2000)
+            const capWarning = warnSpy.mock.calls.some((call) => call.some((argument) => typeof argument === "string" && argument.includes("safety cap")))
+            expect(capWarning).toBe(true)
+        } finally {
+            warnSpy.mockRestore()
+        }
+    })
+
+    it("初回マウントの高さ照合マイクロタスクが破棄されず総高さが実測へ収束する", async () => {
+        // React Testing Library の act はマイクロタスクより先に passive effect を同期実行してしまうため、
+        // ブラウザ実挙動 (レンダー由来マイクロタスク → passive effect の順) を再現するには act を使わず
+        // createRoot で直接マウントする。
+        const globalWithActFlag = globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+        const previousActEnvironment = globalWithActFlag.IS_REACT_ACT_ENVIRONMENT
+        globalWithActFlag.IS_REACT_ACT_ENVIRONMENT = false
+        const host = document.createElement("div")
+        document.body.appendChild(host)
+        const root = createRoot(host)
+        try {
+            const itemCount = 1000
+            // 行 51..70 のみ 35px、それ以外は 100px。初期 sampleRange (0..50) の外に実高と推定の差を作る。
+            const getItemHeight = (index: number) => (index >= 51 && index <= 70 ? 35 : 100)
+            const ref = React.createRef<VirtualScrollHandle>()
+            root.render(
+                React.createElement(VirtualScroll as (props: unknown) => React.ReactElement, {
+                    ref,
+                    itemCount,
+                    getItem: (index: number) => `Item ${index}`,
+                    getItemHeight,
+                    viewportSize: 400,
+                    // 行 51 以降が初回描画ウィンドウに入るオフセット (行 0..50 = 5100px)。
+                    initialScrollOffset: 5100,
+                    children: (item: string) => React.createElement("div", null, item),
+                }),
+            )
+            // レンダー・マイクロタスク・passive effect・setContentSize 再レンダーをすべて完了させる。
+            await new Promise((resolve) => setTimeout(resolve, 50))
+            const handle = ref.current
+            expect(handle).not.toBeNull()
+            // 行 51..70 (20 行 × -65px) の実測が反映される: 980×100 + 20×35 = 98,700。
+            // 初回マイクロタスクが破棄されると推定値 (約 100,000) のまま残る。
+            expect(handle?.getFenwickTreeTotalHeight()).toBe(98_700)
+        } finally {
+            root.unmount()
+            host.remove()
+            globalWithActFlag.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment
+        }
+    })
+})