@aiquants/virtualscroll 1.18.5 → 1.19.1

package/src/useFenwickMapTree.ts

@@ -0,0 +1,1368 @@
+/**
+ * @file Fenwick Tree (Binary Indexed Tree) implementation and React hook.
+ * @file Fenwick Tree (Binary Indexed Tree) の実装と React フック。
+ *
+ * @module useFenwickMapTree
+ * @description This module provides a FenwickTree (Binary Indexed Tree) data structure
+ * and a React hook `useFenwickMapTree` to manage it.
+ * This is optimized for virtual scrolling scenarios with dynamically sized items.
+ *
+ * @description このモジュールは、FenwickTree (バイナリインデックスツリー) データ構造と、
+ * それを管理するための React フック `useFenwickMapTree` の提供。
+ * 動的なアイテムサイズを持つ仮想スクロールのシナリオに最適化されている。
+ */
+import { useRef } from "react"
+import { Logger } from "./logger.ts"
+import { minmax } from "./utils.ts"
+
+/**
+ * Maximum number of points evaluated when estimating `baseValue`, and the small/large-list
+ * threshold. Lists with more than this many items switch from head/sample-range sampling to a
+ * whole-list stride sample so a non-representative head cannot skew the total-height estimate.
+ *
+ * `baseValue` 推定で評価する最大点数であり、小/大リストの分岐しきい値でもある。これを超える
+ * リストは先頭/サンプル範囲サンプリングからリスト全体のストライドサンプリングへ切り替わり、
+ * 非代表的な先頭が総高さ推定を狂わせないようにする。
+ */
+const SAMPLE_COUNT = 100
+
+type MaterializeRange = { from: number; to: number }
+type MaterializeOption = { materialize: boolean; ranges?: MaterializeRange[] }
+type MaterializeConfig = { materializeOption?: MaterializeOption }
+type DeltaUpdate = { index: number; change: number }
+type ValueUpdate = { index: number; value: number }
+
+/**
+ * Converts a numeric size into a non-negative bigint, safeguarding against fractional input.
+ *
+ * 分数入力を安全に丸めてから非負の bigint へ変換。
+ */
+const toSafeBigInt = (value: number): bigint => {
+    if (!Number.isFinite(value)) {
+        return 0n
+    }
+    const truncated = Math.trunc(value)
+    if (truncated <= 0) {
+        return 0n
+    }
+    return BigInt(truncated)
+}
+
+/**
+ * Validates that `valueFn` returned a finite number, throwing otherwise. A single NaN/Infinity
+ * propagated into the tree poisons `tree`/`total` irrecoverably, so the materialization and
+ * sampling paths reject non-finite values up front, symmetric with the update-path validation.
+ *
+ * `valueFn` の返値が有限数であることの検証 (非有限なら throw)。NaN/Infinity は一度木へ伝播すると
+ * `tree`/`total` を復旧不能に汚染するため、update 系の検証と対称に具現化/サンプリング経路でも
+ * 前段で拒否する方針。
+ */
+const requireFiniteValue = (value: number, index: number): number => {
+    if (!Number.isFinite(value)) {
+        throw new Error(`valueFn returned a non-finite value at index ${index}: ${value}`)
+    }
+    return value
+}
+
+/**
+ * Tolerance used when rejecting delta changes that would make an effective value negative.
+ * Guards against false positives caused by floating-point dust (e.g. a fractional `baseValue`
+ * combined with a change targeting an exact-zero effective value).
+ *
+ * 実効値が負になる delta 変更を拒否する際の許容誤差。小数 `baseValue` と実効値 0 を狙う変更の
+ * 組合せ等で生じる浮動小数点の丸め屑による誤検出の防止。
+ */
+const NEGATIVE_EFFECTIVE_VALUE_EPSILON = 1e-9
+
+/**
+ * Derives the lowest set bit without relying on 32-bit bitwise operators.
+ *
+ * 32 ビット演算に依存せずに最下位ビットを算出。
+ */
+const getLowestSetBit = (value: number): number => {
+    if (value <= 0 || !Number.isFinite(value)) {
+        return 0
+    }
+    const integer = Math.trunc(value)
+    // 32 ビット符号付き整数の範囲内なら通常のビット演算で最下位ビットを求める (BigInt 割り当てを回避)。
+    // ホットパス (prefixSum / _updateTree など) の GC 圧を大幅に削減する。
+    if (integer <= 0x7fffffff) {
+        return integer & -integer
+    }
+    const lowestBit = BigInt(integer) & -BigInt(integer)
+    return Number(lowestBit)
+}
+
+/**
+ * @class FenwickTree
+ * @classdesc Implements a Fenwick Tree (or Binary Indexed Tree).
+ * This data structure efficiently calculates prefix sums and performs updates in logarithmic time.
+ * It is particularly useful for virtual scrolling, where it can manage the offsets of variably sized items.
+ *
+ * @classdesc Fenwick Tree (バイナリインデックスツリー) の実装。
+ * このデータ構造は、接頭辞和の計算と更新を対数時間で効率的に実行。
+ * 可変サイズのアイテムのオフセットを管理できるため、特に仮想スクロールで有用。
+ *
+ * @remarks Memory: exact offsets are the design priority, so every materialized/updated row keeps
+ * an entry in `tree` and `deltas`. Memory therefore grows with the number of materialized elements,
+ * not with `size`. Rows equal to `baseValue` are pruned (zero-delta), but there is no eviction of
+ * measured deltas — evicting one would silently snap that row back to the estimated `baseValue` and
+ * corrupt `total`, which is incompatible with the exact-offset guarantee. If a hard memory ceiling
+ * is required, discard off-screen measured heights in the consumer layer (e.g. an LRU height cache)
+ * and let those rows fall back to the estimate there, rather than inside this tree.
+ * @remarks メモリ: 厳密オフセットを設計上の最優先とするため、具現化/更新された行はすべて `tree` と
+ * `deltas` にエントリを保持する。よってメモリは `size` ではなく具現化済み要素数に比例して増える。
+ * `baseValue` と一致する行は zero-delta 枝刈りされるが、計測済み delta の evict は行わない。evict すると
+ * その行が黙って推定値 `baseValue` へ戻り `total` が破損し、厳密オフセット保証と両立しないためである。
+ * ハードなメモリ上限が必要な場合は、この木の内部ではなく消費側 (LRU 高さキャッシュ等) で可視域外の
+ * 実測値を破棄し、そこで既定推定へ委ねる設計とすること。
+ */
+export class FenwickMapTree {
+    /**
+     * @private
+     * @property {Map<number, number>} tree - The Map storing the Fenwick tree structure, specifically the sums of deltas. It is 1-indexed.
+     * @property {Map<number, number>} tree - Fenwick Tree 構造を格納する Map。特に差分の合計を保持する。1-indexed。
+     */
+    private tree!: Map<number, number>
+
+    /**
+     * @private
+     * @property {Map<number, number>} deltas - The Map storing the differences (deltas) from the base value at each index.
+     * @property {Map<number, number>} deltas - 各インデックスにおける基準値との差分 (delta) を格納する Map。
+     */
+    private deltas!: Map<number, number>
+
+    /**
+     * @private
+     * @property {number} size - The number of elements the tree manages.
+     * @property {number} size - ツリーが管理する要素数。
+     */
+    private size!: number
+
+    /**
+     * @private
+     * @property {number} baseValue - The uniform base value for all elements, used to optimize memory.
+     * @property {number} baseValue - 全要素の均一な基準値。メモリ最適化のために使用。
+     */
+    private baseValue!: number
+
+    /**
+     * @private
+     * @property {((index: number) => number) | undefined} valueFn - A function to generate values, stored for lazy initialization.
+     * @property {((index: number) => number) | undefined} valueFn - 値を生成するための関数。遅延初期化のために保存される。
+     */
+    private valueFn?: (index: number) => number
+    private total?: number
+
+    /**
+     * @constructor
+     * @description Initializes the Fenwick Tree.
+     * @description Fenwick Tree の初期化。
+     * @param {number} size - The total number of items.
+     * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
+     * @param {{ sampleRange?: { from: number; to: number }, materialize?: boolean }} [options] - Optional settings for initialization.
+     */
+    constructor(size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; materialize?: boolean }) {
+        this.reset(size, valueOrFn, options)
+    }
+
+    /**
+     * @method reset
+     * @description Resets the Fenwick Tree with a new size and initial values. The size is
+     * normalized on entry (non-finite/negative sizes collapse to 0, fractions are truncated).
+     * When `valueOrFn` is a function, all sampling/materialization values are computed and
+     * validated (finite-only) before the tree state is mutated, so a `valueFn` returning
+     * NaN/Infinity throws while leaving the previous tree state intact instead of a half-built one.
+     * @description Fenwick Tree を新しいサイズと初期値でリセット。size は入口で正規化する
+     * (非有限/負は 0 に縮退、小数は切り捨て)。`valueOrFn` が関数の場合、サンプリング/具現化の値は
+     * 木の状態を変異させる前に計算・検証 (有限数のみ) するため、NaN/Infinity を返す `valueFn` は
+     * throw しつつ木を半構築で残さず直前の状態を無傷に保つ方針。
+     * @param {number} size - The total number of items.
+     * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
+     * @param {{ sampleRange?: { from: number; to: number }, materialize?: boolean }} [options] - Optional settings for initialization.
+     */
+    reset(size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; materialize?: boolean }) {
+        // size を正規化する: 非有限 (NaN/Infinity)・非正は 0、小数は切り捨て。
+        // NaN size は `this.size > 0` 系の判定をすり抜けて total を NaN 汚染するため入口で遮断する。
+        const safeSize = Number.isFinite(size) && size > 0 ? Math.trunc(size) : 0
+
+        if (typeof valueOrFn !== "function") {
+            this.size = safeSize
+            this.tree = new Map()
+            this.deltas = new Map()
+            this.valueFn = undefined
+            this.baseValue = valueOrFn
+            this.total = this.baseValue * this.size
+            return
+        }
+
+        // --- 計算フェーズ (this を変異させない) ---
+        // valueFn が非有限値を返して throw しても、木は呼び出し前の状態のまま無傷に保つ
+        // (半構築状態を残さない)。検証済みの値だけを後段のコミットフェーズで木へ流し込む。
+        let baseValue = 0
+        let seed: { from: number; values: number[] } | undefined
+        if (safeSize > 0) {
+            // 初期可視ウィンドウ (= 具現化対象) の範囲を決定する。
+            // baseValue の推定範囲とは分離する: 具現化は利用者が最初に見る領域だけ正確化すればよいが、
+            // baseValue は未具現化の全アイテムの総高さ推定に効くため、リスト全体を代表する値が必要。
+            const range = options?.sampleRange ?? {
+                from: 0,
+                to: Math.min(SAMPLE_COUNT - 1, safeSize - 1),
+            }
+            // sampleRange は 0..size-1 にクランプ + 整数化してから使用する。負 index で valueFn を
+            // 呼ぶと undefined/NaN が返り baseValue が汚染され、小数はループ変数が非整数キーの
+            // ノードを生んで木を破損させるため。
+            let from = Math.max(0, Math.trunc(range.from))
+            let to = Math.min(Math.trunc(range.to), safeSize - 1)
+            // from > to の逆転指定はサンプルが空になり baseValue=0 / total=0 へ静かに縮退するため、
+            // 既定の先頭ウィンドウへフォールバックする。
+            if (from > to) {
+                from = 0
+                to = Math.min(SAMPLE_COUNT - 1, safeSize - 1)
+            }
+
+            if (safeSize > SAMPLE_COUNT) {
+                // 大きいリストでは baseValue をリスト全体にわたる分散 (ストライド) サンプリングで決める。
+                // 先頭固定サンプリングだと、先頭が非代表的な高さ (ヒーロー行/見出しなど) のとき
+                // 多数派の実際の高さではなくその外れ値が baseValue に選ばれ、未具現化アイテムの
+                // 総高さ・スクロールバー比率・scrollToIndex クランプが大きく狂う。
+                // For large lists, derive baseValue from a stride sample spanning the whole list so
+                // a non-representative head (hero/heading rows) cannot skew the majority estimate.
+                baseValue = FenwickMapTree._sampleBaseValueStrided(valueOrFn, safeSize, SAMPLE_COUNT)
+
+                // 具現化は従来どおり初期可視ウィンドウ (sampleRange) のみを対象にする (正確性を維持)。
+                if (options?.materialize) {
+                    seed = { from, values: FenwickMapTree._collectValidatedValues(valueOrFn, from, to) }
+                }
+            } else {
+                // 小さいリスト (size <= SAMPLE_COUNT) は分散サンプリングの利点が無いため、
+                // 従来どおり sampleRange の最頻値/中央値を baseValue とし、
+                // 生成済みの値を再利用して具現化する (valueFn の二重評価を回避)。
+                // For small lists, keep the original sample-range mode/median and value reuse.
+                const values = FenwickMapTree._collectValidatedValues(valueOrFn, from, to)
+                // _modeOrMedian はソートで配列を破壊するため、具現化用の並びはコピーで保護する
+                baseValue = FenwickMapTree._modeOrMedian([...values])
+                if (options?.materialize) {
+                    seed = { from, values }
+                }
+            }
+        }
+
+        // --- コミットフェーズ (検証済みの値のみで木を構築する) ---
+        this.size = safeSize
+        this.tree = new Map()
+        this.deltas = new Map()
+        this.total = undefined
+        this.valueFn = valueOrFn
+        this.baseValue = baseValue
+        if (seed) {
+            for (let i = 0; i < seed.values.length; i++) {
+                const index = seed.from + i
+                if (index >= this.size) {
+                    break
+                }
+                // _materialize を呼ぶ代わりに、計算フェーズの検証済みの値を使って更新する (二重評価を回避)
+                const change = seed.values[i] - this.baseValue
+                // baseValue と一致する行は delta を持たせない (Map の無駄な肥大を回避)
+                if (change !== 0) {
+                    this.deltas.set(index, change)
+                    this._updateTree(index, change)
+                }
+            }
+        }
+        // 具現化が完了した後に total を計算する
+        this.total = this.getTotal()
+    }
+
+    /**
+     * @method setValueFn
+     * @description Updates the value function and re-initializes the tree.
+     * @description 値関数を更新し、ツリーを再初期化する。
+     * @param {number | ((index: number) => number)} valueOrFn - The new value for all elements, or a function to generate values.
+     * @param {{ reset?: boolean }} [options] - Optional settings. If reset is true, the tree is reset with the new value function.
+     */
+    setValueFn(valueOrFn: number | ((index: number) => number), options?: { reset?: boolean }) {
+        if (options?.reset) {
+            this.reset(this.size, valueOrFn)
+            return
+        }
+
+        if (typeof valueOrFn === "function") {
+            this.valueFn = valueOrFn
+        } else {
+            // If a number is provided, it's treated as a new baseValue,
+            // and valueFn is cleared. This case effectively turns the tree
+            // into a uniform-value tree, but existing deltas are preserved.
+            this.valueFn = undefined
+            this.baseValue = valueOrFn
+            // baseValue を差し替えたら total を再計算しないと prefixSum と乖離する。
+            // (deltas は温存されるため sum(deltas) + baseValue * size に一致させる)
+            this.total = this._computeTreeTotal()
+        }
+    }
+
+    /**
+     * @private
+     * @method _collectValidatedValues
+     * @description Evaluates `valueFn` over the inclusive `[from, to]` range and returns the values, throwing on any non-finite result. Validation happens here, before any tree mutation, so a poisoned `valueFn` can never leave the tree half-built.
+     * @description `valueFn` を閉区間 `[from, to]` で評価して値配列を返す。非有限値は throw で拒否。検証を木の変異前 (このメソッド内) で行うことで、汚染された `valueFn` が木を半構築のまま残す事態の防止。
+     * @param {(index: number) => number} valueFn - The value-generating function to evaluate.
+     * @param {number} from - The starting index of the range (inclusive).
+     * @param {number} to - The ending index of the range (inclusive).
+     * @returns {number[]} The validated (finite-only) values in index order.
+     */
+    private static _collectValidatedValues(valueFn: (index: number) => number, from: number, to: number): number[] {
+        const values: number[] = []
+        for (let i = from; i <= to; i++) {
+            values.push(requireFiniteValue(valueFn(i), i))
+        }
+        return values
+    }
+
+    /**
+     * @private
+     * @method _modeOrMedian
+     * @description Reduces a sample of generated values to a single representative height: the mode when it is frequent enough to be trustworthy, otherwise the median. A value is only accepted as the mode when its frequency exceeds 20% of the sample; this prevents periodic or near-uniform data (where sampling bias can make an arbitrary value momentarily frequent) from picking an unrepresentative base. Multiple co-modes are averaged.
+     * @description サンプル値を 1 つの代表的な高さへ縮約する。信頼できるほど頻出する場合は最頻値を、そうでなければ中央値を返す。最頻値はサンプルの 20% を超える頻度のときのみ採用し、周期的/ほぼ一様なデータ (サンプリング偏りで任意の値が一時的に頻出しうる) が非代表値を選ぶのを防ぐ。同率最頻値が複数ある場合は平均する。
+     * @param {number[]} values - The sampled values (mutated in place by sorting).
+     * @returns {number} The representative base value.
+     */
+    private static _modeOrMedian(values: number[]): number {
+        if (values.length === 0) {
+            return 0
+        }
+
+        // 中央値を計算してデフォルトの最頻値として設定
+        values.sort((a, b) => a - b)
+        const mid = Math.floor(values.length / 2)
+        let mode: number
+        if (values.length % 2 === 0) {
+            // 偶数個の場合は中央2つの値の平均
+            mode = Math.floor((values[mid - 1] + values[mid]) / 2)
+        } else {
+            // 奇数個の場合は中央の値
+            mode = values[mid]
+        }
+
+        const frequencies = new Map<number, number>()
+        let maxFreq = 0
+
+        for (const value of values) {
+            const count = (frequencies.get(value) ?? 0) + 1
+            frequencies.set(value, count)
+            if (count > maxFreq) {
+                maxFreq = count
+            }
+        }
+
+        // 最頻値の出現頻度がサンプルサイズの 20% を超える場合のみ最頻値を採用する
+        // これにより、周期的なデータや一様分布に近いデータで、サンプリングの偏りによって
+        // 偶然頻度が高くなった値が採用されるのを防ぐ
+        if (maxFreq > values.length * 0.2) {
+            const modes: number[] = []
+            for (const [value, count] of frequencies.entries()) {
+                if (count === maxFreq) {
+                    modes.push(value)
+                }
+            }
+            const sum = modes.reduce((a, b) => a + b, 0)
+            mode = Math.floor(sum / modes.length)
+        }
+        return mode
+    }
+
+    /**
+     * @private
+     * @method _sampleBaseValueStrided
+     * @description Estimates `baseValue` by evaluating `valueFn` at up to `sampleCount` points spread across the entire `[0, size-1]` range, then reducing them via `_modeOrMedian`. Spanning the whole list (rather than a fixed head window) makes the majority height win even when the first items are atypical (hero/heading rows). The stride uses `ceil(size / sampleCount)` so the samples always span the whole range — `floor` would collapse to stride 1 for `sampleCount < size < 2 * sampleCount` and only ever look at the head. The stride is also forced odd to avoid aliasing against common even-period layouts (e.g. alternating or 20-row cycles), which a stride that shares a factor with the period would otherwise collapse into a single residue. For a uniform list every sample is identical, so the estimate is unchanged. Non-finite sample values throw before any state is touched.
+     * @description `valueFn` を `[0, size-1]` 全域に散らした最大 `sampleCount` 点で評価し、`_modeOrMedian` で縮約して `baseValue` を推定する。先頭固定ウィンドウではなくリスト全体を跨ぐことで、先頭が非典型 (ヒーロー/見出し行) でも多数派の高さが選ばれる。ストライドは `ceil(size / sampleCount)` を用いて常に全域を跨がせる (`floor` だと `sampleCount < size < 2 * sampleCount` で stride=1 に潰れ先頭しか見ない盲点が生じる)。さらに奇数へ強制し、周期と公約数を持つストライドがサンプルを 1 剰余類へ潰してしまう周期レイアウト (交互・20行周期など) とのエイリアシングを避ける。一様リストでは全サンプルが同一なので推定値は不変。非有限のサンプル値は状態を変異させる前に throw で拒否。
+     * @param {(index: number) => number} valueFn - The value-generating function to sample.
+     * @param {number} size - The total number of items the tree will manage.
+     * @param {number} sampleCount - Maximum number of points to evaluate.
+     * @returns {number} The estimated base value.
+     */
+    private static _sampleBaseValueStrided(valueFn: (index: number) => number, size: number, sampleCount: number): number {
+        if (size <= 0) {
+            return 0
+        }
+
+        // stride = max(1, ceil(size / sampleCount)) を基準に、偶数なら +1 して奇数化する。
+        // ceil によりサンプル数を多少犠牲にしても必ずリスト全域を跨ぐ (_modeOrMedian の
+        // 20% しきい値は割合ベースのためサンプル数減の影響は受けない)。
+        // (bigint を使わず大サイズでも安全に奇数化するため | 1 ではなく剰余で判定する)
+        let stride = Math.max(1, Math.ceil(size / sampleCount))
+        if (stride % 2 === 0) {
+            stride += 1
+        }
+
+        const values: number[] = []
+        for (let i = 0; i < size && values.length < sampleCount; i += stride) {
+            values.push(requireFiniteValue(valueFn(i), i))
+        }
+        return FenwickMapTree._modeOrMedian(values)
+    }
+
+    /**
+     * @method update
+     * @description Updates the value at a given index.
+     * @description 指定されたインデックスの値を更新。
+     * @param {number} index - The 0-based index to update.
+     * @param {number} value - The new value.
+     */
+    update(index: number, value: number): number | undefined {
+        return this.updates([{ index, value }])
+    }
+
+    /**
+     * @method updates
+     * @description Updates the values at given indices.
+     * @description 指定されたインデックスの値を更新。
+     * @param {ValueUpdate[]} updates - An array of updates, each with an index and the new value.
+     */
+    updates(updates: ValueUpdate[]): number | undefined {
+        const deltaUpdates = this._buildDeltaUpdates(updates)
+        if (deltaUpdates.length > 0) {
+            return this.updateDeltas(deltaUpdates)
+        }
+        return this.total
+    }
+
+    /**
+     * @method updateDelta
+     * @description Updates the delta at a given index and propagates the change through the tree. A change that would make the effective value (`baseValue` + delta) negative is rejected with an error, mirroring the negative-value rejection of `update`/`updates`.
+     * @description 指定されたインデックスのデルタを更新し、変更をツリーに伝播させる。適用後の実効値 (`baseValue` + delta) が負になる変更は `update`/`updates` の負値拒否と対称に throw で拒否する方針。
+     * @param {number} index - The 0-based index to update.
+     * @param {number} change - The value to add to the delta at the given index.
+     */
+    updateDelta(index: number, change: number): number | undefined {
+        return this.updateDeltas([{ index, change }])
+    }
+
+    /**
+     * @method updateDeltas
+     * @description Updates the deltas at given indices and propagates the changes through the tree. All entries are validated up front (atomicity): out-of-range or non-integer indices, non-finite changes, and changes whose resulting effective value (`baseValue` + delta) would turn negative are rejected with an error before anything is applied. Negative effective values would break the monotonic prefix sums that `_descend`/`_findIndexLarge` rely on.
+     * @description 指定されたインデックスのデルタを更新し、変更をツリーに伝播させる。全件を先に検証してから適用する (アトミック性): 範囲外/非整数の index、非有限の change、適用後の実効値 (`baseValue` + delta) が負になる変更はいずれも適用前に throw で拒否。負の実効値は `_descend`/`_findIndexLarge` が前提とする累積和の単調性を破壊するため。
+     * @param {DeltaUpdate[]} updates - An array of updates, each with an index and the change to apply.
+     */
+    updateDeltas(updates: DeltaUpdate[]): number | undefined {
+        // 先に全件を検証してから適用する (アトミック性の確保)。
+        // 途中に範囲外 index があっても先行分だけ適用された不整合状態にしない。
+        // 同一 index がバッチ内に複数含まれても累積後の実効値で判定できるよう、
+        // バッチ内の確定済み delta を index ごとに追跡する。
+        const pendingDeltas = new Map<number, number>()
+        for (const { index, change } of updates) {
+            if (index < 0 || index >= this.size) {
+                throw new Error(`Index ${index} out of bounds`)
+            }
+            // 小数/NaN の index は整数走査が読まない不正キーのノードを作り
+            // cumulative と total を静かに乖離させるため拒否する (NaN は上の範囲比較を素通りする)。
+            if (!Number.isInteger(index)) {
+                throw new Error(`Index must be an integer: ${index}`)
+            }
+            // NaN/Infinity は一度伝播すると tree/total 全体が復旧不能に汚染されるため、
+            // 適用前の検証段で拒否する (負値 throw と同じ扱い)。
+            if (!Number.isFinite(change)) {
+                throw new Error(`Change must be a finite number: ${change}`)
+            }
+            // 適用後の実効値 (baseValue + delta) が負になる変更は累積和の単調性を破り、
+            // _descend / _findIndexLarge の探索契約を壊すため拒否する
+            // (updates 経路の value < 0 拒否と対称。丸め屑の誤検出は許容誤差で回避)。
+            const currentDelta = pendingDeltas.get(index) ?? this.deltas.get(index) ?? 0
+            const nextDelta = currentDelta + change
+            if (nextDelta + this.baseValue < -NEGATIVE_EFFECTIVE_VALUE_EPSILON) {
+                throw new Error(`Change would make the value at index ${index} negative: ${nextDelta + this.baseValue}`)
+            }
+            pendingDeltas.set(index, nextDelta)
+        }
+
+        for (const { index, change } of updates) {
+            // deltas Map を更新
+            const currentDelta = this.deltas.get(index) ?? 0
+            const nextDelta = currentDelta + change
+            // 差分が 0 に戻る場合はエントリを保持しない (Map の無制限成長を抑制)。
+            // value(index) は baseValue と一致し、has(index)=false でも意味は変わらない。
+            if (nextDelta === 0) {
+                this.deltas.delete(index)
+            } else {
+                this.deltas.set(index, nextDelta)
+            }
+
+            // ツリーを更新
+            this._updateTree(index, change)
+        }
+
+        return this.total
+    }
+
+    /**
+     * @private
+     * @method _updateTree
+     * @description Updates the Fenwick tree and the total sum with a given change.
+     * @description Fenwick Tree と合計値を指定された変更で更新する。
+     * @param {number} index - The 0-based index that changed.
+     * @param {number} change - The change in value.
+     */
+    private _updateTree(index: number, change: number) {
+        if (change === 0) {
+            return
+        }
+        // tree Map を更新
+        let treeIndex = index + 1 // Fenwick Tree のアルゴリズムは 1 始まりで設計される
+        while (treeIndex <= this.size) {
+            this.tree.set(treeIndex, (this.tree.get(treeIndex) ?? 0) + change)
+            const step = getLowestSetBit(treeIndex)
+            if (step === 0) {
+                break
+            }
+            treeIndex += step
+        }
+
+        // 合計値を更新 (totalが計算済みの場合のみ)
+        if (this.total !== undefined) {
+            this.total += change
+        }
+    }
+
+    /**
+     * @private
+     * @method _buildDeltaUpdates
+     * @description Converts value updates into delta updates while preserving validation logic.
+     * @description 値更新入力を検証しつつデルタ更新へ変換する。
+     * @param {ValueUpdate[]} updates - Requested value updates.
+     * @returns {DeltaUpdate[]} Sanitized delta updates ready to apply.
+     */
+    private _buildDeltaUpdates(updates: ValueUpdate[]): DeltaUpdate[] {
+        const deltaUpdates: DeltaUpdate[] = []
+        // 同一 index が同一バッチ内に複数含まれても差分を二重適用しないよう、
+        // バッチ内での確定済み delta を index ごとに追跡する。
+        const pendingDeltas = new Map<number, number>()
+        for (const { index, value } of updates) {
+            if (index < 0 || index >= this.size) {
+                throw new Error(`Index ${index} out of bounds`)
+            }
+            // 小数/NaN の index は整数走査が読まない不正キーのノードを作り
+            // cumulative と total を静かに乖離させるため拒否する (NaN は上の範囲比較を素通りする)。
+            if (!Number.isInteger(index)) {
+                throw new Error(`Index must be an integer: ${index}`)
+            }
+            // NaN は `< 0` をすり抜けて tree/total を復旧不能に全面汚染するため、
+            // 非有限値 (NaN/Infinity) は検証段で throw して拒否する。
+            if (!Number.isFinite(value)) {
+                throw new Error(`Value must be a finite number: ${value}`)
+            }
+            if (value < 0) {
+                throw new Error("Value cannot be negative.")
+            }
+
+            // 現在の delta はバッチ内で既に更新済みならその値を、なければ Map の値を使う
+            const currentDelta = pendingDeltas.has(index) ? (pendingDeltas.get(index) ?? 0) : (this.deltas.get(index) ?? 0)
+            const oldValue = currentDelta + this.baseValue
+            const change = value - oldValue
+            if (change !== 0) {
+                deltaUpdates.push({ index, change })
+            }
+            // 次の同一 index エントリのために確定 delta を進める (change=0 でも記録)
+            pendingDeltas.set(index, currentDelta + change)
+        }
+        return deltaUpdates
+    }
+
+    /**
+     * @private
+     * @method _computeTreeTotal
+     * @description Calculates the total height represented by the current Fenwick tree structure, reproducing the same traversal used by `prefixSum` at the last index to avoid floating-point drift.
+     * @description Fenwick 木が保持する合計値を算出する。末尾インデックスでの `prefixSum` と同一の走査手順を再現し、浮動小数点の誤差を防ぐ。
+     * @returns {number} The total height encoded in the Fenwick tree.
+     */
+    private _computeTreeTotal(): number {
+        if (this.size <= 0) {
+            return 0
+        }
+
+        let sum = 0
+        let treeIndex = this.size
+        while (treeIndex > 0) {
+            sum += this.tree.get(treeIndex) ?? 0
+            const step = getLowestSetBit(treeIndex)
+            if (step === 0) {
+                break
+            }
+            treeIndex -= step
+        }
+
+        return sum + this.baseValue * this.size
+    }
+
+    /**
+     * @private
+     * @method _materialize
+     * @description Materializes the value at a specific index if it hasn't been already. A non-finite `valueFn` result throws before any mutation, symmetric with the update-path validation, so the tree is never poisoned.
+     * @description 特定のインデックスの値がまだ具現化されていない場合に具現化する。`valueFn` の非有限な返値は変異前に throw で拒否 (update 系の検証と対称) し、木を汚染させない方針。
+     * @param {number} index - The 0-based index to materialize.
+     * @param {boolean} [updateTree=true] - Whether to update the Fenwick tree after materialization.
+     */
+    private _materialize(index: number, updateTree = true) {
+        if (this.valueFn) {
+            // 1. 現在の差分を取得する (存在しなければ 0)
+            const oldDelta = this.deltas.get(index) ?? 0
+
+            // 2. valueFn から本来の値を計算し、新しい差分を求める。
+            //    非有限値は一度伝播すると tree/total 全体が復旧不能に汚染されるため、
+            //    deltas/tree を変異させる前に throw で拒否する (update 系と対称)。
+            const value = requireFiniteValue(this.valueFn(index), index)
+            const newDelta = value - this.baseValue
+
+            // 3. 差分が実際に変わった場合のみ、ツリーを更新する
+            if (newDelta !== oldDelta) {
+                // baseValue と一致する行は delta を保持しない (Map の無制限成長を抑制)
+                if (newDelta === 0) {
+                    this.deltas.delete(index)
+                } else {
+                    this.deltas.set(index, newDelta)
+                }
+                if (updateTree) {
+                    // ツリーに反映すべき差分は「新しい差分」と「古い差分」の間の差
+                    const changeForTree = newDelta - oldDelta
+                    this._updateTree(index, changeForTree)
+                }
+            }
+        }
+    }
+
+    /**
+     * @private
+     * @method _materializeRanges
+     * @description Materializes values for provided ranges and optionally a target index, keeping existing semantics for each caller.
+     * @description 指定された範囲とターゲットインデックスを既存仕様通りに具現化する。
+     * @param {MaterializeOption | undefined} option - Materialization option wrapper.
+     * @param {number | undefined} index - Target index for materialization.
+     * @param {boolean} [forceIndex=false] - When true, materializes the index even if it is outside the provided ranges.
+     */
+    private _materializeRanges(option?: MaterializeOption, index?: number, forceIndex = false) {
+        if (!(option?.materialize && this.valueFn)) {
+            return
+        }
+
+        const ranges = option.ranges
+        if (ranges && ranges.length > 0) {
+            for (const range of ranges) {
+                // from も 0 側にクランプする。負インデックスを具現化すると
+                // deltas に不正なキーが入り total が恒久的に破損するのを防ぐ。
+                // 小数はループ変数が非整数キーのノードを生むため切り捨てて整数化する。
+                const from = Math.max(0, Math.trunc(range.from))
+                const to = Math.min(Math.trunc(range.to), this.size - 1)
+                for (let i = from; i <= to; i++) {
+                    this._materialize(i)
+                }
+            }
+
+            if (index === undefined) {
+                return
+            }
+
+            if (forceIndex) {
+                this._materialize(index)
+                return
+            }
+
+            const first = ranges[0].from
+            const last = ranges[ranges.length - 1].to
+            if (index >= first && index <= last) {
+                this._materialize(index)
+            }
+            return
+        }
+
+        if (index !== undefined) {
+            this._materialize(index)
+        }
+    }
+
+    /**
+     * @private
+     * @method _findIndex
+     * @description Executes a binary search over prefix sums to find the first index satisfying a boundary condition.
+     * @description 累積和に対する二分探索を行い、境界条件を満たす最初のインデックスを求める。
+     * @param {number} target - Target cumulative value.
+     * @param {MaterializeConfig} options - Materialization setting wrapper.
+     * @param {boolean} chooseLowerBound - When true, finds the smallest index meeting or exceeding the target; otherwise finds the largest index not exceeding it.
+     * @returns {{ index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined }} Binary search result.
+     */
+    private _findIndex(target: number, options: MaterializeConfig = {}, chooseLowerBound: boolean): { index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined } {
+        // JSのビット演算子は32ビット整数に制限されています。
+        // bit の倍加 (bit << 1) は 2^30 に達すると Int32 オーバーフローで負値へ化け、
+        // 条件が常に真になって無限ループする。そのため size が 2^30 以上のときは
+        // bigint ベースの二分探索 (_findIndexLarge) に委譲する。 (0x40000000 = 2^30)
+        if (this.size >= 0x40000000) {
+            return this._findIndexLarge(target, options, chooseLowerBound)
+        }
+        if (this.size === 0) {
+            return { index: -1, total: this.total ?? 0, cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+        }
+
+        // 探索前に対象範囲を具現化しておく。具現化後のツリー状態で降下を行うことで、
+        // 返す index と後段 prefixSum の cumulative が同一状態を反映し、
+        // 同一引数の連続呼び出しでも結果がぶれないようにする (_findIndexLarge と挙動を揃える)。
+        this._materializeRanges(options.materializeOption)
+
+        // materialize:true の契約: 返す index/cumulative は「その index が具現化済みの木」を
+        // 反映しなければならない。降下後に結果 index を具現化すると木が変わり、返した
+        // cumulative が古い状態のまま (契約違反) になり、同一引数の再呼び出しで結果が
+        // ドリフトする。そこで「降下 -> 結果 index を具現化 -> 木が変わったら再降下」を
+        // 不動点に達するまで繰り返す。決定的な valueFn なら各行の具現化は 1 度しか木を
+        // 変えないため、ループは必ず停止する。
+        const materialize = options.materializeOption?.materialize === true
+        let resultIdx: number
+        for (;;) {
+            resultIdx = this._descend(target, chooseLowerBound)
+
+            if (resultIdx < 0 || resultIdx >= this.size) {
+                return { index: -1, total: this.total ?? this.getTotal(), cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+            }
+
+            if (!materialize) {
+                break
+            }
+
+            // 結果 index を具現化し、delta が変化しなければ結果は安定している
+            const deltaBefore = this.deltas.get(resultIdx) ?? 0
+            this._materialize(resultIdx)
+            if ((this.deltas.get(resultIdx) ?? 0) === deltaBefore) {
+                break
+            }
+        }
+
+        // Retrieve full details for the found index.
+        // options を渡さない: 探索後の prefixSum 内部での強制具現化 (forceIndex) による
+        // 木の変異を防ぐ (必要な具現化は上のループで完了済み)。
+        const result = this.prefixSum(resultIdx)
+
+        return {
+            index: resultIdx,
+            total: this.total ?? result.total,
+            cumulative: result.cumulative,
+            currentValue: result.currentValue,
+            safeIndex: result.safeIndex,
+        }
+    }
+
+    /**
+     * @private
+     * @method _descend
+     * @description Performs a single bitwise descent over the current tree state, returning the candidate index for the boundary condition without mutating the tree.
+     * @description 現在の木の状態に対してビット降下を 1 回実行し、木を変異させずに境界条件の候補インデックスを返す。
+     * @param {number} target - Target cumulative value.
+     * @param {boolean} chooseLowerBound - When true, finds the smallest index meeting or exceeding the target; otherwise finds the largest index not exceeding it.
+     * @returns {number} The candidate index (may be out of range when no index satisfies the condition).
+     */
+    private _descend(target: number, chooseLowerBound: boolean): number {
+        // Optimization: Use bitwise descent (O(log N)) instead of binary search over prefixSum (O(log^2 N))
+        // This assumes non-negative values (monotonic prefix sums).
+
+        let currentIdx = 0
+        let currentSum = 0
+
+        // Find the highest power of 2 less than or equal to size
+        let bit = 1
+        while (bit << 1 <= this.size) {
+            bit <<= 1
+        }
+
+        for (; bit > 0; bit >>= 1) {
+            const nextIdx = currentIdx + bit
+            if (nextIdx <= this.size) {
+                const treeValue = this.tree.get(nextIdx) ?? 0
+                const val = treeValue + this.baseValue * bit
+
+                const check = chooseLowerBound ? currentSum + val < target : currentSum + val <= target
+
+                if (check) {
+                    currentIdx = nextIdx
+                    currentSum += val
+                }
+            }
+        }
+
+        return chooseLowerBound ? currentIdx : currentIdx - 1
+    }
+
+    /**
+     * Executes a binary search using bigint arithmetic for extremely large sizes.
+     *
+     * 非常に大きなサイズに対して bigint 演算を用いた二分探索を実施。
+     */
+    private _findIndexLarge(target: number, options: MaterializeConfig, chooseLowerBound: boolean): { index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined } {
+        if (this.size === 0) {
+            return { index: -1, total: this.total ?? 0, cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+        }
+
+        const sizeBig = toSafeBigInt(this.size)
+        if (sizeBig === 0n) {
+            return { index: -1, total: this.total ?? 0, cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+        }
+
+        // 小サイズパス (_findIndex) と同一契約: 探索前に対象範囲を具現化し、探索中は木を
+        // 変異させない (prefixSum に options を渡さない)。materialize:true の場合は
+        // 「探索 -> 結果 index を具現化 -> 木が変わったら再探索」を不動点まで繰り返す。
+        this._materializeRanges(options.materializeOption)
+        const materialize = options.materializeOption?.materialize === true
+
+        for (;;) {
+            let low = 0n
+            let high = sizeBig - 1n
+            let resolvedIndex: bigint | undefined
+            let bestResult: { cumulative: number; total: number | undefined; currentValue: number; safeIndex: number } | undefined
+            let finalTotal = this.total
+
+            while (low <= high) {
+                const mid = (low + high) >> 1n
+                const midNumber = Number(mid)
+                const result = this.prefixSum(midNumber)
+                finalTotal = result.total
+                const meetsCondition = chooseLowerBound ? result.cumulative >= target : result.cumulative <= target
+                if (meetsCondition) {
+                    resolvedIndex = mid
+                    bestResult = result
+                    if (chooseLowerBound) {
+                        if (mid === 0n) {
+                            break
+                        }
+                        high = mid - 1n
+                    } else {
+                        low = mid + 1n
+                    }
+                } else if (chooseLowerBound) {
+                    low = mid + 1n
+                } else {
+                    if (mid === 0n) {
+                        break
+                    }
+                    high = mid - 1n
+                }
+            }
+
+            // 未発見時 (bestResult なし) は小サイズパス (_findIndex) と同一契約で
+            // cumulative/currentValue/safeIndex を undefined にする。lastResult へフォールバック
+            // すると無関係な最終プローブ位置の値が載り、AtOrBefore の未発見時に
+            // cumulative > target のような契約矛盾の値を返してしまうため。
+            const chosenResult = bestResult
+            const indexNumber = resolvedIndex !== undefined ? Number(resolvedIndex) : -1
+
+            if (materialize && indexNumber >= 0) {
+                // 結果 index を具現化し、木が変化した場合のみ再探索する
+                const deltaBefore = this.deltas.get(indexNumber) ?? 0
+                this._materialize(indexNumber)
+                if ((this.deltas.get(indexNumber) ?? 0) !== deltaBefore) {
+                    continue
+                }
+            }
+
+            return {
+                index: indexNumber,
+                total: finalTotal,
+                cumulative: chosenResult?.cumulative,
+                currentValue: chosenResult?.currentValue,
+                safeIndex: chosenResult?.safeIndex,
+            }
+        }
+    }
+
+    /**
+     * @method prefixSum
+     * @description Calculates the cumulative sum up to a given index (inclusive) in O(log n) time.
+     * @description 指定されたインデックスまでの累積和を O(log n) で計算。
+     * @param {number} index - The 0-based index to prefixSum up to.
+     * @param {MaterializeConfig} [options] - Optional settings for materializing values.
+     * @returns {{ cumulative: number; total: number | undefined; currentValue: number; safeIndex: number }} The cumulative sum of values from index 0 to the given index, the total sum, and the value at the given index.
+     */
+    prefixSum(index: number, options?: MaterializeConfig): { cumulative: number; total: number | undefined; currentValue: number; safeIndex: number } {
+        // NaN index は minmax を素通りして NaN キーの具現化 (木の汚染) を招くため、
+        // 負 index と同じ中立値へ縮退させる。
+        if (index < 0 || Number.isNaN(index)) {
+            return { cumulative: 0, total: this.total, currentValue: 0, safeIndex: 0 }
+        }
+        // 空の木 (size=0) は正当な状態として中立値を返す (throw しない)。
+        // minmax(index, 0, -1) が負値へ丸められ get(-1) が throw するのを回避する。
+        if (this.size === 0) {
+            return { cumulative: 0, total: this.total ?? 0, currentValue: 0, safeIndex: 0 }
+        }
+        // 小数 index は具現化時に非整数キーのノードを作り整数走査と乖離するため切り捨てる
+        // (Infinity は trunc を素通りした後 minmax で size-1 にクランプされる)。
+        const safeIndex = minmax(Math.trunc(index), 0, this.size - 1)
+
+        const materializeOption = options?.materializeOption
+        this._materializeRanges(materializeOption, safeIndex, true)
+
+        let sum = 0
+        let treeIndex = safeIndex + 1 // Fenwick Tree のアルゴリズムは 1 始まりで設計される
+        while (treeIndex > 0) {
+            const treeNodeValue = this.tree.get(treeIndex) ?? 0
+            sum += treeNodeValue
+            const step = getLowestSetBit(treeIndex)
+            if (step === 0) {
+                break
+            }
+            treeIndex -= step
+        }
+
+        const currentValue = materializeOption?.materialize ? this.get(safeIndex) : (this.deltas.get(safeIndex) || 0) + this.baseValue
+
+        // ベース値に基づく合計を加算
+        return { cumulative: sum + this.baseValue * (safeIndex + 1), total: this.total, currentValue, safeIndex }
+    }
+
+    /**
+     * @method get
+     * @description Gets the value at a specific index.
+     * @description 特定のインデックスの値を取得。
+     * @param {number} index - The 0-based index to get.
+     * @param {MaterializeConfig} [options] - Optional settings for materializing values.
+     * @returns {number} The value at the given index.
+     */
+    get(index: number, options?: MaterializeConfig): number {
+        // 空の木 (size=0) は正当な状態として中立値 0 を返す (throw しない)。
+        if (this.size === 0) {
+            return 0
+        }
+        // 小数/NaN の index は具現化時に非整数キーのノードを作り total を静かに汚染するため、
+        // 範囲外と同様に throw で拒否する (NaN は範囲比較を素通りする)。
+        if (!Number.isInteger(index) || index < 0 || index >= this.size) {
+            throw new Error("Index out of bounds")
+        }
+
+        const materializeOption = options?.materializeOption
+        this._materializeRanges(materializeOption, index)
+
+        return (this.deltas.get(index) ?? 0) + this.baseValue
+    }
+
+    /**
+     * @method getTotal
+     * @description Gets the total sum of all values in the tree.
+     * @description ツリー内のすべての値の合計を取得。
+     * @param {MaterializeConfig} [options] - Optional settings for materializing values.
+     * @returns {number} The total sum of all values.
+     */
+    getTotal(options?: MaterializeConfig): number {
+        const materializeOption = options?.materializeOption
+        this._materializeRanges(materializeOption)
+
+        if (this.total === undefined) {
+            if (this.size === 0) {
+                this.total = 0
+            } else {
+                this.total = this._computeTreeTotal()
+                const lastPrefix = this.prefixSum(this.getSize() - 1)
+                if (lastPrefix.cumulative !== lastPrefix.total) {
+                    Logger.error("Inconsistent Fenwick Tree state")
+                }
+            }
+        }
+
+        return this.total
+    }
+
+    /**
+     * @method rebuildTree
+     * @description Rebuilds the Fenwick Tree from the existing `baseValue` and `deltas`. This corrects any discrepancies in the tree's internal state, such as those caused by floating-point errors, by recalculating the tree structure and the total sum from the source `deltas`. This method does not re-materialize values from `valueFn`.
+     * @description 既存の `baseValue` と `deltas` から Fenwick Tree を再構築します。これにより、`deltas` からツリー構造と合計値を再計算することで、浮動小数点誤差などによって生じた内部状態の不一致を修正します。このメソッドは `valueFn` から値を再具現化しません。
+     * @param {object} [options] - Optional settings for rebuilding.
+     * @param {boolean} [options.materialize=false] - If true and `valueFn` is provided, re-materializes all values, recalculating `deltas` and `baseValue`.
+     */
+    rebuildTree(options?: { materialize?: boolean }) {
+        if (options?.materialize && this.valueFn) {
+            // すべての値を具現化する
+            const valueFn = this.valueFn
+            this.reset(this.size, (i) => valueFn(i), { materialize: true })
+            return
+        }
+
+        const newTree = new Map<number, number>()
+        // let newTotal = this.baseValue * this.size
+
+        // 既存の deltas を使って新しいツリーを構築し、合計値も同時に再計算する
+        for (const [index, delta] of this.deltas.entries()) {
+            if (delta === 0) {
+                continue
+            }
+            // Fenwick Tree のアルゴリズムは 1 始まりで設計されるため、インデックスを 1 加算する
+            let treeIndex = index + 1
+            while (treeIndex <= this.size) {
+                newTree.set(treeIndex, (newTree.get(treeIndex) ?? 0) + delta)
+                const step = getLowestSetBit(treeIndex)
+                if (step === 0) {
+                    break
+                }
+                treeIndex += step
+            }
+        }
+
+        // 最後に状態をアトミックに更新
+        this.tree = newTree
+        this.total = this._computeTreeTotal()
+    }
+
+    /**
+     * @method calculateAccumulatedError
+     * @description Compares the cached total sum with a theoretical total calculated directly from the source values (`deltas` and `baseValue`, or `valueFn`). This helps detect any discrepancy in the tree's cached state, which might be caused by floating-point errors or other inconsistencies.
+     * @description キャッシュされている合計値と、元の値 (`deltas` と `baseValue`、または `valueFn`) から直接計算した理論上の合計値とを比較します。これにより、浮動小数点数の累積誤差やその他の不整合によって生じる可能性のある、ツリーのキャッシュ状態の不一致を検出できます。
+     * @returns {number} The difference between the cached total and the theoretical total.
+     */
+    calculateAccumulatedError(): number {
+        if (this.total === undefined) {
+            // total がまだ計算されていない場合は、誤差は 0 とする
+            return 0
+        }
+
+        // 理論上の合計値を計算
+        let theoreticalTotal = this.baseValue * this.size
+        for (const delta of this.deltas.values()) {
+            theoreticalTotal += delta
+        }
+
+        // キャッシュされている合計値との差を返す
+        return this.total - theoreticalTotal
+    }
+
+    /**
+     * @method changeSize
+     * @description Changes the size of the Fenwick Tree. Only tail growth/shrink is modelled: this
+     * method receives a size delta, not an index mapping, so it assumes items are appended to or
+     * removed from the tail. Existing rows keep their index-to-height association. It therefore
+     * cannot represent a middle insertion/deletion — after such a structural change the index↔height
+     * mapping is no longer preserved and the tree's deltas would apply to the wrong rows. Consumers
+     * that insert or remove items in the middle must instead reset the tree (see
+     * `useFenwickMapTree`'s `resetOnValueFnChange`, surfaced as `resetOnGetItemHeightChange` in
+     * VirtualScroll) or remount the component with a new `key`.
+     * @description Fenwick Tree のサイズを変更する。モデル化するのは末尾の伸長/縮小のみ: 本メソッドは
+     * サイズ差分のみを受け取りインデックスの対応表は受け取らないため、要素は末尾に追加/末尾から削除
+     * されると仮定する。既存行は index↔高さ の対応を保つ。したがって中間挿入/削除は表現できず、その
+     * ような構造変更の後は index↔高さ の対応が保存されず、木の delta が誤った行へ適用されてしまう。
+     * 中間で要素を挿入/削除する消費側は、代わりに木をリセットするか (`useFenwickMapTree` の
+     * `resetOnValueFnChange`。VirtualScroll では `resetOnGetItemHeightChange` として公開) 、新しい
+     * `key` でコンポーネントを再マウントすること。
+     * @remarks Validation: a non-finite `newSize` (NaN/Infinity) throws because it would poison
+     * `size`/`total` irrecoverably. Fractional sizes are truncated and negative sizes collapse to 0,
+     * matching the normalization rule of `reset`.
+     * @remarks 検証: 非有限の `newSize` (NaN/Infinity) は `size`/`total` を復旧不能に汚染するため
+     * throw。小数は切り捨て、負値は 0 に縮退 (`reset` の正規化規則と同一)。
+     * @param {number} newSize - The new size of the tree.
+     */
+    changeSize(newSize: number) {
+        // 非有限 (NaN/Infinity) は size/total を復旧不能に汚染するため入口で拒否する。
+        if (!Number.isFinite(newSize)) {
+            throw new Error(`Size must be a finite number: ${newSize}`)
+        }
+        // 小数は切り捨て、負値は 0 として末尾伸縮を扱う (reset の正規化と同じ規則)。
+        const targetSize = Math.max(0, Math.trunc(newSize))
+        const oldSize = this.size
+        if (targetSize === oldSize) {
+            // サイズが変わらない場合は何もしない
+            return
+        }
+
+        if (targetSize > oldSize) {
+            // 末尾への伸長は増分更新で済ませる (全再構築 O(D log n) を回避)。
+            // 既存ノード (treeIndex <= oldSize) は不変であり、新規要素は delta 0 なので、
+            // oldSize で伝播が止まっていた既存 delta を新たに有効化されたノード
+            // (oldSize, targetSize] にのみ伝播すればよい。
+            this._growSize(oldSize, targetSize)
+        } else {
+            // サイズが小さくなる場合、範囲外の delta を削除してからツリーを再構築する
+            for (const index of this.deltas.keys()) {
+                if (index >= targetSize) {
+                    this.deltas.delete(index)
+                }
+            }
+            this.size = targetSize
+            this.rebuildTree()
+        }
+
+        const lastPrefix = this.prefixSum(this.getSize() - 1)
+        if (lastPrefix.cumulative !== lastPrefix.total) {
+            Logger.error("Inconsistent Fenwick Tree state")
+        }
+    }
+
+    /**
+     * @private
+     * @method _minCoveredLowBound
+     * @description Computes `min(t - lowestSetBit(t))` over the newly-activated node range `t in (oldSize, newSize]`. Any delta whose 1-based tree index is at or below this bound cannot be covered by any newly-activated node and can be skipped during an incremental grow.
+     * @description 新規有効化ノード範囲 `t in (oldSize, newSize]` にわたる `min(t - lowestSetBit(t))` を算出する。1 始まりの木インデックスがこの下限以下の delta はどの新規ノードにも覆われないため、増分伸長時にスキップできる。
+     * @param {number} oldSize - The previous size (exclusive lower bound of the new node range).
+     * @param {number} newSize - The new size (inclusive upper bound of the new node range).
+     * @returns {number} The minimum left boundary `t - lowestSetBit(t)` of the newly-activated nodes.
+     */
+    private static _minCoveredLowBound(oldSize: number, newSize: number): number {
+        // ノード t が覆う区間は (t - lsb(t), t]。min(t - lsb(t)) は
+        // 「(oldSize, newSize] に倍数を持つ最大の 2 冪 p」を使うと閉形式で求まる:
+        // 範囲内の p の倍数はいずれも lsb がちょうど p (2p の倍数が範囲に在れば p の最大性に反する)
+        // なので、最小の倍数 m = p * (floor(oldSize / p) + 1) が min を与え、
+        // m - p = p * floor(oldSize / p) となる。
+        // 2 冪の乗除は仮数を変えないため 2^53 未満の整数では丸め誤差なし。
+        let power = 1
+        for (;;) {
+            const next = power * 2
+            // (oldSize, newSize] に next の倍数が存在するか (最大の倍数 > oldSize と同値)
+            if (Math.floor(newSize / next) * next <= oldSize) {
+                break
+            }
+            power = next
+        }
+        return power * Math.floor(oldSize / power)
+    }
+
+    /**
+     * @private
+     * @method _propagateDeltaToGrownNodes
+     * @description Propagates a single delta into the tree nodes newly activated by a tail growth, i.e. parent-chain nodes in `(oldSize, newSize]`.
+     * @description 末尾伸長で新規有効化されたノード ((oldSize, newSize] にある親チェーンノード) へ単一 delta を伝播する。
+     * @param {number} index - The 0-based delta index.
+     * @param {number} delta - The delta value to propagate.
+     * @param {number} oldSize - The previous size.
+     * @param {number} newSize - The new (larger) size.
+     */
+    private _propagateDeltaToGrownNodes(index: number, delta: number, oldSize: number, newSize: number) {
+        let treeIndex = index + 1
+        // 既存範囲 (<= oldSize) のノードは更新済みなので、
+        // 親チェーンを辿って oldSize を超える最初のノードまで進める。
+        while (treeIndex <= oldSize) {
+            const step = getLowestSetBit(treeIndex)
+            if (step === 0) {
+                break
+            }
+            treeIndex += step
+        }
+        // 新たに有効化されたノード (oldSize, newSize] にのみ差分を伝播する。
+        while (treeIndex <= newSize) {
+            this.tree.set(treeIndex, (this.tree.get(treeIndex) ?? 0) + delta)
+            const step = getLowestSetBit(treeIndex)
+            if (step === 0) {
+                break
+            }
+            treeIndex += step
+        }
+    }
+
+    /**
+     * @private
+     * @method _growSize
+     * @description Extends the tree to a larger size incrementally, propagating existing deltas into newly-activated higher-order tree nodes only. Candidate deltas are narrowed via `_minCoveredLowBound`, so a typical `+1` tail append costs amortized O(log n) instead of O(D log n) (D = number of materialized deltas).
+     * @description ツリーを末尾方向に増分的に拡張する。既存 delta を新たに有効化された上位ノードにのみ伝播する。候補 delta は `_minCoveredLowBound` で絞り込むため、通常の +1 末尾追記は O(D log n) (D = 具現化済み delta 数) ではなく償却 O(log n) で済む。
+     * @param {number} oldSize - The previous size.
+     * @param {number} newSize - The new (larger) size.
+     */
+    private _growSize(oldSize: number, newSize: number) {
+        this.size = newSize
+
+        if (this.deltas.size > 0) {
+            // 影響し得る delta は木インデックス (index + 1) が lowBound を超えるものだけ。
+            // 既存 delta の index は必ず oldSize 未満なので、候補は index in [lowBound, oldSize)。
+            const lowBound = FenwickMapTree._minCoveredLowBound(oldSize, newSize)
+            const candidateCount = oldSize - lowBound
+            if (candidateCount < this.deltas.size) {
+                // 候補範囲の方が狭い (+1 追記の通常ケース): index を直接ループして deltas から拾う。
+                for (let index = lowBound; index < oldSize; index++) {
+                    const delta = this.deltas.get(index)
+                    if (delta === undefined || delta === 0) {
+                        continue
+                    }
+                    this._propagateDeltaToGrownNodes(index, delta, oldSize, newSize)
+                }
+            } else {
+                // delta 件数の方が少ない (大幅伸長など): 従来どおり全 deltas を走査し、
+                // lowBound 以下の木インデックスを持つものは除外する。
+                for (const [index, delta] of this.deltas.entries()) {
+                    if (delta === 0 || index < lowBound) {
+                        continue
+                    }
+                    this._propagateDeltaToGrownNodes(index, delta, oldSize, newSize)
+                }
+            }
+        }
+
+        // total は増分 (+= baseValue * Δ) ではなく prefixSum と同一走査を再現する
+        // _computeTreeTotal で確定する。増分加算は浮動小数点の分配則不成立により
+        // prefixSum の走査結果と厳密不一致になり、changeSize 末尾の整合検査が
+        // 偽の "Inconsistent Fenwick Tree state" を量産するため。O(log n) なので
+        // 増分更新の速度メリットは保たれる。
+        this.total = this._computeTreeTotal()
+    }
+
+    /**
+     * @method getSize
+     * @description Gets the size of the tree.
+     * @description ツリーのサイズを取得。
+     * @returns {number} The total number of items.
+     */
+    getSize(): number {
+        return this.size
+    }
+
+    /**
+     * @method findIndexAtOrAfter
+     * @description Finds the first index where the cumulative sum is greater than or equal to a target value.
+     * @description 累積和がターゲット値以上になる最初のインデックスを検索。
+     * @param {number} target - The target cumulative sum.
+     * @param {MaterializeConfig} [options] - Optional settings for materializing values.
+     * @param {MaterializeOption} [options.materializeOption] - Options to control materialization.
+     * @param {boolean} [options.materializeOption.materialize=false] - Whether to materialize values.
+     * @param {MaterializeRange[]} [options.materializeOption.ranges] - Optional ranges for eager materialization.
+     * @returns {{ index: number, total: number | undefined, cumulative: number | undefined, currentValue: number | undefined, safeIndex: number | undefined }} The 0-based index and the total sum, or -1 if not found.
+     */
+    findIndexAtOrAfter(target: number, options?: MaterializeConfig): { index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined } {
+        return this._findIndex(target, options ?? {}, true)
+    }
+
+    /**
+     * @method findIndexAtOrBefore
+     * @description Finds the last index where the cumulative sum is less than or equal to a target value.
+     * @description 累積和がターゲット値以下になる最後のインデックスを検索。
+     * @param {number} target - The target cumulative sum.
+     * @param {MaterializeConfig} [options] - Optional settings for materializing values.
+     * @param {MaterializeOption} [options.materializeOption] - Options to control materialization。
+     * @param {boolean} [options.materializeOption.materialize=false] - Whether to materialize values。
+     * @param {MaterializeRange[]} [options.materializeOption.ranges] - Optional ranges for eager materialization。
+     * @returns {{ index: number, total: number | undefined, cumulative: number | undefined, currentValue: number | undefined, safeIndex: number | undefined }} The 0-based index and the total sum, or -1 if not found.
+     */
+    findIndexAtOrBefore(target: number, options?: MaterializeConfig): { index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined } {
+        return this._findIndex(target, options ?? {}, false)
+    }
+}
+
+/**
+ * Determines whether the tree-relevant part of the options (only `sampleRange` affects
+ * tree initialization/sampling) actually changed. Compares by value rather than by
+ * reference so that non-memoized inline option objects with an equivalent `sampleRange`
+ * do not trigger a destructive full reset every render.
+ *
+ * ツリー初期化に影響するオプション (`sampleRange` のみ) が実質的に変わったかを値比較で判定する。
+ * 参照比較ではなくすることで、非メモ化のインライン options でも sampleRange が同一なら
+ * 毎レンダーの破壊的な full reset を起こさない。
+ */
+const sampleRangeChanged = (a?: { sampleRange?: { from: number; to: number } }, b?: { sampleRange?: { from: number; to: number } }): boolean => {
+    const ra = a?.sampleRange
+    const rb = b?.sampleRange
+    if (ra === rb) {
+        return false
+    }
+    if (!(ra && rb)) {
+        return true
+    }
+    return ra.from !== rb.from || ra.to !== rb.to
+}
+
+/**
+ * @hook useFenwickMapTree
+ * @description A React hook that creates and manages a `FenwickMapTree` instance.
+ * The tree instance is stable across re-renders. A new tree instance is created
+ * if `size` or `valueOrFn` changes.
+ * @description `FenwickMapTree` インスタンスを作成・管理する React フック。
+ * ツリーインスタンスは再レンダリングされても同一性を維持する。`size` または `valueOrFn` が
+ * 変更された場合に新しいインスタンスが作成される。
+ *
+ * @remarks Structural changes: `size` changes are treated as tail append/remove (see
+ * `FenwickMapTree.changeSize`). If a `size`/`itemCount` change actually reflects a middle
+ * insertion or deletion, the `valueOrFn` index↔height association is not preserved by an
+ * incremental resize; set `resetOnValueFnChange` to `true` (so the tree fully re-samples on
+ * every `valueOrFn` change) or remount with a new `key` when the list structure changes.
+ * @remarks 構造変更: `size` 変更は末尾追加/削除として扱う (`FenwickMapTree.changeSize` 参照)。
+ * `size`/`itemCount` の変更が実は中間挿入/削除を表す場合、増分リサイズでは `valueOrFn` の
+ * index↔高さ 対応が保存されないため、`resetOnValueFnChange` を `true` にする (毎回の `valueOrFn`
+ * 変更で木を全面再サンプリング) か、リスト構造変更時に新しい `key` で再マウントすること。
+ *
+ * @remarks Render-phase design constraint: this hook applies tree changes synchronously during
+ * render (not in an effect) because VirtualScroll reads `getTotal()` synchronously right after a
+ * size change. A consequence is that React concurrent's discarded renders are not undone — a
+ * shrink (deltas deletion) is irreversible if the render is thrown away. To stay safe, always pass
+ * a memoized `options`/`sampleRange` (e.g. `useMemo`) and a memoized `valueOrFn` (e.g. `useCallback`)
+ * so an unstable reference does not trigger a destructive reset every render.
+ * @remarks render フェーズの設計上の制約: 本フックはツリー変更を effect ではなく render 中に同期的に
+ * 適用する。VirtualScroll がサイズ変更直後に `getTotal()` を同期的に読む契約に依存するためである。
+ * 結果として React concurrent の破棄されたレンダーは巻き戻されず、縮小 (deltas 削除) はレンダーが
+ * 破棄されると不可逆になる。安全のため `options`/`sampleRange` は必ずメモ化して渡し (`useMemo`)、
+ * `valueOrFn` もメモ化する (`useCallback`) こと。不安定な参照は毎レンダーの破壊的 reset を招く。
+ *
+ * @param {number} size - The total number of items.
+ * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
+ * @param {number | ((index: number) => number)} valueOrFn - 全要素の均一な値、または値を生成する関数。不要なツリーの再作成を防ぐため、この関数は `useCallback` でメモ化すること。
+ * @param {{ sampleRange?: { from: number; to: number }, resetOnValueFnChange?: boolean, debug?: boolean }} [options] - Optional settings.
+ * @param {{ sampleRange?: { from: number; to: number } }} [options] - 初期化時のオプション設定。不要なツリーの再作成を防ぐため、このオブジェクトは `useMemo` でメモ化すること。
+ * @returns {FenwickMapTree} The FenwickMapTree instance.
+ * @returns {FenwickMapTree} FenwickMapTree インスタンス。
+ */
+export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; debug?: boolean; resetOnValueFnChange?: boolean }): FenwickMapTree => {
+    // size を正規化する: 非有限 (NaN は Math.max(0, NaN) を素通りする)・非正は 0、小数は切り捨て。
+    // reset / changeSize へ渡る前にここで遮断し、木の内部を NaN 汚染させない (reset と同一規則)。
+    const validSize = Number.isFinite(size) && size > 0 ? Math.trunc(size) : 0
+    const treeRef = useRef<FenwickMapTree | null>(null)
+    const prevPropsRef = useRef({ size: validSize, valueOrFn, options })
+
+    if (treeRef.current === null) {
+        treeRef.current = new FenwickMapTree(validSize, valueOrFn, options)
+    }
+
+    const tree = treeRef.current
+    const prev = prevPropsRef.current
+
+    // Detect changes
+    const sizeChanged = prev.size !== validSize
+    const valueOrFnChanged = prev.valueOrFn !== valueOrFn
+    // options は参照比較ではなく sampleRange の値で比較する。
+    // 非メモ化のインライン options でも sampleRange が同一なら reset を起こさない
+    // (計測済み delta を毎レンダーで破棄しないため)。
+    const optionsChanged = sampleRangeChanged(prev.options, options)
+
+    // 旧 size が 0 の木は baseValue が未確立 (0) のまま。増分伸長 (changeSize) では
+    // total = 0 * N = 0 で固着するため、0 -> N の伸長は resetOnValueFnChange の設定に
+    // 関わらず常に reset (サンプリング込み) へ倒す。sizeChanged のみの分岐と前提を統一する。
+    const growingFromZero = prev.size === 0 && validSize > 0
+
+    if (valueOrFnChanged || optionsChanged) {
+        const resetRequested = options?.resetOnValueFnChange ?? true
+        // If options changed, we essentially must reset because options control initialization behavior (sampling, etc).
+        // If only valueOrFn changed, we respect the flag.
+        // Growing from size 0 must always reset (baseValue was never established).
+        const shouldReset = optionsChanged || (valueOrFnChanged && resetRequested) || growingFromZero
+
+        if (shouldReset) {
+            // Full reset if fundamental properties change
+            if (options?.debug) {
+                Logger.debug("[useFenwickMapTree] reset", { valueOrFnChanged, optionsChanged })
+            }
+            tree.reset(validSize, valueOrFn, options)
+        } else {
+            // valueFn changed but reset is disabled
+            // If size also changed, we need to apply resize before setting the new valueFn
+            if (sizeChanged) {
+                if (options?.debug) {
+                    Logger.debug("[useFenwickMapTree] resize (with valueFn change)", { from: prev.size, to: validSize })
+                }
+                tree.changeSize(validSize)
+            }
+
+            if (options?.debug) {
+                Logger.debug("[useFenwickMapTree] setValueFn (no reset)", { valueOrFnChanged })
+            }
+            tree.setValueFn(valueOrFn, { reset: false })
+        }
+        prevPropsRef.current = { size: validSize, valueOrFn, options }
+    } else if (sizeChanged) {
+        // Resize optimization if only size changes
+        if (options?.debug) {
+            Logger.debug("[useFenwickMapTree] resize", { from: prev.size, to: validSize })
+        }
+
+        if (growingFromZero) {
+            // When growing from 0, baseValue is likely 0 (default).
+            // We must reset to correctly initialize baseValue via sampling the new valueFn results.
+            tree.reset(validSize, valueOrFn, options)
+        } else {
+            tree.changeSize(validSize)
+        }
+
+        prevPropsRef.current = { size: validSize, valueOrFn, options }
+    }
+
+    return tree
+}