@aiquants/virtualscroll 3.9.2 → 3.11.0

package/src/labels.ts

@@ -1,14 +1,16 @@
 /**
  * @module labels
- * @description Built-in UI chrome label catalog of the package. Covers exactly the seven strings
- * the components render on their own: the ScrollBar arrow aria-labels, the VirtualScroll
+ * @description Built-in UI chrome label catalog of the package. Covers exactly the eleven strings
+ * the components render on their own: the ScrollBar accessible names (per orientation, the two
+ * arrows, the `role="scrollbar"` bar and its `role="slider"` thumb), the VirtualScroll
  * scroll-to-edge pill texts and the empty-state text. Live-region wording stays consumer-owned
  * (`liveRegion.format` / `liveRegion.buildMessage`) and is not part of this catalog. The default
  * locale is `"en"`; `"ja"` is the second locale. No language negotiation happens here: hosts map
  * `navigator.language` (or anything else) to a supported locale themselves.
  *
- * @description パッケージ内蔵の UI クローム文言カタログ。コンポーネント自身が描画する 7 文言
- * (ScrollBar 矢印の aria-label、VirtualScroll の端スクロールピル文言、空状態文言) だけを対象とし、
+ * @description パッケージ内蔵の UI クローム文言カタログ。コンポーネント自身が描画する 11 文言
+ * (向きごとの ScrollBar のアクセシブルネーム — 矢印 2 個・`role="scrollbar"` のバー・その `role="slider"` の
+ * つまみ —、VirtualScroll の端スクロールピル文言、空状態文言) だけを対象とし、
  * ライブリージョンの文言は利用側の所有 (`liveRegion.format` / `liveRegion.buildMessage`) で
  * 本カタログの対象外。既定ロケールは `"en"`、第 2 ロケールは `"ja"`。言語ネゴシエーションは行わず、
  * `navigator.language` 等から対応ロケールへの対応付けはホスト側の責務。
@@ -53,6 +55,30 @@ export type VirtualScrollLabels = {
      * 横 ScrollBar 終端 (右) 矢印ボタンの aria-label。
      */
     readonly scrollRight: string
+    /**
+     * aria-label of the vertical ScrollBar root (`role="scrollbar"`). Assistive technology appends
+     * the role ("scroll bar") itself, so the name carries only what tells the two bars apart.
+     * 縦 ScrollBar のルート (`role="scrollbar"`) の aria-label。ロール名 (スクロールバー) は支援技術が
+     * 付け足すため、名前は 2 本のバーを区別する情報のみ。
+     */
+    readonly verticalScrollBar: string
+    /**
+     * aria-label of the horizontal ScrollBar root (`role="scrollbar"`).
+     * 横 ScrollBar のルート (`role="scrollbar"`) の aria-label。
+     */
+    readonly horizontalScrollBar: string
+    /**
+     * aria-label of the vertical ScrollBar thumb (`role="slider"`), whose value is the scroll
+     * position.
+     * 縦 ScrollBar のつまみ (`role="slider"`) の aria-label。値はスクロール位置。
+     */
+    readonly verticalScrollThumb: string
+    /**
+     * aria-label of the horizontal ScrollBar thumb (`role="slider"`), whose value is the scroll
+     * position.
+     * 横 ScrollBar のつまみ (`role="slider"`) の aria-label。値はスクロール位置。
+     */
+    readonly horizontalScrollThumb: string
     /**
      * Text of the VirtualScroll scroll-to-top pill, shown when
      * `scrollBarOptions.enableScrollToTopBottomButtons` is on.
@@ -87,15 +113,32 @@ export type VirtualScrollLabelOverrides = { readonly [K in keyof VirtualScrollLa
  * overrides are validated against.
  * {@link VirtualScrollLabels} の全キー (カタログ順)。上書き検証に用いる閉じたキー集合。
  */
