@aiquants/virtualscroll 1.18.5 → 1.19.0

package/src/VirtualScroll.tsx

@@ -0,0 +1,1891 @@
+import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react"
+import { Logger } from "./logger.ts"
+import { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneProps } from "./ScrollPane.tsx"
+import { useFenwickMapTree } from "./useFenwickMapTree.ts"
+import { minmax } from "./utils.ts"
+
+/**
+ * Represents the current state of the rendered range and scroll metrics.
+ *
+ * 現在のレンダリング範囲とスクロールメトリクスの状態を表します。
+ */
+export type VirtualScrollRange = {
+    /** Start index for rendering (includes overscan) / 描画開始インデックス（オーバースキャン含む） */
+    renderingStartIndex: number
+    /** End index for rendering (includes overscan) / 描画終了インデックス（オーバースキャン含む） */
+    renderingEndIndex: number
+    /** Index of the first item strictly visible in the viewport / ビューポート内に見えている最初のアイテムのインデックス */
+    visibleStartIndex: number
+    /** Index of the last item strictly visible in the viewport / ビューポート内に見えている最後のアイテムのインデックス */
+    visibleEndIndex: number
+    /** Current logical scroll position / 現在の論理スクロール位置 */
+    scrollPosition: number
+    /** Total height of the scroll content / スクロールコンテンツの総高さ */
+    totalHeight: number
+}
+
+/**
+ * Handle interface for controlling the VirtualScroll component externally.
+ *
+ * 外部から VirtualScroll コンポーネントを制御するためのハンドルインターフェース。
+ */
+export type VirtualScrollHandle = ScrollPaneHandle & {
+    /** Scrolls to a specific item index / 指定したアイテムインデックスへスクロール */
+    scrollToIndex: (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number }) => void
+    /** Gets the total height managed by the Fenwick Tree / Fenwick Tree で管理されている総高さを取得 */
+    getFenwickTreeTotalHeight: () => number
+    /** Gets the number of items in the Fenwick Tree / Fenwick Tree 内のアイテム数を取得 */
+    getFenwickSize: () => number
+    /** Focuses an item at the specified index / 指定したインデックスのアイテムにフォーカス */
+    focusItemAtIndex: (index: number, options?: { ensureVisible?: boolean }) => void
+    /** Gets the current scroll range information / 現在のスクロール範囲情報を取得 */
+    getRange: () => VirtualScrollRange
+    /**
+     * Manually updates the size of a specific item. Contract: after calling this,
+     * `getItemHeight(index)` must return the same `size`; `getItemHeight` is the source of truth,
+     * so if it keeps returning the old value, rows inside the current rendering window (including
+     * overscan) are reverted to the `getItemHeight` value by height reconciliation on the next render.
+     *
+     * 特定のアイテムのサイズを手動で更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を
+     * 返すこと。`getItemHeight` が正であるため、旧値を返し続けると描画ウィンドウ (オーバースキャン
+     * 含む) 内の行は次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。
+     */
+    updateItemSize: (index: number, size: number) => void
+}
+
+export type VirtualScrollScrollBarOptions = {
+    width?: number
+    enableThumbDrag?: boolean
+    enableTrackClick?: boolean
+    enableArrowButtons?: boolean
+    enableScrollToTopBottomButtons?: boolean
+    renderThumbOverlay?: ScrollPaneProps["renderThumbOverlay"]
+    tapScrollCircleOptions?: ScrollPaneProps["tapScrollCircleOptions"]
+}
+
+export type VirtualScrollBehaviorOptions = {
+    enablePointerDrag?: boolean
+    enableKeyboardNavigation?: boolean
+    wheelSpeedMultiplier?: number
+    inertiaOptions?: ScrollPaneProps["inertiaOptions"]
+    clipItemHeight?: boolean
+    /**
+     * When `true`, the underlying Fenwick tree fully re-samples on every `getItemHeight` change
+     * instead of applying an incremental tail resize.
+     *
+     * Set this to `true` whenever an `itemCount` change may represent a middle insertion/deletion
+     * (not just a tail append/remove): an incremental resize assumes items are added/removed at the
+     * tail and keeps each existing index's measured height, so a middle insert would leave the
+     * `getItemHeight` index↔height mapping applied to the wrong rows. Alternatively, remount
+     * VirtualScroll with a new `key` when the list structure changes.
+     *
+     * `true` のとき、内部 Fenwick 木は `getItemHeight` 変更のたびに増分的な末尾リサイズではなく全面
+     * 再サンプリングを行う。`itemCount` の変更が末尾追記/削除ではなく中間挿入/削除を含みうる場合は
+     * `true` にすること。増分リサイズは要素が末尾で増減する前提で各既存インデックスの実測高さを保持する
+     * ため、中間挿入があると `getItemHeight` の index↔高さ 対応が誤った行に適用されてしまう。代替として、
+     * リスト構造が変わるときに新しい `key` で VirtualScroll を再マウントしてもよい。
+     */
+    resetOnGetItemHeightChange?: boolean
+}
+
+/**
+ * Props for the VirtualScroll component.
+ *
+ * VirtualScroll コンポーネントの Props。
+ */
+export type VirtualScrollProps<T> = {
+    itemCount: number
+    getItem: (index: number) => T
+    getItemKey?: (index: number) => React.Key
+    /**
+     * Returns the height of the item at `index`. The index↔height mapping must be stable for a
+     * given list ordering: when `itemCount` grows/shrinks, VirtualScroll assumes items are
+     * appended to / removed from the tail and preserves the measured height of each existing index.
+     * If a list mutation inserts or removes items in the middle (shifting later indices), enable
+     * `behaviorOptions.resetOnGetItemHeightChange` or remount with a new `key`; otherwise cached
+     * heights stay attached to indices that now point at different items.
+     *
+     * `index` のアイテム高さを返す。index↔高さ の対応は同じ並び順の間は安定である必要がある。`itemCount`
+     * が増減するとき VirtualScroll は要素が末尾で追加/削除されると仮定し、既存インデックスの実測高さを
+     * 保持する。中間挿入/削除 (以降のインデックスがずれる) を伴うリスト変更では
+     * `behaviorOptions.resetOnGetItemHeightChange` を有効化するか新しい `key` で再マウントすること。
+     * さもないとキャッシュ済み高さが別のアイテムを指すインデックスに残る。
+     */
+    getItemHeight: (index: number) => number
+    viewportSize: number
+    overscanCount?: number
+    className?: string
+    /** Test id emitted as data-testid on the scroll root (DOM hooks must use data-* attributes, never class selectors). / スクロールルートに data-testid として出力されるテスト ID (DOM フックはクラスセレクタでなく data-* 属性を使う)。 */
+    testId?: string
+    onScroll?: (scrollPosition: number, totalHeight: number) => void
+    onRangeChange?: (range: VirtualScrollRange) => void
+    background?: ReactNode
+    children: (item: T, index: number) => ReactNode
+    initialScrollIndex?: number
+    initialScrollOffset?: number
+    callbackThrottleMs?: number
+    contentInsets?: ScrollPaneProps["contentInsets"]
+    onItemFocus?: (index: number) => void
+    scrollBarOptions?: VirtualScrollScrollBarOptions
+    behaviorOptions?: VirtualScrollBehaviorOptions
+    /** Delegates horizontal wheel/trackpad delta to an upstream owner (e.g. a frozen-column grid). / 横ホイール量を上流へ委譲する。 */
+    onWheelHorizontal?: (deltaX: number) => void
+}
+
+/**
+ * Normalizes index values to valid bounds.
+ *
+ * インデックス値を安全な範囲に丸める。
+ */
+const sanitizeIndex = (value: number, size: number) => (size <= 0 ? 0 : minmax(value, 0, size - 1))
+
+const normalizeInsets = (insets?: ScrollPaneContentInsets): Required<ScrollPaneContentInsets> => ({
+    top: Math.max(0, insets?.top ?? 0),
+    bottom: Math.max(0, insets?.bottom ?? 0),
+})
+
+const toLogicalPositionWithInset = (pane: number, top: number) => (pane <= top ? 0 : pane - top)
+
+const toPanePositionWithInset = (logical: number, top: number) => (logical <= 0 ? top : logical + top)
+
+/**
+ * Maximum run length of consecutive zero-height rows scanned linearly before attempting an
+ * O(log n) jump to the next non-zero row via the Fenwick tree.
+ *
+ * 高さ 0 行の連続をこの件数まで線形走査し、超えたら Fenwick 木で次の非 0 行へ O(log n) ジャンプする閾値。
+ */
+const ZERO_HEIGHT_RUN_LIMIT = 1000
+
+/**
+ * Safety cap for the number of item nodes materialized in a single render pass.
+ * Guards against pathological rendering ranges (e.g. a huge contiguous run of zero-height rows).
+ *
+ * 1 回のレンダーで具現化するアイテムノード数の安全上限。
+ * 病的な描画範囲 (巨大な高さ 0 行の連続など) からの防御。
+ */
+const MAX_RENDERED_ITEMS = 2000
+
+/**
+ * Distance (px) between the rendering window start and the current render anchor beyond which
+ * the anchor is re-based. Keeps row `top` values and the wrapper `translateY` small enough to
+ * stay within browser layout (LayoutUnit ~2^25 px) and compositor f32 precision limits.
+ *
+ * 描画ウィンドウ先頭と現在の描画アンカーの距離がこの値 (px) を超えたらアンカーを再基準化する。
+ * 行 top とラッパー translateY をブラウザのレイアウト座標上限 (LayoutUnit 約 2^25 px) と
+ * compositor の f32 精度内に収めるための量子化距離。
+ */
+const ANCHOR_REBASE_DISTANCE = 1_048_576 // 2^20 px
+
+/**
+ * Converts a numeric size into a non-negative bigint for large collection handling.
+ *
+ * 大規模コレクション向けに数値サイズを非負の bigint へ変換。
+ */
+const toSafeBigInt = (value: number): bigint => {
+    if (!Number.isFinite(value)) return 0n
+    const truncated = Math.trunc(value)
+    return truncated <= 0 ? 0n : BigInt(truncated)
+}
+
+/**
+ * Computes rendering ranges for collections exceeding Number.MAX_SAFE_INTEGER.
+ * Uses BigInt math to handle positions that cannot be represented by standard JavaScript numbers.
+ *
+ * Number.MAX_SAFE_INTEGER を超える巨大なコレクションに対して描画範囲を算出します。
+ * 標準的な JavaScript 数値では表現できない位置を扱うために、内部計算には BigInt を使用します。
+ *
+ * @param effectiveScrollPosition Clamped scroll position / 丸められた有効なスクロール位置
+ * @param viewportSize Height of the viewport / ビューポートの高さ
+ * @param overscanCount Number of items to render outside the viewport / ビューポート外に描画するアイテム数
+ * @param itemSize Total number of items / 総アイテム数
+ * @param getItemHeight Function to get height of an item / アイテムの高さを取得する関数
+ * @param fenwickTree Fenwick Tree instance / Fenwick Tree インスタンス
+ * @param totalHeight Total content height / コンテンツ総高さ
+ * @param hasFiniteTotal Whether the total height is finite / 総高さが有限かどうか
+ */
+const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSize: number, overscanCount: number, itemSize: number, getItemHeight: (index: number) => number, fenwickTree: ReturnType<typeof useFenwickMapTree>, totalHeight: number, hasFiniteTotal: boolean) => {
+    const sizeBig = toSafeBigInt(itemSize)
+    if (sizeBig === 0n) {
+        return { renderingStartIndex: 0, renderingEndIndex: 0, visibleStartIndex: 0, visibleEndIndex: 0 }
+    }
+
+    const clampBig = (value: bigint): bigint => {
+        if (value < 0n) {
+            return 0n
+        }
+        if (value >= sizeBig) {
+            return sizeBig - 1n
+        }
+        return value
+    }
+
+    const materializeOption = { materializeOption: { materialize: false } }
+    const { index: rawStartIndex, cumulative } = fenwickTree.findIndexAtOrAfter(effectiveScrollPosition, materializeOption)
+
+    let startBig: bigint
+    if (rawStartIndex === -1) {
+        startBig = sizeBig - 1n
+    } else {
+        if (cumulative === effectiveScrollPosition) {
+            startBig = toSafeBigInt(rawStartIndex + 1)
+        } else {
+            startBig = toSafeBigInt(rawStartIndex)
+        }
+
+        if (startBig >= sizeBig) {
+            startBig = sizeBig - 1n
+        }
+    }
+
+    if (effectiveScrollPosition <= 0) {
+        startBig = 0n
+    }
+
+    if (hasFiniteTotal && effectiveScrollPosition >= totalHeight) {
+        startBig = sizeBig - 1n
+    }
+
+    // 高さ 0 (折りたたみ行) はスキップして走査を継続する (散発的な 0 行は正当な入力)。
+    // 走査を打ち切るのは負値・非有限の高さ (不正入力) のみ。0 行が大量に連続する場合は
+    // 連続数が閾値を超えた時点で Fenwick 木により次の非 0 行へ O(log n) でジャンプし、有界性を保つ。
+    const jumpPastZeroRun = (lastScanned: bigint): bigint | null => {
+        const lastNumber = Number(lastScanned)
+        if (!Number.isSafeInteger(lastNumber)) {
+            // number へ安全に変換できない領域では木のクエリが不正確になるため打ち切る
+            return null
+        }
+        const { cumulative: runBottom } = fenwickTree.prefixSum(lastNumber, { materializeOption: { materialize: false } })
+        if (!Number.isFinite(runBottom)) {
+            return null
+        }
+        const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom + 0.5, { materializeOption: { materialize: false } })
+        if (jumpIndex === -1) {
+            return null
+        }
+        const jumpBig = toSafeBigInt(jumpIndex)
+        return jumpBig > lastScanned ? jumpBig : null
+    }
+
+    const accumulateForward = (initial: bigint) => {
+        let height = 0
+        let cursor = initial
+        let last = initial
+        let iterations = 0n
+        let zeroRun = 0
+        while (cursor < sizeBig && height < viewportSize) {
+            const cursorNumber = Number(cursor)
+            const currentHeight = getItemHeight(cursorNumber)
+            height += currentHeight
+            last = cursor
+            cursor += 1n
+            iterations += 1n
+            if (!Number.isFinite(currentHeight) || currentHeight < 0) {
+                break
+            }
+            if (currentHeight === 0) {
+                zeroRun += 1
+                if (zeroRun > ZERO_HEIGHT_RUN_LIMIT) {
+                    const jumped = jumpPastZeroRun(last)
+                    if (jumped !== null && jumped > cursor) {
+                        // 0 行の連続を飛び越えて次の非 0 行から走査を続行する
+                        cursor = jumped
+                        zeroRun = 0
+                    } else if (jumped !== null && jumped === cursor && getItemHeight(Number(cursor)) > 0) {
+                        // 連続 0 行がちょうどここで終わる: 次の行は非 0 なので通常走査を続行する
+                        zeroRun = 0
+                    } else {
+                        // ジャンプ先が無い/前進しない (木と getItemHeight の不一致など) は打ち切り、有界性を優先する
+                        break
+                    }
+                }
+            } else {
+                zeroRun = 0
+            }
+        }
+        if (iterations === 0n) {
+            last = initial
+        }
+        return { height, end: last }
+    }
+
+    let { height: forwardHeight, end: forwardEnd } = accumulateForward(startBig)
+
+    if (forwardHeight < viewportSize && startBig > 0n) {
+        let backwardStart = startBig
+        let backwardHeight = forwardHeight
+        let backwardZeroRun = 0
+        while (backwardStart > 0n && backwardHeight < viewportSize) {
+            backwardStart -= 1n
+            const indexNumber = Number(backwardStart)
+            const itemHeight = getItemHeight(indexNumber)
+            backwardHeight += itemHeight
+            if (!Number.isFinite(itemHeight) || itemHeight < 0) {
+                break
+            }
+            if (itemHeight === 0) {
+                backwardZeroRun += 1
+                if (backwardZeroRun > ZERO_HEIGHT_RUN_LIMIT) {
+                    // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)
+                    const indexNum = Number(backwardStart)
+                    if (!Number.isSafeInteger(indexNum)) {
+                        break
+                    }
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(indexNum, { materializeOption: { materialize: false } })
+                    if (!Number.isFinite(runBottom)) {
+                        break
+                    }
+                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, { materializeOption: { materialize: false } })
+                    const jumpBig = jumpIndex === -1 ? -1n : toSafeBigInt(jumpIndex)
+                    if (jumpBig >= 0n && jumpBig < backwardStart) {
+                        // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
+                        backwardStart = jumpBig + 1n
+                        backwardZeroRun = 0
+                    } else if (jumpBig === backwardStart && backwardStart >= 1n && getItemHeight(Number(backwardStart - 1n)) > 0) {
+                        // 連続 0 行がちょうどここで終わる: 次 (下方向) の行は非 0 なので通常走査を続行する
+                        backwardZeroRun = 0
+                    } else {
+                        // ジャンプ先が無い/前進しない (木と getItemHeight の不一致など) は打ち切り、有界性を優先する
+                        break
+                    }
+                }
+            } else {
+                backwardZeroRun = 0
+            }
+        }
+        startBig = clampBig(backwardStart)
+        const forward = accumulateForward(startBig)
+        forwardHeight = forward.height
+        forwardEnd = forward.end
+    }
+
+    const visibleStartBig = clampBig(startBig)
+    const visibleEndBig = clampBig(forwardEnd)
+    const renderingStartBig = clampBig(visibleStartBig - BigInt(Math.max(0, overscanCount)))
+    const renderingEndBig = clampBig(visibleEndBig + BigInt(Math.max(0, overscanCount)))
+
+    return {
+        renderingStartIndex: sanitizeIndex(Number(renderingStartBig), itemSize),
+        renderingEndIndex: sanitizeIndex(Number(renderingEndBig), itemSize),
+        visibleStartIndex: sanitizeIndex(Number(visibleStartBig), itemSize),
+        visibleEndIndex: sanitizeIndex(Number(visibleEndBig), itemSize),
+    }
+}
+
+/**
+ * Retrieves a high-resolution timestamp when available.
+ *
+ * 高精度タイムスタンプを可能なら取得。
+ */
+/**
+ * Calculates rendering boundaries from current scroll metrics.
+ *
+ * 現在のスクロール情報から描画範囲を算出。
+ */
+export const computeRenderingRanges = (scrollPosition: number, viewportSize: number, overscanCount: number, itemSize: number, getItemHeight: (index: number) => number, fenwickTree: ReturnType<typeof useFenwickMapTree>, totalHeight: number) => {
+    if (itemSize === 0) {
+        return { renderingStartIndex: 0, renderingEndIndex: 0, visibleStartIndex: 0, visibleEndIndex: 0 }
+    }
+    const hasFiniteTotal = Number.isFinite(totalHeight)
+    const effectiveScrollPosition = hasFiniteTotal ? Math.min(Math.max(0, scrollPosition), totalHeight) : Math.max(0, scrollPosition)
+    if (itemSize >= Number.MAX_SAFE_INTEGER) {
+        return computeRenderingRangesHuge(effectiveScrollPosition, viewportSize, overscanCount, itemSize, getItemHeight, fenwickTree, totalHeight, hasFiniteTotal)
+    }
+    const { index: rawStartIndex, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(effectiveScrollPosition, { materializeOption: { materialize: false } })
+    const startIndex =
+        rawStartIndex === -1
+            ? (() => {
+                  // Fenwick がインデックスを返さない場合は末尾に合わせて開始位置を再計算
+                  if (viewportSize <= 0) {
+                      return itemSize - 1
+                  }
+                  return (cumulative ?? 0) < effectiveScrollPosition + (currentValue ?? 0) ? itemSize - 1 : 0
+              })()
+            : rawStartIndex
+    let visibleStartIndex = sanitizeIndex(startIndex, itemSize)
+
+    let visibleHeight = 0
+    if (rawStartIndex !== -1 && cumulative === effectiveScrollPosition) {
+        visibleStartIndex = sanitizeIndex(rawStartIndex + 1, itemSize)
+        visibleHeight = 0
+    } else if (visibleStartIndex === rawStartIndex && cumulative !== undefined && currentValue !== undefined) {
+        const itemTop = cumulative - currentValue
+        visibleHeight = itemTop - effectiveScrollPosition
+    } else {
+        const { cumulative: startCumulative, currentValue: startHeight } = fenwickTree.prefixSum(visibleStartIndex, { materializeOption: { materialize: false } })
+        const itemTop = (startCumulative ?? 0) - (startHeight ?? 0)
+        visibleHeight = itemTop - effectiveScrollPosition
+    }
+
+    const initialOffset = visibleHeight
+
+    // 高さ 0 (折りたたみ行・区切り行) はスキップして走査を継続する (散発的な 0 行は正当な入力)。
+    // 走査を打ち切るのは負値・非有限の高さ (不正入力) のみ。0 行が大量に連続する場合でも
+    // 走査が全件に膨れ上がらないよう、連続数が閾値を超えたら Fenwick 木の findIndexAtOrAfter で
+    // 次の非 0 行へ O(log n) でジャンプして続行する。ジャンプが前進しない場合 (木と
+    // getItemHeight の不一致など) は打ち切り、有界性を優先する。
+    const scanForward = (startIndex: number, initialHeight: number) => {
+        let forwardCursor = startIndex
+        let height = initialHeight
+        let zeroRun = 0
+        while (forwardCursor < itemSize && height < viewportSize) {
+            const currentHeight = getItemHeight(forwardCursor)
+            height += currentHeight
+            forwardCursor++
+            if (!Number.isFinite(currentHeight) || currentHeight < 0) {
+                break
+            }
+            if (currentHeight === 0) {
+                zeroRun++
+                if (zeroRun > ZERO_HEIGHT_RUN_LIMIT) {
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(forwardCursor - 1, { materializeOption: { materialize: false } })
+                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom + 0.5, { materializeOption: { materialize: false } }) : { index: -1 }
+                    if (jumpIndex > forwardCursor) {
+                        // 0 行の連続を飛び越えて次の非 0 行から走査を続行する
+                        forwardCursor = jumpIndex
+                        zeroRun = 0
+                    } else if (jumpIndex === forwardCursor && getItemHeight(forwardCursor) > 0) {
+                        // 連続 0 行がちょうどここで終わる: 次の行は非 0 なので通常走査を続行する
+                        zeroRun = 0
+                    } else {
+                        // ジャンプ先が無い/前進しない (木と getItemHeight の不一致など) は打ち切り、有界性を優先する
+                        break
+                    }
+                }
+            } else {
+                zeroRun = 0
+            }
+        }
+        return { cursor: forwardCursor, height }
+    }
+
+    const forward = scanForward(visibleStartIndex, visibleHeight)
+    let cursor = forward.cursor
+    visibleHeight = forward.height
+
+    if (visibleHeight < viewportSize && visibleStartIndex > 0) {
+        let backwardHeight = visibleHeight + Math.abs(Math.min(0, initialOffset))
+        let backwardCursor = visibleStartIndex - 1
+        let backwardZeroRun = 0
+        while (backwardCursor >= 0 && backwardHeight < viewportSize) {
+            const itemHeight = getItemHeight(backwardCursor)
+            backwardHeight += itemHeight
+            if (!Number.isFinite(itemHeight) || itemHeight < 0) {
+                backwardCursor--
+                break
+            }
+            if (itemHeight === 0) {
+                backwardZeroRun++
+                if (backwardZeroRun > ZERO_HEIGHT_RUN_LIMIT) {
+                    // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(backwardCursor, { materializeOption: { materialize: false } })
+                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom - 0.5, { materializeOption: { materialize: false } }) : { index: -1 }
+                    if (jumpIndex !== -1 && jumpIndex < backwardCursor) {
+                        // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
+                        backwardCursor = jumpIndex
+                        backwardZeroRun = 0
+                        continue
+                    }
+                    if (jumpIndex === backwardCursor && backwardCursor >= 1 && getItemHeight(backwardCursor - 1) > 0) {
+                        // 連続 0 行がちょうどここで終わる: 次 (下方向) の行は非 0 なので通常走査を続行する
+                        backwardZeroRun = 0
+                    } else {
+                        // ジャンプ先が無い/前進しない (木と getItemHeight の不一致など) は打ち切り、有界性を優先する
+                        backwardCursor--
+                        break
+                    }
+                }
+            } else {
+                backwardZeroRun = 0
+            }
+            backwardCursor--
+        }
+        visibleStartIndex = sanitizeIndex(backwardCursor + 1, itemSize)
+        const rescan = scanForward(visibleStartIndex, 0)
+        cursor = rescan.cursor
+        visibleHeight = rescan.height
+    }
+    const renderingStartIndex = sanitizeIndex(visibleStartIndex - overscanCount, itemSize)
+    const visibleEndIndex = sanitizeIndex(Math.max(cursor - 1, visibleStartIndex), itemSize)
+    const renderingEndIndex = sanitizeIndex(visibleEndIndex + overscanCount, itemSize)
+
+    return { renderingStartIndex, renderingEndIndex, visibleStartIndex, visibleEndIndex }
+}
+
+/**
+ * Renders a virtualized scroll pane referencing a Fenwick tree for offsets.
+ *
+ * Fenwick 木でオフセットを管理する仮想スクロールコンテナ。
+ */
+
+type OnScrollCallback = (scrollPosition: number, totalHeight: number) => void
+type OnRangeChangeCallback = (range: VirtualScrollRange) => void
+
+/**
+ * A custom hook that creates a throttled invoker function using requestAnimationFrame.
+ * This ensures that the callback is executed at most once per animation frame, plus an optional time throttle.
+ * It also handles cleanup of pending animation frames on unmount.
+ *
+ * requestAnimationFrame を使用してスロットリングされた実行関数を作成するカスタムフック。
+ * コールバックがアニメーションフレームごとに最大1回（＋オプションの時間スロットル）実行されることを保証します。
+ * また、アンマウント時に保留中のアニメーションフレームをクリーンアップします。
+ *
+ * @param callbackRef Mutable ref to the callback function / コールバック関数への Ref
+ * @param throttleMs Minimum time between invocations in ms / 実行間の最小時間（ミリ秒）
+ * @param invoke Wrapper function to execute the callback (e.g. for argument unwrapping) / コールバックを実行するラッパー関数
+ */
+const useThrottledInvoker = <Callback, Payload>(callbackRef: React.MutableRefObject<Callback | undefined>, throttleMs: number | undefined, invoke: (callback: Callback, payload: Payload) => void) => {
+    const throttle = Math.max(0, throttleMs ?? 0)
+    // last: 最終実行時刻, id: RAF ID, arg: 待機中の引数
+    const state = useRef({ last: 0, id: null as number | null, arg: null as Payload | null }).current
+
+    // クリーンアップ: アンマウント時にRAFをキャンセル
+    useEffect(
+        () => () => {
+            if (state.id !== null) {
+                cancelAnimationFrame(state.id)
+                state.id = null
+            }
+        },
+        [state],
+    )
+
+    return useCallback(
+        (payload: Payload) => {
+            state.arg = payload
+            if (state.id !== null) return
+
+            const loop = (now: number) => {
+                state.id = null
+                if (state.arg === null) return
+
+                const elapsed = now - state.last
+                if (throttle === 0 || state.last === 0 || elapsed >= throttle) {
+                    if (callbackRef.current) {
+                        try {
+                            invoke(callbackRef.current, state.arg)
+                        } catch (e) {
+                            console.error("[useThrottledInvoker] Error invoking callback", e)
+                        }
+                    }
+                    state.arg = null
+                    state.last = now
+                }
+
+                if (state.arg !== null) {
+                    state.id = requestAnimationFrame(loop)
+                }
+            }
+            state.id = requestAnimationFrame(loop)
+        },
+        [throttle, invoke, callbackRef, state],
+    )
+}
+
+type VirtualScrollItemProps<T> = {
+    index: number
+    top: number
+    height: number
+    item: T
+    children: (item: T, index: number) => ReactNode
+    clipItemHeight: boolean
+    enableKeyboardNavigation: boolean
+    onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>, index: number) => void
+    onFocus: (index: number) => void
+    registerItemRef: (index: number, node: HTMLDivElement | null) => void
+}
+
+/**
+ * Renders a single virtualized item.
+ * Wraps the user-provided item component with positioning styles and event handlers.
+ * Memoized to prevent unnecessary re-renders when props haven't changed.
+ *
+ * 単一の仮想アイテムをレンダリングするコンポーネント。
+ * ユーザーが提供したアイテムコンポーネントを、配置スタイルとイベントハンドラでラップします。
+ * Props が変更されていない場合の不要な再レンダリングを防ぐためにメモ化されています。
+ */
+const VirtualScrollItem = React.memo(<T,>({ index, top, height, item, children, clipItemHeight, enableKeyboardNavigation, onKeyDown, onFocus, registerItemRef }: VirtualScrollItemProps<T>) => {
+    const handleRef = useCallback((node: HTMLDivElement | null) => registerItemRef(index, node), [index, registerItemRef])
+    const handleKeyDown = useCallback((e: React.KeyboardEvent<HTMLDivElement>) => onKeyDown(e, index), [index, onKeyDown])
+    const handleFocus = useCallback(() => onFocus(index), [index, onFocus])
+    const handlePointerDown = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+        e.currentTarget.focus({ preventScroll: true })
+    }, [])
+
+    return (
+        <div
+            ref={handleRef}
+            data-index={index}
+            data-virtualscroll-item="true"
+            className="aqvs-item-container"
+            style={{
+                top,
+                height,
+                overflow: clipItemHeight ? "hidden" : undefined,
+            }}
+            tabIndex={enableKeyboardNavigation ? -1 : undefined}
+            onPointerDown={enableKeyboardNavigation ? handlePointerDown : undefined}
+            onKeyDownCapture={enableKeyboardNavigation ? handleKeyDown : undefined}
+            onFocusCapture={enableKeyboardNavigation ? handleFocus : undefined}>
+            {children(item, index)}
+        </div>
+    )
+}) as <T>(props: VirtualScrollItemProps<T>) => React.ReactElement
+
+/**
+ * Renders a virtualized scroll pane referencing a Fenwick tree for offsets.
+ *
+ * Fenwick 木でオフセットを管理する仮想スクロールコンテナ。
+ */
+const VirtualScrollInner = <T,>(
+    {
+        itemCount,
+        getItem,
+        getItemKey,
+        getItemHeight,
+        viewportSize,
+        overscanCount = 15,
+        className,
+        testId,
+        onScroll,
+        onRangeChange,
+        children,
+        background,
+        initialScrollIndex,
+        initialScrollOffset,
+        callbackThrottleMs = 5,
+        contentInsets,
+        onItemFocus,
+        scrollBarOptions,
+        behaviorOptions,
+        onWheelHorizontal,
+    }: VirtualScrollProps<T>,
+    ref: React.Ref<VirtualScrollHandle>,
+) => {
+    const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
+
+    const { enablePointerDrag, enableKeyboardNavigation = true, wheelSpeedMultiplier, inertiaOptions, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
+
+    const scrollPaneRef = useRef<VirtualScrollHandle>(null)
+    const currentRangeRef = useRef<VirtualScrollRange>({
+        renderingStartIndex: 0,
+        renderingEndIndex: 0,
+        visibleStartIndex: 0,
+        visibleEndIndex: 0,
+        scrollPosition: 0,
+        totalHeight: 0,
+    })
+    const pendingVisibleStartIndexRef = useRef<{
+        index: number
+        align?: "top" | "bottom" | "center"
+        offset?: number
+    } | null>(null)
+    // 「アンマウント済みか」を追跡する (初期 false)。「マウント済みか」の正ガードだと、初回レンダー中に
+    // 予約された高さ照合マイクロタスクが passive effect (マウントフラグ設定) より先に実行されて破棄される。
+    const isUnmountedRef = useRef(false)
+
+    useEffect(() => {
+        // 目的: アイテムの高さ取得ロジックがリセットされた場合に、古いインデックスへのアンカーを解除する。
+        // 依存関係: resetOnGetItemHeightChange, getItemHeight
+        if (resetOnGetItemHeightChange) {
+            // When configured to reset on logic change, we drop the scroll anchor
+            // to avoid sticking to an index that may no longer be relevant contextually.
+            pendingVisibleStartIndexRef.current = null
+        }
+    }, [resetOnGetItemHeightChange, getItemHeight])
+
+    const resolvedInsets = useMemo(() => normalizeInsets(contentInsets), [contentInsets])
+
+    // sampleRange は「初期に具現化するウィンドウ」= 利用者が最初に見る領域 (initialScrollIndex 近傍) を指す。
+    // baseValue (未具現化アイテムの総高さ推定) の代表値は、木側がリスト全体にわたる分散 (ストライド)
+    // サンプリングで別途決めるため、この sampleRange は baseValue 推定には影響しない。先頭が非代表的な
+    // 高さ (ヒーロー行など) でも総高さ推定は多数派へ寄る。
+    // sampleRange はマウント時の initialScrollIndex から一度だけ確定する ("initial" prop の意味論)。
+    // マウント後の initialScrollIndex 変更を options に反映させると、useFenwickMapTree 側の値比較
+    // (sampleRangeChanged) が破壊的な tree.reset を発火し、実測済みの全行高さが破棄されてしまう。
+    const [initialSampleRange] = useState(() => {
+        const SAMPLE_HALF_WINDOW = 50
+        const anchor = typeof initialScrollIndex === "number" && Number.isFinite(initialScrollIndex) ? Math.max(0, Math.trunc(initialScrollIndex)) : 0
+        return { from: Math.max(0, anchor - SAMPLE_HALF_WINDOW), to: anchor + SAMPLE_HALF_WINDOW }
+    })
+
+    const fenwickTreeOptions = useMemo(
+        // 目的: Fenwick Tree のオプション設定
+        // 依存関係: resetOnGetItemHeightChange, initialSampleRange (マウント時固定)
+        // itemCount には依存させない (依存させると追記のたびに options 参照が変わり、計測済み高さが全消去される)。
+        // この useMemo により sampleRange を毎レンダー新規生成しない = 参照同一性由来の破壊的 reset を防ぐ。
+        () => ({
+            sampleRange: initialSampleRange,
+            resetOnValueFnChange: resetOnGetItemHeightChange,
+            materialize: true,
+        }),
+        [resetOnGetItemHeightChange, initialSampleRange],
+    )
+    const fenwickTree = useFenwickMapTree(itemCount, getItemHeight, fenwickTreeOptions)
+
+    const [initialValues] = useState(() => {
+        let position = resolvedInsets.top
+        let total = 0
+        if (typeof initialScrollIndex === "number") {
+            const safeIndex = minmax(initialScrollIndex, 0, itemCount - 1)
+            const safeIndexFrom = minmax(safeIndex - overscanCount * 2, 0, itemCount - 1)
+            const safeIndexTo = minmax(safeIndex + overscanCount * 2, 0, itemCount - 1)
+            const options = initialScrollIndex > 0 ? { materializeOption: { materialize: true, ranges: [{ from: safeIndexFrom, to: safeIndexTo }] } } : undefined
+            const { cumulative, total: materializedTotal, currentValue } = fenwickTree.prefixSum(initialScrollIndex, options)
+            const logicalOffset = Math.max(cumulative - currentValue, 0)
+            position = toPanePositionWithInset(logicalOffset, resolvedInsets.top)
+            total = materializedTotal ?? fenwickTree.getTotal()
+        } else if (typeof initialScrollOffset === "number") {
+            position = toPanePositionWithInset(Math.max(initialScrollOffset, 0), resolvedInsets.top)
+            total = fenwickTree.getTotal()
+        } else {
+            total = fenwickTree.getTotal()
+        }
+        return { position, total }
+    })
+
+    const [scrollPosition, setScrollPosition] = useState(initialValues.position)
+    const [contentSize, setContentSize] = useState<number>(initialValues.total)
+
+    const latestScrollPositionRef = useRef(initialValues.position)
+    const previousTopInsetRef = useRef(resolvedInsets.top)
+    const onScrollRef = useRef<OnScrollCallback | undefined>(onScroll ?? undefined)
+    const onRangeChangeRef = useRef<OnRangeChangeCallback | undefined>(onRangeChange ?? undefined)
+    const itemRefs = useRef<Map<number, HTMLDivElement>>(new Map())
+    const pendingFocusIndexRef = useRef<number | null>(null)
+    const lastFocusedIndexRef = useRef<number | null>(null)
+
+    const [scrollDirection, setScrollDirection] = useState<"up" | "down" | null>(null)
+    const [showScrollButtons, setShowScrollButtons] = useState(false)
+    const scrollButtonTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+    const isProgrammaticScrollRef = useRef(false)
+    const isCompensatingRef = useRef(0)
+    // レイアウトシフト補正の scrollTo が ScrollPane の旧 contentSize でクランプされた場合に true。
+    // 新 contentSize がコミットされた後の同期 effect で補正を再発行する (二段補正の二段目) ためのフラグ。
+    const pendingCompensationRef = useRef(false)
+    const isResizingRef = useRef(false)
+    const prevItemCountRef = useRef(itemCount)
+
+    if (prevItemCountRef.current !== itemCount) {
+        prevItemCountRef.current = itemCount
+        isResizingRef.current = true
+    }
+
+    useEffect(() => {
+        // 目的: 外部から渡されたコールバックの参照を最新状態に保つ。
+        // 依存関係: onRangeChange, onScroll
+        onScrollRef.current = onScroll ?? undefined
+        onRangeChangeRef.current = onRangeChange ?? undefined
+    }, [onRangeChange, onScroll])
+
+    const tryFocusElement = useCallback(
+        (element: HTMLElement | null) => {
+            if (!(enableKeyboardNavigation && element)) {
+                return
+            }
+            if (typeof element.focus === "function") {
+                try {
+                    element.focus({ preventScroll: true } as FocusOptions)
+                } catch (_error) {
+                    element.focus()
+                }
+            }
+        },
+        [enableKeyboardNavigation],
+    )
+
+    // スロットル制御された onScroll 通知関数
+    const invokeScroll = useCallback((callback: OnScrollCallback, { position, totalHeight }: { position: number; totalHeight: number }) => {
+        callback(position, totalHeight)
+    }, [])
+    const scheduleScrollEffect = useThrottledInvoker<OnScrollCallback, { position: number; totalHeight: number }>(onScrollRef, callbackThrottleMs, invokeScroll)
+
+    // スロットル制御された onRangeChange 通知関数
+    const invokeRangeChange = useCallback((callback: OnRangeChangeCallback, range: VirtualScrollRange) => {
+        callback(range)
+    }, [])
+    const scheduleRangeEffect = useThrottledInvoker<OnRangeChangeCallback, VirtualScrollRange>(onRangeChangeRef, callbackThrottleMs, invokeRangeChange)
+
+    // 自己再帰する RAF ループが常に最新の依存値を参照できるよう、揮発値を ref で保持する。
+    // これにより、走行中のループが古いクロージャ (旧 inset / 旧 scheduleScrollEffect) を掴み続けるのを防ぐ。
+    const resolvedInsetsTopRef = useRef(resolvedInsets.top)
+    resolvedInsetsTopRef.current = resolvedInsets.top
+    const scheduleScrollEffectRef = useRef(scheduleScrollEffect)
+    scheduleScrollEffectRef.current = scheduleScrollEffect
+
+    useEffect(() => {
+        // 目的: アンマウント状態を追跡し、アンマウント後のステート更新を防止する。
+        // 依存関係: なし (マウント/アンマウント時のみ)
+        // StrictMode の二重マウント (cleanup 後に再 effect) でも正しく復帰するよう、effect 本体で false へ戻す。
+        isUnmountedRef.current = false
+        return () => {
+            isUnmountedRef.current = true
+            // スクロールボタン非表示用タイマーがアンマウント後に発火するのを防ぐ。
+            if (scrollButtonTimerRef.current) {
+                clearTimeout(scrollButtonTimerRef.current)
+                scrollButtonTimerRef.current = null
+            }
+        }
+    }, [])
+
+    useEffect(() => {
+        // 目的: キーボードナビゲーションが無効化された場合、フォーカス管理用の参照をクリアする。
+        // 依存関係: enableKeyboardNavigation
+        if (enableKeyboardNavigation) {
+            return
+        }
+        itemRefs.current.clear()
+        pendingFocusIndexRef.current = null
+        lastFocusedIndexRef.current = null
+    }, [enableKeyboardNavigation])
+
+    const registerItemRef = useCallback(
+        (index: number, node: HTMLDivElement | null) => {
+            if (!node) {
+                itemRefs.current.delete(index)
+                return
+            }
+            if (!enableKeyboardNavigation) {
+                return
+            }
+            itemRefs.current.set(index, node)
+            if (pendingFocusIndexRef.current === index) {
+                pendingFocusIndexRef.current = null
+                lastFocusedIndexRef.current = index
+                tryFocusElement(node)
+            }
+        },
+        [enableKeyboardNavigation, tryFocusElement],
+    )
+
+    /**
+     * Updates scroll position immediately for rendering.
+     *
+     * 即時にスクロール位置を更新してレンダリングへ反映。
+     */
+    const POSITION_EPSILON = 0.01
+
+    const renderLoopRef = useRef<{
+        rafId: number | null
+        loopActive: boolean
+        idleFrames: number
+        lastRenderedPosition: number
+    }>({
+        rafId: null,
+        loopActive: false,
+        idleFrames: 0,
+        lastRenderedPosition: initialValues.position,
+    })
+
+    const stopRenderLoop = useCallback(() => {
+        // 目的: アニメーションループを停止し、保留中の RAF をキャンセルする。
+        const loop = renderLoopRef.current
+        if (loop.rafId !== null && typeof cancelAnimationFrame === "function") {
+            cancelAnimationFrame(loop.rafId)
+        }
+        loop.rafId = null
+        loop.loopActive = false
+        loop.idleFrames = 0
+    }, [])
+
+    useEffect(
+        () => () => {
+            // クリーンアップ: アンマウント時にレンダリングループを停止
+            stopRenderLoop()
+        },
+        [stopRenderLoop],
+    )
+
+    // 自身の最新クロージャを保持し、RAF 再アーム時に旧クロージャを掴まないようにする。
+    const runRenderLoopRef = useRef<(frameTime?: number) => void>(() => {})
+
+    const runRenderLoop: (frameTime?: number) => void = useCallback(() => {
+        const loop = renderLoopRef.current
+        loop.rafId = null
+
+        const currentPosition = latestScrollPositionRef.current
+        // 揮発値 (inset / 通知関数) は ref から読み、走行中でも常に最新を使う。
+        const logicalPosition = toLogicalPositionWithInset(currentPosition, resolvedInsetsTopRef.current)
+        const totalHeight = fenwickTree.getTotal()
+
+        setScrollPosition((prev) => {
+            if (Math.abs(prev - currentPosition) < POSITION_EPSILON) {
+                return prev
+            }
+            return currentPosition
+        })
+
+        const positionChanged = Math.abs(loop.lastRenderedPosition - currentPosition) >= POSITION_EPSILON
+        if (positionChanged) {
+            // 位置が実際に変化したフレームのみ onScroll を通知する。
+            // アイドル (静止) フレームで同一値を重複通知しないようにする。
+            scheduleScrollEffectRef.current({ position: logicalPosition, totalHeight })
+            loop.lastRenderedPosition = currentPosition
+            loop.idleFrames = 0
+        } else {
+            loop.idleFrames += 1
+        }
+
+        if (loop.idleFrames >= 2) {
+            stopRenderLoop()
+            return
+        }
+
+        if (typeof requestAnimationFrame === "function") {
+            loop.rafId = requestAnimationFrame((t) => runRenderLoopRef.current(t))
+            return
+        }
+        loop.loopActive = false
+    }, [fenwickTree, stopRenderLoop])
+    runRenderLoopRef.current = runRenderLoop
+
+    const ensureRenderLoop = useCallback(() => {
+        const loop = renderLoopRef.current
+        loop.idleFrames = 0
+        if (loop.loopActive) {
+            return
+        }
+        loop.loopActive = true
+        if (typeof requestAnimationFrame === "function") {
+            loop.rafId = requestAnimationFrame(runRenderLoop)
+            return
+        }
+        loop.loopActive = false
+    }, [runRenderLoop])
+
+    const updateScrollPositionImmediate = useCallback(
+        (nextPosition: number, options?: { immediate?: boolean }) => {
+            const immediate = options?.immediate ?? false
+            const logicalPosition = toLogicalPositionWithInset(nextPosition, resolvedInsets.top)
+            latestScrollPositionRef.current = nextPosition
+            if (immediate) {
+                renderLoopRef.current.lastRenderedPosition = nextPosition
+                renderLoopRef.current.idleFrames = 0
+                setScrollPosition(nextPosition)
+                scheduleScrollEffect({ position: logicalPosition, totalHeight: fenwickTree.getTotal() })
+                return
+            }
+            ensureRenderLoop()
+        },
+        [ensureRenderLoop, fenwickTree, resolvedInsets.top, scheduleScrollEffect],
+    )
+
+    /**
+     * Issues a layout-shift compensation scroll to the pane and keeps the compensation
+     * bookkeeping consistent. Returns the clamped position the pane actually applied
+     * (single source of truth). When the pane position does not change, no `onScroll`
+     * fires, so the compensation counter increment is rolled back to prevent a leak.
+     * When the applied position diverges from the target (clamped by a stale content
+     * size inside the same synchronous batch), a re-issue is scheduled for after the
+     * new content size commits.
+     *
+     * レイアウトシフト補正のスクロールをペインへ発行し、補正カウンタの整合を保つ。戻り値は
+     * ペインが実際に適用したクランプ済み位置 (単一の真実)。ペイン位置が変化しない場合は
+     * onScroll が発火しないため、カウンタ増分を巻き戻してリークを防止。適用位置が目標と
+     * 乖離した場合 (同一同期バッチ内の旧 contentSize によるクランプ) は、新 contentSize
+     * コミット後の補正再発行を予約。
+     */
+    const issueCompensationScroll = useCallback((targetPosition: number): number => {
+        const pane = scrollPaneRef.current
+        if (!pane) {
+            return targetPosition
+        }
+        // クランプで位置が変化しない場合 onScroll は発火しない。事前位置と比較して増分を戻すために保持する
+        const beforePosition = pane.getScrollPosition()
+        isCompensatingRef.current += 1
+        const appliedPosition = pane.scrollTo(targetPosition)
+        if (appliedPosition === beforePosition) {
+            // onScroll 不発: 補正カウンタの増分を巻き戻し、次の手動スクロールが補正扱いされるのを防ぐ
+            isCompensatingRef.current = Math.max(0, isCompensatingRef.current - 1)
+        }
+        if (Math.abs(appliedPosition - targetPosition) > 0.5) {
+            // 旧 contentSize でクランプされた: 新 contentSize コミット後の同期 effect で補正を再発行する
+            pendingCompensationRef.current = true
+        }
+        return appliedPosition
+    }, [])
+
+    const didApplyInitialOffsetRef = useRef(false)
+
+    /**
+     * Flushes queued onScroll notifications.
+     *
+     * キューされた onScroll 通知を実行。
+     */
+    useEffect(() => {
+        if (didApplyInitialOffsetRef.current) return
+        didApplyInitialOffsetRef.current = true
+        // 目的: 初期オフセットを一度だけ適用し (同期処理)、ペインと論理位置を同期させる。
+        // 依存関係: initialScrollOffset (初回のみ実行されるガード節あり)
+        if (typeof initialScrollOffset === "number") {
+            const paneOffset = toPanePositionWithInset(Math.max(initialScrollOffset, 0), resolvedInsets.top)
+            const needsPaneSync = Math.abs(paneOffset - latestScrollPositionRef.current) > 0.5
+            updateScrollPositionImmediate(paneOffset, { immediate: true })
+            if (needsPaneSync) {
+                scrollPaneRef.current?.scrollTo(paneOffset)
+            }
+        } else {
+            updateScrollPositionImmediate(latestScrollPositionRef.current, { immediate: true })
+        }
+    }, [initialScrollOffset, resolvedInsets.top, updateScrollPositionImmediate])
+
+    useEffect(() => {
+        // itemCount triggers recalculation of contentSize
+        void itemCount
+
+        // 目的: FenwickTree のサイズ変更を検出し、コンテンツサイズ State を同期させる。
+        // 依存関係: fenwickTree, contentSize, itemCount
+
+        // Note: Logic for updating tree structure based on getItemHeight is now delegated to useFenwickMapTree.
+
+        const totalHeight = fenwickTree.getTotal()
+        if (contentSize !== totalHeight) {
+            setContentSize(totalHeight)
+            return
+        }
+
+        // 二段補正の二段目: 補正 scrollTo が旧 contentSize でクランプされていた場合、この passive effect は
+        // ScrollPane の layout effect (sizeRef の新 contentSize への更新) より後に走るため、ここでの
+        // scrollTo は新 contentSize で正しくクランプされる。論理位置 (latestScrollPositionRef) に保持した
+        // 補正目標へ再発行し、収束後はクランプ済み実位置を単一の真実として採用する。
+        if (pendingCompensationRef.current) {
+            pendingCompensationRef.current = false
+            const pane = scrollPaneRef.current
+            if (pane && Math.abs(pane.getScrollPosition() - latestScrollPositionRef.current) > 0.5) {
+                const appliedPosition = issueCompensationScroll(latestScrollPositionRef.current)
+                // 再発行後もなお目標に届かない場合 (目標が負値等) はクランプ済み実位置へ収束させ、
+                // 再発行の連鎖を断つ
+                pendingCompensationRef.current = false
+                updateScrollPositionImmediate(appliedPosition, { immediate: true })
+            }
+        }
+    }, [fenwickTree, contentSize, itemCount, issueCompensationScroll, updateScrollPositionImmediate])
+
+    useEffect(() => {
+        // 目的: サイズ変更やスクロール等でターゲットインデックスの位置がずれた場合、スクロール位置を補正 (ドリフト補正) する。
+        // 依存関係: contentSize, fenwickTree, itemCount, resolvedInsets.top, updateScrollPositionImmediate, viewportSize
+        if (pendingVisibleStartIndexRef.current !== null) {
+            const { index, align, offset } = pendingVisibleStartIndexRef.current
+            const safeIndex = sanitizeIndex(index, itemCount)
+            const { cumulative: itemBottom, currentValue: itemHeight } = fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: false } })
+
+            if (itemBottom !== undefined && itemHeight !== undefined) {
+                const itemTop = Math.max(itemBottom - itemHeight, 0)
+                let targetLogicalPosition = itemTop
+
+                if (align === "bottom") {
+                    targetLogicalPosition = itemBottom - viewportSize
+                } else if (align === "center") {
+                    targetLogicalPosition = itemTop + itemHeight / 2 - viewportSize / 2
+                }
+
+                if (offset) {
+                    targetLogicalPosition -= offset
+                }
+
+                targetLogicalPosition = Math.max(0, targetLogicalPosition)
+
+                const maxScrollPosition = Math.max(0, contentSize + resolvedInsets.top + resolvedInsets.bottom - viewportSize)
+                const targetPanePosition = Math.min(toPanePositionWithInset(targetLogicalPosition, resolvedInsets.top), maxScrollPosition)
+
+                if (Math.abs(targetPanePosition - latestScrollPositionRef.current) > 1.0) {
+                    Logger.debug("[VirtualScroll] Drift correction", {
+                        from: latestScrollPositionRef.current,
+                        to: targetPanePosition,
+                        targetIndex: safeIndex,
+                    })
+                    // Guard against double increment if multiple effects fire before scroll handles it
+                    if (isCompensatingRef.current === 0) {
+                        isCompensatingRef.current += 1
+                    }
+                    scrollPaneRef.current?.scrollTo(targetPanePosition)
+                    updateScrollPositionImmediate(targetPanePosition, { immediate: true })
+                }
+            }
+        }
+        isResizingRef.current = false
+    }, [contentSize, fenwickTree, itemCount, resolvedInsets.top, updateScrollPositionImmediate, viewportSize, resolvedInsets.bottom])
+
+    useEffect(() => {
+        // 目的: 上部インセットが動的に変更された場合、論理スクロール位置を維持したまま、ペインのスクロール位置を再計算してずらす。
+        // 依存関係: resolvedInsets.top
+        const previousTop = previousTopInsetRef.current
+        if (previousTop === resolvedInsets.top) return
+
+        const logicalPosition = toLogicalPositionWithInset(latestScrollPositionRef.current, previousTop)
+        const panePosition = toPanePositionWithInset(logicalPosition, resolvedInsets.top)
+        previousTopInsetRef.current = resolvedInsets.top
+        latestScrollPositionRef.current = panePosition
+        scrollPaneRef.current?.scrollTo(panePosition)
+        updateScrollPositionImmediate(panePosition, { immediate: true })
+    }, [resolvedInsets.top, updateScrollPositionImmediate])
+
+    /**
+     * Updates the size of a specific item. Contract: after this call, `getItemHeight(index)` must
+     * return the same `size`; `getItemHeight` is the source of truth, so rows inside the current
+     * rendering window (including overscan) are otherwise reverted to the `getItemHeight` value by
+     * height reconciliation on the next render.
+     *
+     * 指定されたアイテムのサイズを更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を返すこと。
+     * `getItemHeight` が正であるため、そうでない場合は描画ウィンドウ (オーバースキャン含む) 内の行が
+     * 次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。
+     */
+    const updateItemSize = useCallback(
+        (index: number, size: number) => {
+            if (itemCount === 0) {
+                return
+            }
+            const safeIndex = sanitizeIndex(index, itemCount)
+            const oldSize = fenwickTree.get(safeIndex)
+            const delta = size - oldSize
+
+            const total = fenwickTree.update(safeIndex, size)
+            if (total !== undefined) {
+                setContentSize(total)
+            }
+            Logger.debug("[VirtualScroll] Updated item size manually", { index: safeIndex, size, total })
+
+            // Layout Shift Compensation (レイアウトシフト補正)
+            // Update scroll position if the size change happened above the current viewport
+            // サイズ変更が現在のビューポートより上部で発生した場合、視覚的な位置ズレを防ぐためにスクロール位置を補正します。
+            let activeVisibleStartIndex = pendingVisibleStartIndexRef.current ? pendingVisibleStartIndexRef.current.index : null
+
+            // If no pending target, calculate the current visible index based on scroll position
+            // ターゲットインデックスが保留中でない場合、現在のスクロール位置に基づいて現在の可視インデックスを計算します
+            if (activeVisibleStartIndex === null) {
+                const currentScrollTop = latestScrollPositionRef.current
+                const insetsTop = normalizeInsets(contentInsets).top
+                const logicalScrollTop = toLogicalPositionWithInset(currentScrollTop, insetsTop)
+                // Use materialize: false for performance, we just need the index
+                const { index, cumulative } = fenwickTree.findIndexAtOrAfter(logicalScrollTop, { materializeOption: { materialize: false } })
+                // findIndexAtOrAfter は「下端(cumulative) >= scrollTop の最小 index」を返すため、
+                // アイテム index の下端がちょうど scrollTop に一致する場合、その行は完全にビューポート上方にある。
+                // computeRenderingRanges (cumulative === effectiveScrollPosition の特例) と同じく可視先頭を index+1 に補正する。
+                activeVisibleStartIndex = cumulative !== undefined && cumulative === logicalScrollTop ? index + 1 : index
+            }
+
+            // Allow for a small buffer in case of slight misalignments or stale refs
+            // If the item is strictly above the visible start, it pushes content down.
+            // アイテムが（ほぼ）確実に可視領域より上にある場合、コンテンツ全体を押し下げます
+            if (activeVisibleStartIndex !== -1 && safeIndex < activeVisibleStartIndex && delta !== 0) {
+                // Use latestScrollPositionRef as the source of truth for the current position
+                // to avoid reading stale DOM values during batched updates (e.g. multiple items resizing at once).
+                const currentPanePosition = latestScrollPositionRef.current
+                const newPosition = currentPanePosition + delta
+
+                // 同一同期バッチ内では ScrollPane の sizeRef が旧 contentSize のままのため、scrollTo は
+                // 旧最大値でクランプされ得る。issueCompensationScroll がカウンタのリークを防ぎつつ乖離時の
+                // 再発行を予約し、論理位置 (latestScrollPositionRef) には補正目標を保持して二段目の収束先とする。
+                issueCompensationScroll(newPosition)
+                updateScrollPositionImmediate(newPosition, { immediate: true })
+                Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (manual update)", { from: currentPanePosition, to: newPosition, causedByIndex: safeIndex, delta, activeVisibleStartIndex })
+            }
+        },
+        [fenwickTree, itemCount, issueCompensationScroll, updateScrollPositionImmediate, contentInsets],
+    )
+
+    /**
+     * Scrolls to the requested logical index.
+     *
+     * 指定インデックスへのスクロールを実行。
+     */
+    const scrollToIndex = useCallback(
+        (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number }) => {
+            if (!scrollPaneRef.current || itemCount === 0) {
+                return
+            }
+            const safeIndex = sanitizeIndex(index, itemCount)
+            const safeIndexFrom = sanitizeIndex(safeIndex - overscanCount * 2, itemCount)
+            const safeIndexTo = sanitizeIndex(safeIndex + overscanCount * 2, itemCount)
+            const { cumulative: itemBottom, total, currentValue: itemHeight } = fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: true, ranges: [{ from: safeIndexFrom, to: safeIndexTo }] } })
+
+            Logger.debug("[VirtualScroll] Scrolling to index:", safeIndex, "ItemBottom:", itemBottom, "Total height:", total, "ItemHeight:", itemHeight, "safeIndexFrom:", safeIndexFrom, "safeIndexTo:", safeIndexTo)
+
+            if (!total) {
+                return
+            }
+
+            const itemTop = Math.max(itemBottom - itemHeight, 0)
+            let targetLogicalPosition = itemTop
+
+            if (options?.align === "bottom") {
+                targetLogicalPosition = itemBottom - viewportSize
+            } else if (options?.align === "center") {
+                targetLogicalPosition = itemTop + itemHeight / 2 - viewportSize / 2
+            }
+
+            if (options?.offset) {
+                targetLogicalPosition -= options.offset
+            }
+
+            // Ensure we don't scroll past the content
+            // targetLogicalPosition = minmax(targetLogicalPosition, 0, total - viewportSize)
+            // Actually ScrollPane handles bounds usually, but let's be safe with 0
+            targetLogicalPosition = Math.max(0, targetLogicalPosition)
+
+            const paneOffset = toPanePositionWithInset(targetLogicalPosition, resolvedInsets.top)
+
+            // Clamp the scroll position to the maximum allowed value to ensure state consistency with ScrollPane.
+            // If we don't clamp, VirtualScroll might think it's at 501,000px while ScrollPane is capped at 499,991px.
+            // This mismatch causes the visible range calculation to shift, potentially rendering items at the wrong relative position (e.g. at the top instead of bottom).
+            // Use ScrollPane's content size directly to avoid costly calculations with large datasets.
+            // スクロール位置を最大許容値にクランプして、ScrollPane との状態整合性を保ちます。
+            // クランプしないと、VirtualScroll が 501,000px にあると認識しているのに、ScrollPane が 499,991px で止まっているという不整合が起きる可能性があります。
+            // この不整合により可視範囲計算がずれ、アイテムが誤った相対位置（例：下端にあるべきアイテムが上端に来るなど）に描画される原因となります。
+            const totalContentHeight = scrollPaneRef.current?.getContentSize() ?? total + resolvedInsets.top + resolvedInsets.bottom
+            const maxScrollPosition = Math.max(0, totalContentHeight - viewportSize)
+            const clampedPaneOffset = Math.min(paneOffset, maxScrollPosition)
+
+            // Set the pending target index to anchor the layout shift compensation
+            // レイアウトシフト補正のアンカーとして、保留中のターゲットインデックスを設定します
+            pendingVisibleStartIndexRef.current = {
+                index: safeIndex,
+                align: options?.align,
+                offset: options?.offset,
+            }
+
+            const currentPanePosition = scrollPaneRef.current?.getScrollPosition() ?? -1
+            const shouldScroll = Math.abs(currentPanePosition - clampedPaneOffset) > 0.5
+
+            // Reset flags for strict accounting to avoid leaks
+            // リークを防ぐため、補正関連のフラグをリセットします
+            isProgrammaticScrollRef.current = false
+            isCompensatingRef.current = 0
+
+            if (shouldScroll) {
+                // Mark as programmatic to prevent clearing the anchor in handleScroll
+                // handleScroll 内でアンカーが意図せずクリアされるのを防ぐため、プログラムによるスクロールとしてマークします
+                isProgrammaticScrollRef.current = true
+                // Increment compensating ref to protect anchor during system-initiated scroll
+                // システム主導のスクロール中にアンカーを保護するため、補正中参照カウンタをインクリメントします
+                isCompensatingRef.current += 1
+
+                scrollPaneRef.current?.scrollTo(clampedPaneOffset)
+            }
+
+            setContentSize(total)
+            updateScrollPositionImmediate(clampedPaneOffset, { immediate: true })
+
+            Logger.debug("[VirtualScroll] Setting scroll position to:", clampedPaneOffset, { original: paneOffset, max: maxScrollPosition })
+        },
+        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, updateScrollPositionImmediate],
+    )
+
+    /**
+     * Scrolls to a raw offset while resolving to an index.
+     *
+     * オフセットをインデックスに変換しつつスクロール。
+     */
+    const scrollTo = useCallback(
+        (newPosition: number) => {
+            if (!scrollPaneRef.current || itemCount === 0) {
+                return
+            }
+            const total = fenwickTree.getTotal()
+            const safePosition = minmax(Math.floor(newPosition), 0, total)
+            const { index, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(safePosition, { materializeOption: { materialize: false } })
+
+            // Calculate offset relative to item top to ensure precise positioning
+            // itemTop = cumulative - currentValue
+            const itemTop = (cumulative ?? 0) - (currentValue ?? 0)
+            const offset = itemTop - safePosition
+
+            scrollToIndex(index, { offset })
+        },
+        [fenwickTree, itemCount, scrollToIndex],
+    )
+
+    /**
+     * Imperative scroll entry supporting updater functions.
+     *
+     * アップデーター関数対応の命令的スクロール入口。
+     */
+    const scrollToHandle = useCallback(
+        (position: number | ((prev: number) => number)) => {
+            const currentLogical = toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top)
+            const resolvedLogical = typeof position === "function" ? position(currentLogical) : position
+            scrollTo(resolvedLogical)
+            const panePosition = scrollPaneRef.current?.getScrollPosition()
+            const effectivePosition = typeof panePosition === "number" ? panePosition : latestScrollPositionRef.current
+            updateScrollPositionImmediate(effectivePosition)
+            return effectivePosition
+        },
+        [resolvedInsets.top, scrollTo, updateScrollPositionImmediate],
+    )
+
+    /**
+     * Handles scroll events from the pane.
+     *
+     * ペインのスクロールイベントを処理。
+     */
+    const handleScroll = useCallback(
+        (newPosition: number, prevPosition: number) => {
+            Logger.debug("[VirtualScroll] Scroll position changed:", newPosition)
+
+            const isProgrammatic = isProgrammaticScrollRef.current
+            if (isProgrammatic) {
+                isProgrammaticScrollRef.current = false
+            }
+
+            const isCompensating = isCompensatingRef.current > 0
+            if (isCompensating) {
+                isCompensatingRef.current = 0
+            }
+
+            // If manual scroll (neither programmatic nor compensating), clear the pending anchor
+            // This ensures that manual scrolling immediately detaches from any previous scroll target
+            if (!(isProgrammatic || isCompensating || isResizingRef.current)) {
+                pendingVisibleStartIndexRef.current = null
+            }
+
+            updateScrollPositionImmediate(newPosition)
+
+            if (enableScrollToTopBottomButtons) {
+                if (isProgrammatic || isCompensating) {
+                    return
+                }
+
+                const diff = newPosition - prevPosition
+                Logger.debug("[VirtualScroll] Scroll diff:", diff, "New:", newPosition, "Prev:", prevPosition)
+                if (Math.abs(diff) > 1) {
+                    const direction = diff > 0 ? "down" : "up"
+                    setScrollDirection(direction)
+                    setShowScrollButtons(true)
+                    Logger.debug("[VirtualScroll] Showing scroll buttons. Direction:", direction)
+
+                    if (scrollButtonTimerRef.current) {
+                        clearTimeout(scrollButtonTimerRef.current)
+                    }
+                    scrollButtonTimerRef.current = setTimeout(() => {
+                        setShowScrollButtons(false)
+                        Logger.debug("[VirtualScroll] Hiding scroll buttons")
+                    }, 2000)
+                }
+            }
+        },
+        [updateScrollPositionImmediate, enableScrollToTopBottomButtons],
+    )
+
+    // レンダリング範囲を計算
+    const logicalScrollPosition = useMemo(() => toLogicalPositionWithInset(scrollPosition, resolvedInsets.top), [resolvedInsets.top, scrollPosition])
+
+    const renderingRanges = useMemo(() => {
+        // useMemo 内では State の contentSize ではなく、常に最新の計算結果を持つ fenwickTree.getTotal() を使用する。
+        // これにより、アイテム数が大幅に減少した直後でも、古い contentSize (State) に基づく誤ったレンダリング範囲計算を防ぐことができる。
+        // contentSize (State) の更新は非同期で行われるため、一瞬古い状態が残る可能性があるが、fenwickTree は同期的であり信頼性が高い。
+        const currentTotalHeight = fenwickTree.getTotal()
+        const ranges = computeRenderingRanges(logicalScrollPosition, viewportSize, overscanCount, itemCount, getItemHeight, fenwickTree, currentTotalHeight)
+        Logger.debug("[VirtualScroll] Calculated rendering range:", () => ({
+            ...ranges,
+            scrollPosition: logicalScrollPosition,
+            renderingContentSize: currentTotalHeight,
+            overscanCount,
+            viewportSize,
+        }))
+        return ranges
+    }, [logicalScrollPosition, viewportSize, overscanCount, itemCount, getItemHeight, fenwickTree]) // contentSize を依存配列から削除
+
+    const { renderingStartIndex, renderingEndIndex, visibleStartIndex, visibleEndIndex } = renderingRanges
+
+    const focusItemAtIndex = useCallback(
+        (index: number, options?: { ensureVisible?: boolean }) => {
+            if (!enableKeyboardNavigation || itemCount === 0) {
+                return
+            }
+            const safeIndex = sanitizeIndex(index, itemCount)
+            const ensureVisible = options?.ensureVisible ?? true
+            if (!ensureVisible) {
+                const existingElement = itemRefs.current.get(safeIndex)
+                if (existingElement) {
+                    pendingFocusIndexRef.current = null
+                    lastFocusedIndexRef.current = safeIndex
+                    tryFocusElement(existingElement)
+                }
+                return
+            }
+
+            const prefix = fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: false } })
+            const itemHeight = prefix.currentValue
+            const itemTop = Math.max(prefix.cumulative - itemHeight, 0)
+            const itemBottom = itemTop + itemHeight
+            const viewportTop = toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top)
+            const viewportBottom = viewportTop + viewportSize
+            const needsScroll = itemTop < viewportTop || itemBottom > viewportBottom
+            if (needsScroll) {
+                scrollToIndex(safeIndex)
+                // オーバースキャン内で既にマウント済みの行は、スクロールしても ref コールバックが
+                // 再実行されない (handleRef の identity 不変) ため、ここで直接フォーカスを適用する。
+                // マウント済み要素へフォーカスできたら pendingFocusIndexRef を残さない
+                // (残すと後刻の無関係な再マウント時にフォーカスを奪ってしまう)。
+                const mounted = itemRefs.current.get(safeIndex)
+                if (mounted) {
+                    pendingFocusIndexRef.current = null
+                    lastFocusedIndexRef.current = safeIndex
+                    tryFocusElement(mounted)
+                } else {
+                    pendingFocusIndexRef.current = safeIndex
+                }
+                return
+            }
+
+            const element = itemRefs.current.get(safeIndex)
+            if (element) {
+                pendingFocusIndexRef.current = null
+                lastFocusedIndexRef.current = safeIndex
+                tryFocusElement(element)
+                return
+            }
+            pendingFocusIndexRef.current = safeIndex
+        },
+        [enableKeyboardNavigation, itemCount, fenwickTree, resolvedInsets.top, scrollToIndex, tryFocusElement, viewportSize],
+    )
+
+    const handleItemKeyDown = useCallback(
+        (event: React.KeyboardEvent<HTMLDivElement>, index: number) => {
+            if (!enableKeyboardNavigation || event.defaultPrevented) {
+                return
+            }
+            if (event.altKey || event.metaKey || event.ctrlKey) {
+                return
+            }
+            const target = event.target as HTMLElement | null
+            if (target) {
+                const tagName = target.tagName
+                if (tagName === "INPUT" || tagName === "TEXTAREA" || tagName === "SELECT") {
+                    return
+                }
+                if (target.isContentEditable) {
+                    return
+                }
+            }
+            if (event.key === "ArrowDown") {
+                if (index < itemCount - 1) {
+                    event.preventDefault()
+                    focusItemAtIndex(index + 1)
+                }
+                return
+            }
+            if (event.key === "ArrowUp") {
+                if (index > 0) {
+                    event.preventDefault()
+                    focusItemAtIndex(index - 1)
+                }
+                return
+            }
+            if (event.key === "PageDown") {
+                if (index < itemCount - 1) {
+                    event.preventDefault()
+                    // 可視範囲は毎レンダー同期している currentRangeRef から読む。
+                    // visibleStart/EndIndex を依存配列に入れると、行境界を跨ぐたびに handleItemKeyDown の
+                    // identity が変わり全 VirtualScrollItem の React.memo が無効化されるため。
+                    const { visibleStartIndex: vStart, visibleEndIndex: vEnd } = currentRangeRef.current
+                    const visibleCount = Math.max(vEnd - vStart + 1, 1)
+                    const delta = Math.max(visibleCount, 1)
+                    const targetIndex = sanitizeIndex(Math.min(index + delta, itemCount - 1), itemCount)
+                    focusItemAtIndex(targetIndex)
+                }
+                return
+            }
+            if (event.key === "PageUp") {
+                if (index > 0) {
+                    event.preventDefault()
+                    const { visibleStartIndex: vStart, visibleEndIndex: vEnd } = currentRangeRef.current
+                    const visibleCount = Math.max(vEnd - vStart + 1, 1)
+                    const delta = Math.max(visibleCount, 1)
+                    const targetIndex = sanitizeIndex(index - delta, itemCount)
+                    focusItemAtIndex(targetIndex)
+                }
+            }
+        },
+        [enableKeyboardNavigation, itemCount, focusItemAtIndex],
+    )
+
+    const handleItemFocus = useCallback(
+        (index: number) => {
+            if (!enableKeyboardNavigation) {
+                return
+            }
+            const safeIndex = sanitizeIndex(index, itemCount)
+            pendingFocusIndexRef.current = null
+            lastFocusedIndexRef.current = safeIndex
+            onItemFocus?.(safeIndex)
+        },
+        [enableKeyboardNavigation, itemCount, onItemFocus],
+    )
+
+    // レンダリング範囲が変更されたらコールバックを呼ぶ
+    useEffect(() => {
+        const scrollPaneScrollPosition = scrollPaneRef.current?.getScrollPosition() ?? 0
+        const paneScrollPosition = latestScrollPositionRef.current
+        const logicalPosition = toLogicalPositionWithInset(paneScrollPosition, resolvedInsets.top)
+
+        Logger.debug("[VirtualScroll] Range change effect triggered", () => ({
+            renderingStartIndex,
+            renderingEndIndex,
+            visibleStartIndex,
+            visibleEndIndex,
+            scrollPositionState: scrollPosition,
+            paneScrollPosition,
+            logicalScrollPosition: logicalPosition,
+            contentSize,
+            scrollPaneScrollPosition,
+        }))
+
+        scheduleRangeEffect({
+            renderingStartIndex,
+            renderingEndIndex,
+            visibleStartIndex,
+            visibleEndIndex,
+            scrollPosition: logicalPosition,
+            totalHeight: contentSize,
+        })
+    }, [contentSize, renderingEndIndex, renderingStartIndex, resolvedInsets.top, scheduleRangeEffect, scrollPosition, visibleEndIndex, visibleStartIndex])
+
+    /**
+     * Produces visible item nodes and schedules height reconciliation.
+     *
+     * 可視アイテムを描画しつつ高さとの差分更新を手配。
+     */
+    const renderOverlay = useCallback(() => {
+        if (!enableScrollToTopBottomButtons) {
+            return null
+        }
+
+        const isVisible = showScrollButtons && scrollDirection !== null
+        const isTop = scrollDirection === "up"
+
+        return (
+            <div className="aqvs-scroll-to-edge-overlay" data-visible={isVisible}>
+                {isTop ? (
+                    <div className="aqvs-scroll-to-edge-button-container aqvs-scroll-to-edge-button-container-top">
+                        <button
+                            type="button"
+                            className="aqvs-scroll-to-edge-button"
+                            onClick={(e) => {
+                                e.stopPropagation()
+                                isProgrammaticScrollRef.current = true
+                                scrollToIndex(0)
+                                setShowScrollButtons(false)
+                            }}>
+                            Top
+                        </button>
+                    </div>
+                ) : (
+                    <div className="aqvs-scroll-to-edge-button-container aqvs-scroll-to-edge-button-container-bottom">
+                        <button
+                            type="button"
+                            className="aqvs-scroll-to-edge-button"
+                            onClick={(e) => {
+                                e.stopPropagation()
+                                isProgrammaticScrollRef.current = true
+                                scrollToIndex(itemCount - 1)
+                                setShowScrollButtons(false)
+                            }}>
+                            Bottom
+                        </button>
+                    </div>
+                )}
+            </div>
+        )
+    }, [enableScrollToTopBottomButtons, showScrollButtons, scrollDirection, scrollToIndex, itemCount])
+
+    // 量子化アンカー (fix: LayoutUnit/f32 精度対策)。行 top はコンテンツ絶対座標そのままではなく
+    // 「絶対座標 - アンカー」で描画し、ラッパー側 translateY にアンカーを足し戻す。
+    // アンカーは描画ウィンドウ先頭が現アンカーから ANCHOR_REBASE_DISTANCE を超えて離れたときだけ
+    // 再基準化する (通常リストでは 0 のままとなり memo 安定性は従来と同一。再基準化フレームのみ
+    // 全行の top が変わるが稀であり許容)。
+    // ref は「最後に採用したアンカー」の再基準化判定用。描画に使う値は memo の返り値 (renderAnchor)
+    // から取り、行 top と translateY が常に同一アンカー基準で整合するようにする。
+    const renderAnchorRef = useRef(0)
+
+    const { visibleItems, renderAnchor } = useMemo(() => {
+        // contentSize は memo 本体では直接使わないが「反応辺」として依存に含める:
+        // fenwickTree は安定参照のため、非同期高さ更新 (updateItemSize / 高さ照合マイクロタスクの
+        // fenwickTree.updates) で木の prefix 和が変わってもこの memo は自動では失効しない。
+        // 両経路とも setContentSize を伴うため、contentSize を依存へ含めることで
+        // 行 top を最新の prefix 和で確実に再計算させる (報告座標と視覚描画の desync 防止)。
+        void contentSize
+
+        if (itemCount === 0) {
+            return {
+                visibleItems: (
+                    <div className="aqvs-no-items-container">
+                        <div className="aqvs-no-items-text">No items</div>
+                    </div>
+                ),
+                renderAnchor: 0,
+            }
+        }
+
+        const safeRenderingStartIndex = sanitizeIndex(renderingStartIndex, itemCount)
+        const safeRenderingEndIndex = sanitizeIndex(renderingEndIndex, itemCount)
+        const { cumulative, currentValue: oldHeight } = fenwickTree.prefixSum(safeRenderingStartIndex, { materializeOption: { materialize: false } })
+        const startPosition = cumulative - oldHeight
+
+        // 量子化アンカーの再基準化: 描画ウィンドウ先頭が現アンカーから一定距離を超えて離れたときだけ
+        // アンカーを付け替える。これにより行 top (= 絶対座標 - アンカー) とラッパー translateY の
+        // 双方が常に ±ANCHOR_REBASE_DISTANCE 近傍の小さな値に収まり、巨大リストの深部でも
+        // ブラウザのレイアウト座標上限 (LayoutUnit) や compositor f32 の量子化誤差を踏まない。
+        if (Number.isFinite(startPosition) && Math.abs(startPosition - renderAnchorRef.current) > ANCHOR_REBASE_DISTANCE) {
+            renderAnchorRef.current = startPosition
+        }
+        const currentAnchor = renderAnchorRef.current
+
+        const toUpdateHeights: Array<{ index: number; value: number }> = []
+        const nodes: ReactNode[] = []
+
+        let cumulativeSizeDelta = 0
+        // 描画ウィンドウ先頭行の絶対 top から、各行の高さを加算して top を求める (O(k))。
+        // 行ごとに prefixSum(i) を呼ぶと O(k·log n) + 多数の BigInt 割り当てが発生するため回避する。
+        let runningBaseOffset = startPosition
+
+        for (let i = safeRenderingStartIndex; i <= safeRenderingEndIndex; i++) {
+            if (nodes.length >= MAX_RENDERED_ITEMS) {
+                // 病的な描画範囲 (高さ 0 行の巨大な連続など) で DOM ノード数が爆発しないよう安全上限で打ち切る。
+                Logger.warn("[VirtualScroll] Rendered item count reached the safety cap; truncating render window.", { cap: MAX_RENDERED_ITEMS, safeRenderingStartIndex, safeRenderingEndIndex })
+                break
+            }
+            const newHeight = getItemHeight(i)
+            const cachedHeight = fenwickTree.get(i)
+            const heightDelta = newHeight - cachedHeight
+
+            if (heightDelta !== 0) {
+                toUpdateHeights.push({ index: i, value: newHeight })
+            }
+
+            // Adjust the item's top position by adding the cumulative size delta from previous items.
+            // This ensures that if previous items have changed size, the current item is pushed down/up immediately
+            // within the current render cycle, preventing visual glitches (overlapping items) before the re-render.
+            //
+            // 前のアイテムまでの累積的な高さの変化分（cumulativeSizeDelta）を加算して、アイテムの top 位置を補正します。
+            // これにより、前のアイテムのサイズが変わった場合でも、現在のレンダリングサイクル内で即座に位置が調整され、
+            // 再レンダリングまでの間に発生する表示崩れ（アイテムの重なりなど）を防ぐことができます。
+            //
+            // top は「コンテンツ絶対座標 (actualOffset) - 量子化アンカー」とする。描画ウィンドウ起点からの
+            // 相対座標にすると、ウィンドウが 1 行ずれるたびに残存行の top prop が一斉に変化し、
+            // VirtualScrollItem の React.memo が全行で無効化されてしまう。アンカーは再基準化時にしか
+            // 動かないため memo 安定性は絶対座標と同等で、かつ巨大リストでも top が小さな値に収まる。
+            // 上部インセット・スクロール追従・アンカーはラッパー側の transform で一括補正する。
+            const actualOffset = runningBaseOffset + cumulativeSizeDelta
+            const key = getItemKey ? getItemKey(i) : i
+
+            nodes.push(
+                <VirtualScrollItem
+                    key={key}
+                    index={i}
+                    top={actualOffset - currentAnchor}
+                    height={newHeight}
+                    item={getItem(i)}
+                    clipItemHeight={clipItemHeight}
+                    enableKeyboardNavigation={enableKeyboardNavigation}
+                    onKeyDown={handleItemKeyDown}
+                    onFocus={handleItemFocus}
+                    registerItemRef={registerItemRef}>
+                    {children}
+                </VirtualScrollItem>,
+            )
+
+            cumulativeSizeDelta += heightDelta
+            runningBaseOffset += cachedHeight
+        }
+
+        if (toUpdateHeights.length > 0) {
+            Promise.resolve().then(() => {
+                // アンマウント後のみ破棄する。初回レンダー由来のマイクロタスクは passive effect より
+                // 先に実行され得るため、「マウント済みか」の判定では正当な初回照合まで破棄してしまう。
+                if (isUnmountedRef.current) {
+                    return
+                }
+
+                let shiftAmount = 0
+                // Calculate shift for items strictly above the viewport
+                // renderingStartIndex (captured in closure) typically includes overscan, but what we care about is the VISIBLE start.
+                // visibleStartIndex is also captured in this closure.
+                for (const update of toUpdateHeights) {
+                    if (update.index < visibleStartIndex) {
+                        const oldVal = fenwickTree.get(update.index)
+                        shiftAmount += update.value - oldVal
+                    }
+                }
+
+                const total = fenwickTree.updates(toUpdateHeights)
+                if (isUnmountedRef.current || typeof total !== "number") {
+                    return
+                }
+                setContentSize(total)
+                Logger.debug("[VirtualScroll] Updated heights for items", toUpdateHeights, "New total height:", total)
+                const panePosition = scrollPaneRef.current?.getScrollPosition() ?? latestScrollPositionRef.current
+
+                if (shiftAmount !== 0) {
+                    const newPosition = panePosition + shiftAmount
+                    // updateItemSize と同型: scrollTo は旧 contentSize でクランプされ得るため、
+                    // issueCompensationScroll でリークを防ぎつつ、乖離時は contentSize 同期 effect で再発行する。
+                    issueCompensationScroll(newPosition)
+                    updateScrollPositionImmediate(newPosition, { immediate: true })
+                    Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (auto update)", { from: panePosition, to: newPosition, shiftAmount })
+                } else if (panePosition !== latestScrollPositionRef.current) {
+                    updateScrollPositionImmediate(panePosition)
+                }
+            })
+        }
+
+        return { visibleItems: nodes, renderAnchor: currentAnchor }
+    }, [
+        children,
+        clipItemHeight,
+        contentSize,
+        enableKeyboardNavigation,
+        itemCount,
+        fenwickTree,
+        getItem,
+        getItemKey,
+        getItemHeight,
+        handleItemFocus,
+        handleItemKeyDown,
+        issueCompensationScroll,
+        registerItemRef,
+        renderingEndIndex,
+        renderingStartIndex,
+        updateScrollPositionImmediate,
+        visibleStartIndex,
+    ])
+
+    const renderVisibleItems = useCallback(
+        (currentScrollPosition: number) => {
+            const shouldUseThrottledPosition = (callbackThrottleMs ?? 0) > 0
+            const diff = Math.abs(currentScrollPosition - scrollPosition)
+            const rawEffectiveScrollPosition = shouldUseThrottledPosition && diff > 0.5 ? scrollPosition : currentScrollPosition
+            const effectiveScrollPosition = toLogicalPositionWithInset(rawEffectiveScrollPosition, resolvedInsets.top)
+
+            Logger.debug("[VirtualScroll] Rendering visible items", () => ({
+                currentScrollPosition,
+                effectiveScrollPosition,
+                renderingStartIndex,
+                renderingEndIndex,
+                itemCount,
+                viewportSize,
+                callbackThrottleMs,
+                diff,
+                rawEffectiveScrollPosition,
+            }))
+
+            if (itemCount === 0) {
+                return visibleItems
+            }
+
+            // アイテム top は「コンテンツ絶対座標 - 量子化アンカー」なので、ラッパー側でスクロール追従・
+            // 上部インセット・アンカーを一括補正する。ペイン座標 (rawEffectiveScrollPosition) を基準に
+            // visual = insets.top + (top + anchor) - pane となるよう、ラッパーを insets.top + anchor - pane
+            // だけ移動させる。アンカーと pane は同オーダーで追従するため translateY は常に小さな値に収まり、
+            // compositor f32 の精度限界 (2^24px 付近からの量子化) を踏まない。ラッパーは CSS の
+            // position:absolute (top:0 = パディング辺 = 0) のまま transform: translateY で動かすことで、
+            // 毎フレームのリフローを避けコンポジタのみで完結させる。
+            // アンカーは visibleItems と同じ memo の返り値を使い、行 top との整合を保証する。
+            const containerTop = resolvedInsets.top + renderAnchor - rawEffectiveScrollPosition
+
+            const bottomInset =
+                resolvedInsets.bottom > 0 ? (
+                    <div
+                        key="virtualscroll-bottom-inset"
+                        className="aqvs-bottom-inset"
+                        style={{
+                            // ラッパー座標での bottom インセット位置 = コンテンツ総高さ (最終行の下端) - アンカー。
+                            top: fenwickTree.getTotal() - renderAnchor,
+                            height: resolvedInsets.bottom,
+                        }}
+                    />
+                ) : null
+
+            Logger.debug("[VirtualScroll] Rendering items", () => ({
+                containerTop,
+                logicalScrollPosition,
+                resolvedInsets,
+                effectiveScrollPosition,
+            }))
+
+            return (
+                <div className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${containerTop}px)`, willChange: "transform" }}>
+                    {visibleItems}
+                    {bottomInset}
+                </div>
+            )
+        },
+        [callbackThrottleMs, itemCount, fenwickTree, logicalScrollPosition, renderAnchor, renderingEndIndex, renderingStartIndex, resolvedInsets, scrollPosition, viewportSize, visibleItems],
+    )
+
+    const currentRange = useMemo<VirtualScrollRange>(
+        () => ({
+            renderingStartIndex: renderingRanges.renderingStartIndex,
+            renderingEndIndex: renderingRanges.renderingEndIndex,
+            visibleStartIndex: renderingRanges.visibleStartIndex,
+            visibleEndIndex: renderingRanges.visibleEndIndex,
+            scrollPosition: logicalScrollPosition,
+            totalHeight: fenwickTree.getTotal(), // contentSize (State) ではなく最新値を反映
+        }),
+        // contentSize を依存に含めることで、updateItemSize/updates 等で木の総高さが変わった際に
+        // (fenwickTree は安定参照のため getTotal() の変化だけでは再計算されない) 総高さを再取得する。
+        [renderingRanges, logicalScrollPosition, fenwickTree, contentSize],
+    )
+
+    useEffect(() => {
+        // 目的: 描画範囲を最新の状態で同期する ref を更新する。
+        // 依存関係: currentRange
+        currentRangeRef.current = currentRange
+    }, [currentRange])
+
+    useImperativeHandle(
+        ref,
+        () => ({
+            getScrollPosition: () => scrollPaneRef.current?.getScrollPosition() ?? -1,
+            getContentSize: () => scrollPaneRef.current?.getContentSize() ?? -1,
+            getViewportSize: () => scrollPaneRef.current?.getViewportSize() ?? -1,
+            scrollTo: scrollToHandle,
+            scrollToIndex,
+            getFenwickTreeTotalHeight: () => fenwickTree.getTotal(),
+            getFenwickSize: () => fenwickTree.getSize(),
+            focusItemAtIndex,
+            getRange: () => currentRangeRef.current,
+            updateItemSize,
+        }),
+        [scrollToHandle, scrollToIndex, fenwickTree, focusItemAtIndex, updateItemSize],
+    )
+
+    const totalContentHeight = fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom
+
+    return (
+        <ScrollPane
+            ref={scrollPaneRef}
+            contentSize={totalContentHeight}
+            viewportSize={viewportSize}
+            className={className}
+            testId={testId}
+            onScroll={handleScroll}
+            background={background}
+            tapScrollCircleOptions={tapScrollCircleOptions}
+            inertiaOptions={inertiaOptions}
+            itemCount={itemCount}
+            scrollBarWidth={scrollBarWidth}
+            enableThumbDrag={enableThumbDrag}
+            enableTrackClick={enableTrackClick}
+            enableArrowButtons={enableArrowButtons}
+            enablePointerDrag={enablePointerDrag}
+            renderThumbOverlay={renderThumbOverlay}
+            wheelSpeedMultiplier={wheelSpeedMultiplier}
+            onWheelHorizontal={onWheelHorizontal}
+            contentInsets={resolvedInsets}
+            visibleStartIndex={visibleStartIndex}
+            visibleEndIndex={visibleEndIndex}
+            renderOverlay={renderOverlay}
+            initialScrollPosition={initialValues.position}>
+            {renderVisibleItems}
+        </ScrollPane>
+    )
+}
+
+/**
+ * A highly performant virtual scroll component that supports variable item heights.
+ * Uses a Fenwick Tree (Binary Indexed Tree) for efficient offset calculation and range queries.
+ *
+ * 可変のアイテム高さをサポートする高性能な仮想スクロールコンポーネント。
+ * オフセット計算と範囲クエリを効率化するために Fenwick Tree (Binary Indexed Tree) を使用しています。
+ */
+export const VirtualScroll = forwardRef(VirtualScrollInner) as <T>(props: VirtualScrollProps<T> & { ref?: React.Ref<VirtualScrollHandle> }) => React.ReactElement