-export const VIRTUAL_SCROLL_LABEL_KEYS = ["scrollUp", "scrollDown", "scrollLeft", "scrollRight", "scrollToTop", "scrollToBottom", "noItems"] as const satisfies readonly (keyof VirtualScrollLabels)[]
+export const VIRTUAL_SCROLL_LABEL_KEYS = [
+    "scrollUp",
+    "scrollDown",
+    "scrollLeft",
+    "scrollRight",
+    "verticalScrollBar",
+    "horizontalScrollBar",
+    "verticalScrollThumb",
+    "horizontalScrollThumb",
+    "scrollToTop",
+    "scrollToBottom",
+    "noItems",
+] as const satisfies readonly (keyof VirtualScrollLabels)[]
 
 // satisfies は部分集合しか保証しないため、キー追加時の登録漏れを型で検出する
 const keysCoverEveryLabel: [Exclude<keyof VirtualScrollLabels, (typeof VIRTUAL_SCROLL_LABEL_KEYS)[number]>] extends [never] ? true : never = true
 void keysCoverEveryLabel
 
 /**
- * Frozen built-in catalogs per locale. `en` is the package's historical English wording.
- * ロケールごとの凍結済み内蔵カタログ。`en` はパッケージ従来の英語文言。
+ * Frozen built-in catalogs per locale. The arrow, pill and empty-state values of `en` are the
+ * package's historical English wording. The bar names state only the orientation, because
+ * assistive technology already reads the role as "scroll bar"; the thumb names state what the
+ * value measures.
+ * ロケールごとの凍結済み内蔵カタログ。`en` の矢印・ピル・空状態の値はパッケージ従来の英語文言。
+ * バーの名前は向きのみ (支援技術がロールを既に「スクロールバー」と読むため)、つまみの名前は値が
+ * 表すもの。
  */
 export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale, VirtualScrollLabels>> = Object.freeze({
     en: Object.freeze({
@@ -103,6 +146,10 @@ export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale,
         scrollDown: "Scroll down",
         scrollLeft: "Scroll left",
         scrollRight: "Scroll right",
+        verticalScrollBar: "Vertical",
+        horizontalScrollBar: "Horizontal",
+        verticalScrollThumb: "Vertical scroll position",
+        horizontalScrollThumb: "Horizontal scroll position",
         scrollToTop: "Top",
         scrollToBottom: "Bottom",
         noItems: "No items",
@@ -112,6 +159,10 @@ export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale,
         scrollDown: "下へスクロール",
         scrollLeft: "左へスクロール",
         scrollRight: "右へスクロール",
+        verticalScrollBar: "縦方向",
+        horizontalScrollBar: "横方向",
+        verticalScrollThumb: "縦スクロール位置",
+        horizontalScrollThumb: "横スクロール位置",
         scrollToTop: "先頭へ",
         scrollToBottom: "末尾へ",
         noItems: "項目がありません",

package/src/logger.ts

@@ -47,7 +47,7 @@ export interface ILogger {
  */
 export class Logger implements ILogger {
     private level: LogLevel
-    private prefix: string
+    private readonly prefix: string
     private impl: ILogger
 
     /**
@@ -104,26 +104,6 @@ export class Logger implements ILogger {
         this.impl = impl
     }
 
-    /**
-     * @method setPrefix
-     * @description Updates the log prefix for the static instance.
-     * @description 静的インスタンスのログのプレフィックスを更新します。
-     * @param {string} prefix - The new prefix.
-     */
-    static setPrefix(prefix: string): void {
-        Logger.instance.setPrefix(prefix)
-    }
-
-    /**
-     * @method setPrefix
-     * @description Updates the log prefix.
-     * @description ログのプレフィックスを更新します。
-     * @param {string} prefix - The new prefix.
-     */
-    setPrefix(prefix: string): void {
-        this.prefix = prefix
-    }
-
     /**
      * @method isEnabled
      * @description Returns whether the given level would be emitted at the current level (static instance).
@@ -197,10 +177,6 @@ export class Logger implements ILogger {
         }
     }
 
-    static info(message?: unknown, ...optionalParams: unknown[]): void {
-        Logger.instance.info(message, ...optionalParams)
-    }
-
     info(message?: unknown, ...optionalParams: unknown[]): void {
         if (this.level <= LogLevel.INFO) {
             this.impl.info(...this.formatMessage(Logger.resolveLazy(message)), ...optionalParams.map(Logger.resolveLazy))

package/src/styles/virtualscroll.css

@@ -329,6 +329,22 @@
   width: 100%;
 }
 
+/* 行ラッパーの包含ブロックで、配置の境界 (Chromium の relayout boundary)。窓をずらす 1 段が行を足し引きしても、配置はこの箱から
+ * 始まって箱の中で終わり、文書の根まで遡らない。境界になるには flex の子でも grid の子でもないことが要る (ペインの中身は flex の子
+ * なので、ラッパーの包含ブロックにしても境界にならない)。この箱は位置指定と、大きさと配置の封じ込めで境界になる。
+ * 箱はペインの中身のパディングの辺に付いて幅を合わせ、高さは 0 に固定する: 行は箱の外へはみ出して描かれ (描画は封じ込めないので、
+ * 切り取りはペインの中身の overflow: hidden のまま)、箱は当たり判定で背景 (background) の前に立たない。行のはみ出しは封じ込めで
+ * インクのはみ出しになるので、ペインの中身のスクロールできる範囲にも数えない。そのため、ブラウザが自分で行を見せるスクロール
+ * (オーバースキャンの行の中への Tab・ページ内検索) はペインの中身を動かせず、行の箱が外側のスクローラーの外にあればそちらを動かす */
+.aqvs-items-boundary {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  height: 0;
+  contain: size layout style;
+}
+
 .aqvs-items-wrapper {
   position: absolute;
   width: 100%;
@@ -547,15 +563,47 @@
   transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
 }
 
-/* パッケージ全域・単一所有者 — 本 CSS 初の forced-colors 規則: グラデーション視覚は
- * forced-colors で平坦化され、輪郭なしではサークルが不可視になる (描画モード修正 —
- * 単体サークルにも輪郭が付くのは登記済みの挙動非変更デルタ)。 */
+/* 強制配色 (forced-colors: active) では、ブラウザがシステム色でない地色をどれも Canvas に置き換える (透明度は残す)。地色だけで
+ * 描く部品 (文字色も枠線も輪郭も持たない部品) は周りと区別できなくなるので、どれもここでシステム色の描き方を持つ
+ * (forcedColors.spec.tsx がこのファイルから地色だけで描く部品を導いて照合する)。
+ * - タップスクロールサークル: グラデーションの視覚は平坦になるので、輪郭で形を残す。
+ * - バーとトラック: 縁を GrayText の輪郭で描く (バーは矢印とトラックの下地、トラックはつまみが動く範囲)。
+ * - つまみ: ネイティブのスクロールバーと同じくシステム色で塗る。状態の規則 (ホバー・ドラッグ・無効) は同じ選択子でここに
+ *   言い直す: 詳細度が同じなので、後に置いたこちらが勝つ。forced-color-adjust: none はホストが塗ったシステム色でない地色を
+ *   Canvas へ消させない (つまみが溝と同じ色になって消えない)。
+ * - サンプルのビジュアルの光と棒: 引いた向きと量を示すので CanvasText で塗る。 */
 @media (forced-colors: active) {
   .aqvs-tap-scroll-circle {
     outline: 1px solid CanvasText;
     outline-offset: -1px;
     border-radius: 50%;
   }
+
+  .aqvs-scrollbar,
+  .aqvs-scrollbar-track {
+    outline: 1px solid GrayText;
+    outline-offset: -1px;
+  }
+
+  .aqvs-scrollbar-thumb {
+    forced-color-adjust: none;
+    background-color: CanvasText;
+  }
+
+  .aqvs-scrollbar-thumb[data-thumb-state="hover"],
+  .aqvs-scrollbar-thumb[data-thumb-state="dragging"] {
+    background-color: Highlight;
+  }
+
+  .aqvs-scrollbar-thumb[data-thumb-state="disabled"] {
+    background-color: GrayText;
+  }
+
+  .aqvs-sample-visual-highlight,
+  .aqvs-sample-visual-rod {
+    forced-color-adjust: none;
+    background-color: CanvasText;
+  }
 }
 
 /* 動きを減らす設定 (prefers-reduced-motion: reduce) では、パッケージが動かす部品はどれも遷移もアニメーションも持たず、

package/src/useFenwickMapTree.ts

@@ -32,22 +32,6 @@ 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
@@ -75,14 +59,17 @@ const requireFiniteValue = (value: number, index: number): number => {
 const NEGATIVE_EFFECTIVE_VALUE_EPSILON = 1e-9
 
 /**
- * Derives the lowest set bit without relying on 32-bit bitwise operators.
+ * Derives the lowest set bit of a 1-based tree index (a positive integer) without relying on 32-bit bitwise operators. Every
+ * caller walks the tree from such an index, so the result is at least 1 and each walk ends: a walk up adds it until the index
+ * passes the size, a walk down subtracts it until the index reaches 0.
+ *
+ * 1 始まりの木の添字 (正の整数) の最下位ビットを、32 ビット演算に依存せずに求める処理。呼び出し元はどれもそのような添字から木を
+ * 辿るので、結果は 1 以上で、どの辿り方も終わる (上へ辿ると足して添字が要素数を越え、下へ辿ると引いて添字が 0 に着く)。
  *
- * 32 ビット演算に依存せずに最下位ビットを算出。
+ * @param value - A 1-based tree index (a positive integer) / 1 始まりの木の添字 (正の整数)
+ * @returns The lowest set bit (1 or more) / 最下位ビット (1 以上)
  */
 const getLowestSetBit = (value: number): number => {
-    if (value <= 0 || !Number.isFinite(value)) {
-        return 0
-    }
     const integer = Math.trunc(value)
     // 32 ビット符号付き整数の範囲内なら通常のビット演算で最下位ビットを求める (BigInt 割り当てを回避)。
     // ホットパス (prefixSum / _updateTree など) の GC 圧を大幅に削減する。
@@ -154,6 +141,13 @@ export class FenwickMapTree {
     private valueFn?: (index: number) => number
     private total?: number
 
+    /**
+     * @private
+     * @property {number} revisionCount - The counter behind `revision`: raised by every change of a stored value or of the size.
+     * @property {number} revisionCount - `revision` の元の数。保持する値か要素数が変わるたびに上がる。
+     */
+    private revisionCount = 0
+
     /**
      * @constructor
      * @description Initializes the Fenwick Tree.
@@ -193,6 +187,7 @@ export class FenwickMapTree {
             this.valueFn = undefined
             this.baseValue = valueOrFn
             this.total = this.baseValue * this.size
+            this.revisionCount += 1
             return
         }
 
@@ -276,11 +271,9 @@ export class FenwickMapTree {
         this.valueFn = valueOrFn
         this.baseValue = baseValue
         if (seed) {
+            // 種は [from, to] (to < size) の値なので、添字は要素数を越えない
             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 の無駄な肥大を回避)
@@ -292,6 +285,7 @@ export class FenwickMapTree {
         }
         // 具現化が完了した後に total を計算する
         this.total = this.getTotal()
+        this.revisionCount += 1
     }
 
     /**
@@ -318,6 +312,7 @@ export class FenwickMapTree {
             // baseValue を差し替えたら total を再計算しないと prefixSum と乖離する。
             // (deltas は温存されるため sum(deltas) + baseValue * size に一致させる)
             this.total = this._computeTreeTotal()
+            this.revisionCount += 1
         }
     }
 
@@ -348,10 +343,6 @@ export class FenwickMapTree {
      * @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)
@@ -402,10 +393,6 @@ export class FenwickMapTree {
      * @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% しきい値は割合ベースのためサンプル数減の影響は受けない)。
@@ -526,15 +513,12 @@ export class FenwickMapTree {
         if (change === 0) {
             return
         }
+        this.revisionCount += 1
         // 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
+            treeIndex += getLowestSetBit(treeIndex)
         }
 
         // 合計値を更新 (totalが計算済みの場合のみ)
@@ -575,7 +559,8 @@ export class FenwickMapTree {
             }
 
             // 現在の delta はバッチ内で既に更新済みならその値を、なければ Map の値を使う
-            const currentDelta = pendingDeltas.has(index) ? (pendingDeltas.get(index) ?? 0) : (this.deltas.get(index) ?? 0)
+            const pendingDelta = pendingDeltas.get(index)
+            const currentDelta = pendingDelta === undefined ? (this.deltas.get(index) ?? 0) : pendingDelta
             const oldValue = currentDelta + this.baseValue
             const change = value - oldValue
             if (change !== 0) {
@@ -603,11 +588,7 @@ export class FenwickMapTree {
         let treeIndex = this.size
         while (treeIndex > 0) {
             sum += this.tree.get(treeIndex) ?? 0
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex -= step
+            treeIndex -= getLowestSetBit(treeIndex)
         }
 
         return sum + this.baseValue * this.size
@@ -717,7 +698,7 @@ export class FenwickMapTree {
             return this._findIndexLarge(target, options, chooseLowerBound)
         }
         if (this.size === 0) {
-            return { index: -1, total: this.total ?? 0, cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+            return { index: -1, total: this.getTotal(), cumulative: undefined, currentValue: undefined, safeIndex: undefined }
         }
 
         // 探索前に対象範囲を具現化しておく。具現化後のツリー状態で降下を行うことで、
@@ -737,7 +718,7 @@ export class FenwickMapTree {
             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 }
+                return { index: -1, total: this.getTotal(), cumulative: undefined, currentValue: undefined, safeIndex: undefined }
             }
 
             if (!materialize) {
@@ -759,7 +740,7 @@ export class FenwickMapTree {
 
         return {
             index: resultIdx,
-            total: this.total ?? result.total,
+            total: this.getTotal(),
             cumulative: result.cumulative,
             currentValue: result.currentValue,
             safeIndex: result.safeIndex,
@@ -812,14 +793,8 @@ export class FenwickMapTree {
      * 非常に大きなサイズに対して 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) は要素数 2^30 以上のときだけここへ来るので、要素数は正の整数
+        const sizeBig = BigInt(this.size)
 
         // 小サイズパス (_findIndex) と同一契約: 探索前に対象範囲を具現化し、探索中は木を
         // 変異させない (prefixSum に options を渡さない)。materialize:true の場合は
@@ -904,7 +879,7 @@ export class FenwickMapTree {
         // 空の木 (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 }
+            return { cumulative: 0, total: this.getTotal(), currentValue: 0, safeIndex: 0 }
         }
         // 小数 index は具現化時に非整数キーのノードを作り整数走査と乖離するため切り捨てる
         // (Infinity は trunc を素通りした後 minmax で size-1 にクランプされる)。
@@ -918,11 +893,7 @@ export class FenwickMapTree {
         while (treeIndex > 0) {
             const treeNodeValue = this.tree.get(treeIndex) ?? 0
             sum += treeNodeValue
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex -= step
+            treeIndex -= getLowestSetBit(treeIndex)
         }
 
         const currentValue = materializeOption?.materialize ? this.get(safeIndex) : (this.deltas.get(safeIndex) || 0) + this.baseValue
@@ -972,10 +943,6 @@ export class FenwickMapTree {
                 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")
-                }
             }
         }
 
@@ -987,11 +954,11 @@ export class FenwickMapTree {
      * @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`.
+     * @param {boolean} [options.materialize=false] - If true and `valueFn` is set, rebuilds from `valueFn` instead: a reset with materialization (`reset(size, valueFn, { materialize: true })`) that re-samples `baseValue`, materializes the initial window (rows 0 to `SAMPLE_COUNT - 1`) and discards every other measured delta. A tree with a uniform value (no `valueFn`) rebuilds from its deltas either way. / true かつ `valueFn` があれば、代わりに `valueFn` から作り直す。具現化付きのリセット (`reset(size, valueFn, { materialize: true })`) で、`baseValue` を標本で決め直し、初期の窓 (行 0〜`SAMPLE_COUNT - 1`) を具現化し、ほかの測った差分はすべて捨てる。一様な値の木 (`valueFn` 無し) はどちらでも差分から作り直す。
      */
     rebuildTree(options?: { materialize?: boolean }) {
         if (options?.materialize && this.valueFn) {
-            // すべての値を具現化する
+            // 全行の具現化は巨大な木で O(n) の valueFn 呼び出しになるので、リセットと同じく初期の窓だけを具現化する
             const valueFn = this.valueFn
             this.reset(this.size, (i) => valueFn(i), { materialize: true })
             return
@@ -1001,25 +968,21 @@ export class FenwickMapTree {
         // let newTotal = this.baseValue * this.size
 
         // 既存の deltas を使って新しいツリーを構築し、合計値も同時に再計算する
+        // 0 の delta は保持しない (zero-delta 枝刈り) ので、どの delta も木へ伝える
         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
+                treeIndex += getLowestSetBit(treeIndex)
             }
         }
 
         // 最後に状態をアトミックに更新
         this.tree = newTree
         this.total = this._computeTreeTotal()
+        // 値は変えないが、浮動小数点の誤差を直した接頭辞和は変わり得る
+        this.revisionCount += 1
     }
 
     /**
@@ -1034,11 +997,6 @@ export class FenwickMapTree {
      * @returns {number} The difference between the cached total and the theoretical total.
      */
     calculateAccumulatedError(): number {
-        if (this.total === undefined) {
-            // total がまだ計算されていない場合は、誤差は 0 とする
-            return 0
-        }
-
         // 理論上の合計値を計算する。範囲外へ退避している delta は木に載っていないので数えない
         let theoreticalTotal = this.baseValue * this.size
         for (const [index, delta] of this.deltas) {
@@ -1048,7 +1006,7 @@ export class FenwickMapTree {
         }
 
         // キャッシュされている合計値との差を返す
-        return this.total - theoreticalTotal
+        return this.getTotal() - theoreticalTotal
     }
 
     /**
@@ -1140,11 +1098,7 @@ export class FenwickMapTree {
             this.size = targetSize
             this.rebuildTree()
         }
-
-        const lastPrefix = this.prefixSum(this.getSize() - 1)
-        if (lastPrefix.cumulative !== lastPrefix.total) {
-            Logger.error("Inconsistent Fenwick Tree state")
-        }
+        this.revisionCount += 1
     }
 
     /**
@@ -1190,20 +1144,12 @@ export class FenwickMapTree {
         // 既存範囲 (<= oldSize) のノードは更新済みなので、
         // 親チェーンを辿って oldSize を超える最初のノードまで進める。
         while (treeIndex <= oldSize) {
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex += step
+            treeIndex += getLowestSetBit(treeIndex)
         }
         // 新たに有効化されたノード (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
+            treeIndex += getLowestSetBit(treeIndex)
         }
     }
 
@@ -1246,9 +1192,8 @@ export class FenwickMapTree {
 
         // total は増分 (+= baseValue * Δ) ではなく prefixSum と同一走査を再現する
         // _computeTreeTotal で確定する。増分加算は浮動小数点の分配則不成立により
-        // prefixSum の走査結果と厳密不一致になり、changeSize 末尾の整合検査が
-        // 偽の "Inconsistent Fenwick Tree state" を量産するため。O(log n) なので
-        // 増分更新の速度メリットは保たれる。
+        // prefixSum(size - 1) の走査結果と厳密には一致せず、末尾の位置で total と
+        // 最後の行の下端が食い違うため。O(log n) なので増分更新の速度メリットは保たれる。
         this.total = this._computeTreeTotal()
     }
 
@@ -1291,6 +1236,23 @@ export class FenwickMapTree {
         return this.baseValue
     }
 
+    /**
+     * @description Gets the tree's revision: a counter that rises whenever a value the tree stores or its size changes — an
+     * update, a materialization that changes a row, a reset, a resize, a new uniform value or a rebuild — and stays the same
+     * otherwise (reads, a materialization that finds the stored value, an update to the same value, a resize to the same size).
+     * The tree keeps its identity while its contents change, so a caller that derives anything from the prefix sums (row tops,
+     * a rendering range) compares two reads: equal reads mean nothing it derived became stale in between. The counter only
+     * rises; how far it rises per change is unspecified.
+     * @description 木の版を取得。木が保持する値か要素数が変わるたび (更新・行を変える具現化・リセット・要素数の変更・一様な値の
+     * 差し替え・再構築) に上がり、それ以外 (読み取り・保持する値と同じ値を見つけた具現化・同じ値への更新・同じ要素数への変更) では
+     * 変わらない数。木は中身が変わっても同一性を保つため、接頭辞和から何か (行の上端・描画範囲) を導く呼び出し側は 2 回の読み取りを
+     * 比べ、等しければその間に導いたものは古くなっていない。数は上がるだけで、1 回の変化でいくつ上がるかは決めない。
+     * @returns {number} The revision. 版。
+     */
+    get revision(): number {
+        return this.revisionCount
+    }
+
     /**
      * @method findIndexAtOrAfter
      * @description Finds the first index where the cumulative sum is greater than or equal to a target value.

package/src/useLruCache.ts

@@ -90,6 +90,16 @@ class DoublyLinkedList<K, V> {
         node.next = null
     }
 
+    /**
+     * @method peekHead
+     * @description Returns the head of the list (the least recently used item) without removing it.
+     * @description リストの先頭 (最も最近使用されていないアイテム) を外さずに返します。
+     * @returns {DoublyLinkedListNode<K, V> | null} The head node, or null if the list is empty.
+     */
+    peekHead(): DoublyLinkedListNode<K, V> | null {
+        return this.head
+    }
+
     /**
      * @method removeHead
      * @description Removes and returns the head of the list, which is the least recently used item.
@@ -176,14 +186,10 @@ export function useLruCache<K, V>(capacity: number) {
         if (!Number.isFinite(normalizedCapacity)) {
             return
         }
-        while (cache.current.size > normalizedCapacity) {
-            const lruNode = list.current.removeHead()
-            if (lruNode) {
-                cache.current.delete(lruNode.key)
-            } else {
-                // This should not happen if cache.current.size > 0
-                break
-            }
+        // 使用順の一覧と Map は同じ項目を持つので、Map が容量を超えている間は一覧の先頭が必ずある
+        for (let lruNode = list.current.peekHead(); lruNode !== null && cache.current.size > normalizedCapacity; lruNode = list.current.peekHead()) {
+            list.current.remove(lruNode)
+            cache.current.delete(lruNode.key)
         }
     }, [capacity, normalizedCapacity])
 

package/src/utils.ts

@@ -56,3 +56,18 @@ export const getAxisScale = (element: HTMLElement, axis: "x" | "y"): number => {
     }
     return visualSize / layoutSize
 }
+
+/**
+ * Pointer-down handler of pointer-only scroll chrome (the scrollbar and the scroll-to-edge pills of a host that scrolls by
+ * keyboard itself): cancels the press's default action, so the press never moves focus — neither onto a part of the chrome
+ * nor away from where the host put it — while the press itself, its pointer events and its click still reach the part.
+ *
+ * ポインタ専用のスクロールの部品 (キーボードのスクロールを自分で持つホストのスクロールバーと端へ戻るピル) の pointerdown の
+ * 処理。押下の既定動作を取り消すので、押下はフォーカスを動かさない — 部品の上へも、ホストが置いた場所の外へも — が、押下
+ * そのもの (ポインタのイベントと click) は部品へ届く。
+ *
+ * @param event - The pointer-down event (only its default action is read) / pointerdown のイベント (既定動作だけを扱う)
+ */
+export const keepFocusOnPress = (event: { readonly preventDefault: () => void }): void => {
+    event.preventDefault()
+}