@aiquants/virtualscroll 3.11.0 → 3.11.2

package/src/VirtualGrid.tsx

@@ -41,7 +41,7 @@ import { Logger } from "./logger.ts"
 import { resolveTapScrollCircleOptions, ScrollBar, type ScrollBarTapCircleOptions } from "./ScrollBar.tsx"
 import type { ScrollPaneProps } from "./ScrollPane.tsx"
 import { TapScrollCircle } from "./TapScrollCircle.tsx"
-import { useFenwickMapTree } from "./useFenwickMapTree.ts"
+import { FENWICK_LOOKUP_ONLY, useFenwickMapTree, useFenwickTreeRevision } from "./useFenwickMapTree.ts"
 import { GRID_TAP_CIRCLE_DEFAULT_OFFSET, useGridTapScroll } from "./useGridTapScroll.ts"
 import { minmax } from "./utils.ts"
 import { ANCHOR_REBASE_DISTANCE, computeRenderingRanges, MAX_RENDERED_ITEMS, VirtualScroll, type VirtualScrollBehaviorOptions, type VirtualScrollHandle, type VirtualScrollRange, type VirtualScrollScrollBarOptions, ZERO_HEIGHT_RUN_LIMIT } from "./VirtualScroll.tsx"
@@ -144,7 +144,7 @@ export const MAX_FROZEN_TRAILING_ROWS = 128
  * Maximum number of CONSECUTIVE NON-CONVERGENT self-heal flushes. A stable accessor converges in
  * ONE flush (tree == accessor afterwards), so the next collect pass is clean and RESETS this
  * counter — sequential legitimate width changes never accumulate. A truly oscillating getColWidth
- * (a contract violation) never produces a clean pass, so the heal→epoch→re-collect microtask
+ * (a contract violation) never produces a clean pass, so the heal→revision→re-collect microtask
  * cycle would spin forever — past this limit healing is suspended with a single warning (bounded
  * degradation instead of a livelock). ❗ The state is deliberately window-agnostic ({count,
  * warned} — no window key): a key-scoped reset would be evaded forever by an oscillation whose
@@ -155,7 +155,7 @@ export const MAX_FROZEN_TRAILING_ROWS = 128
  * 「**連続する非収束**」self-heal フラッシュ数の上限。安定したアクセサは 1 回で収束する
  * (治癒後は 木 == アクセサ) ため次の走査は乖離ゼロとなり本カウンタは**解消**される — 逐次の
  * 正当な幅変更は蓄積しない。真に振動する getColWidth (契約違反) は収束パスを一度も作れず、
- * 治癒→エポック→再走査のマイクロタスク循環が無限旋回するため、超過時は治癒を停止し 1 回だけ
+ * 治癒→版数→再走査のマイクロタスク循環が無限旋回するため、超過時は治癒を停止し 1 回だけ
  * 警告する (livelock でなく有界な縮退)。❗ 状態は意図的に窓非依存 ({count, warned} — 窓キーを
  * 持たない): キー基準の解消は、振幅が窓端を動かす振動が治癒のたびにキーを交互させて永久回避する
  * (実測反証済み)。停止後の回復は収束パス解消が担う (**どの窓でも**収束 1 回で治癒が再武装する)。
@@ -437,7 +437,13 @@ export type VirtualGridProps<T> = {
     testId?: string
 }
 
-/** Imperative handle (logical coordinates everywhere; -1 sentinels pre-attach — row-parity incl. return values). / 命令ハンドル (全て論理座標・未接続 -1 番兵 — 返り値契約まで行側と対称)。 */
+/**
+ * Imperative handle (logical coordinates everywhere — row-parity incl. return values). React attaches it after the embedded
+ * row list, so it never reads as unconnected; a handle the host keeps after the grid unmounts reports the last position and
+ * never throws.
+ * 命令ハンドル (全て論理座標 — 返り値契約まで行側と対称)。React は埋め込みの行の一覧の後にこれを取り付けるので、未接続の値を返す
+ * ことはない。グリッドのアンマウントの後もホストが持ち続けたハンドルは最後の位置を返し、投げない。
+ */
 export type VirtualGridHandle = {
     /**
      * Jump API — do NOT use for continuous input (use scrollBy). Vertical delegates to the row
@@ -470,7 +476,7 @@ export type VirtualGridHandle = {
      * 隠れた末尾セルはどのスクロール位置でも可視化できない — no-op はそこでも正確。
      */
     scrollToCell(row: number, col: number, options?: { alignY?: "top" | "bottom" | "center"; alignX?: "start" | "end" | "center"; offsetX?: number; offsetY?: number }): void
-    /** Synchronous-fresh position read (internal refs — safe mid-event; {-1,-1} pre-attach). / 同期・最新の位置読み (内部 ref — イベント中も安全。未接続 {-1,-1})。 */
+    /** Synchronous-fresh position read (internal refs — safe mid-event; after the grid unmounts, the last position). / 同期・最新の位置読み (内部 ref — イベント中も安全。グリッドのアンマウントの後は最後の位置)。 */
     getScrollPosition(): { x: number; y: number }
     /** {index, offset} anchor capture for exact restore; null when either count is 0, or the embedded scroll rows are absent (all-frozen OR a degenerate band whose H_F fills the viewport — both force itemCount 0, so there is no scroll row to anchor). / 厳密復元用アンカー捕獲。どちらかの count が 0、またはスクロール行が不在 (全行凍結 / H_F がビューポートを埋める縮退帯 — いずれも itemCount 0) なら null。 */
     getScrollAnchor(): { row: number; col: number; offsetX: number; offsetY: number } | null
@@ -480,14 +486,16 @@ export type VirtualGridHandle = {
     /** Pair-call seam: getRowHeight stays the truth. 3-way split — leading band rows bump the frozen-row epoch, trailing band rows bump the trailing-row epoch (accessor re-read; the bands hold no tree), scroll rows delegate to the row updateItemSize at −R. / 対呼び出しシーム (getRowHeight が正)。3 分岐 — 先頭帯行は凍結行 epoch、末尾帯行は末尾行 epoch の繰上げ (アクセサ再読 — 帯に木は無い)、スクロール行は −R で行 updateItemSize へ委譲。 */
     updateRowSize(row: number, px: number): void
     /**
-     * Column twin: validates (MAX_TRACK_SIZE fail-fast), updates the width tree, and bumps the
-     * width epoch so committed cells REPAINT even when the window key is unchanged (small grids,
-     * offsetting batch resizes). Multi-call batch loops coalesce into one recompute via React's
-     * automatic state batching (one commit per synchronous batch — the design's rAF-coalescing
-     * intent realized at commit granularity).
-     * 列双子: 検証 (fail-fast) → 幅木更新 → 幅エポックの繰上げで、窓キー不変でもコミット済み
-     * セルを再描画する (小さなグリッド・相殺バッチリサイズ)。連続呼び出しは React の自動
-     * バッチングで 1 コミットに合流 (設計の rAF 合流意図のコミット粒度での実現)。
+     * Column twin: validates (MAX_TRACK_SIZE fail-fast) and updates the width tree. A width that
+     * changes advances the width tree's revision, so committed cells REPAINT even when the window
+     * key is unchanged (small grids, offsetting batch resizes); the width the column already has
+     * changes nothing and re-renders nothing. Multi-call batch loops coalesce into one recompute via
+     * React's automatic state batching (one commit per synchronous batch — the design's
+     * rAF-coalescing intent realized at commit granularity).
+     * 列双子: 検証 (fail-fast) → 幅木の更新。幅が変われば幅木の版数が進み、窓キー不変でもコミット済み
+     * セルを再描画する (小さなグリッド・相殺バッチリサイズ)。列が既に持つ幅は何も変えず、何も
+     * 再描画しない。連続呼び出しは React の自動バッチングで 1 コミットに合流 (設計の rAF 合流意図の
+     * コミット粒度での実現)。
      */
     updateColSize(col: number, px: number): void
     /**
@@ -573,7 +581,7 @@ export const computeColumnPlacement = (
     // アンカー再基準化 (行 memo と同一ロジック): 描画窓先頭の絶対 X が現アンカーから距離超過の
     // ときのみ付替え。付替え先は任意座標 (グリッド量子化ではなくトリガー距離 — 付録 A.2)
     const safeStart = minmax(ranges.renderingStartIndex, 0, colCount - 1)
-    const { cumulative, currentValue } = colTree.prefixSum(safeStart, { materializeOption: { materialize: false } })
+    const { cumulative, currentValue } = colTree.prefixSum(safeStart, FENWICK_LOOKUP_ONLY)
     const startPosition = cumulative - currentValue
     const colAnchor = Number.isFinite(startPosition) && Math.abs(startPosition - prevAnchor) > ANCHOR_REBASE_DISTANCE ? startPosition : prevAnchor
     return {
@@ -606,7 +614,7 @@ const collectVisibleColumns = (startCol: number, endCol: number, getColWidth: (c
     const columns: PlacedColumn[] = []
     const widthUpdates: Array<{ index: number; value: number }> = []
     // 呼び出し元は空窓 (start > end) を先に除くので、ここへ来る窓は 1 列以上
-    const startPrefix = colTree.prefixSum(startCol, { materializeOption: { materialize: false } })
+    const startPrefix = colTree.prefixSum(startCol, FENWICK_LOOKUP_ONLY)
     // 窓先頭の絶対 left から幅を積む O(k) 走査 (列ごとの prefixSum O(k·log n) を回避 — 行 memo と同型)
     let runningLeft = startPrefix.cumulative - startPrefix.currentValue
     let zeroRun = 0
@@ -634,11 +642,11 @@ const collectVisibleColumns = (startCol: number, endCol: number, getColWidth: (c
         if (zeroRun > ZERO_HEIGHT_RUN_LIMIT) {
             // 幅 0 ランの Fenwick ジャンプ (行側と共有定数・同一比較 `>` — 複製禁止): 次の非 0 列へ。
             // +0.5 は右開区間バンプ — 木側の値で跳ぶため self-heal 前の乖離があっても有界性は保たれる
-            const jump = colTree.findIndexAtOrAfter(runningLeft + 0.5, { materializeOption: { materialize: false } })
+            const jump = colTree.findIndexAtOrAfter(runningLeft + 0.5, FENWICK_LOOKUP_ONLY)
             if (jump.index === -1 || jump.index <= i || !Number.isSafeInteger(jump.index)) {
                 break
             }
-            const jumpPrefix = colTree.prefixSum(jump.index, { materializeOption: { materialize: false } })
+            const jumpPrefix = colTree.prefixSum(jump.index, FENWICK_LOOKUP_ONLY)
             runningLeft = jumpPrefix.cumulative - jumpPrefix.currentValue
             i = jump.index
             zeroRun = 0
@@ -847,10 +855,10 @@ const VirtualGridInner = <T,>(
     }, [resetOnGetColWidthChange, defaultColWidth])
     const colTree = useFenwickMapTree(colCount, validatedGetColWidth, colTreeOptions)
 
-    // ---- 幅エポック (木の内容バージョン): updateColSize / self-heal 適用で繰上げ、窓キー不変でも
-    //      配置 memo と列窓再計算を失効させる。総幅は相殺バッチリサイズ (総和不変) で変わらないため
-    //      合図にならない (行側は VirtualScroll の木の版数が同じ役目を持つ) ----
-    const [widthEpoch, setWidthEpoch] = useState(0)
+    // ---- 列幅木の版数: 木は同一性を保ったまま描画の外で変わる (updateColSize・幅 self-heal) ので、変更はどれも changeColTree を
+    //      通し、木を読む memo と列窓の再計算は colTreeRevision に依存させる。総幅は相殺バッチリサイズ (総和不変) で変わらないため
+    //      合図にならず、同じ幅の書き込みは木の版を動かさないので再計算も確定も足さない (行側の VirtualScroll と同じ仕組み) ----
+    const { revision: colTreeRevision, change: changeColTree } = useFenwickTreeRevision(colTree)
 
     // ---- 凍結帯 (設計 §8) — 形状検証は fail-fast、colCount 超過だけは動的クランプ (シート
     //      切替の過渡で colCount が一時 0 になる正当構成を throw で殺さないための文書化契約) ----
@@ -971,7 +979,6 @@ const VirtualGridInner = <T,>(
     // ---- 論理位置 (float64 ref — DOM へは書かない) と鮮度序列 ----
     const hxRef = useRef(0)
     const vyRef = useRef(0)
-    const attachedRef = useRef(false)
 
     // ---- コミット済み列窓 + アンカー (M10 整合の単位) ----
     const [columnWindow, setColumnWindow] = useState<ColumnWindowState>(INITIAL_COLUMN_WINDOW)
@@ -1004,36 +1011,69 @@ const VirtualGridInner = <T,>(
     // ---- ビューポート実測 (RO — 縦バー幅ぶんを列窓から差し引く) ----
     const scrollBarWidth = scrollBarOptions?.width ?? 12
     const explicitViewport = viewportSize === undefined ? null : { width: Math.max(0, Math.round(viewportSize.width) - scrollBarWidth), height: Math.max(0, Math.round(viewportSize.height) - scrollBarWidth) }
-    const [measuredViewport, setMeasuredViewport] = useState({ width: 0, height: 0 })
-    const viewport = explicitViewport ?? measuredViewport
+    // ルートの箱はバー幅を引く前の寸法で持ち、引くのは描画の側に置く。バー幅が変わっても測り直さずに済み、計測はルートが
+    // 付いている間ずっと同じ 1 つで足りる
+    const [measuredRootSize, setMeasuredRootSize] = useState({ width: 0, height: 0 })
+    const viewport = explicitViewport ?? { width: Math.max(0, measuredRootSize.width - scrollBarWidth), height: Math.max(0, measuredRootSize.height - scrollBarWidth) }
     const viewportRef = useRef(viewport)
     viewportRef.current = viewport
     /** Degenerate band: H_F + H_T fills the measured viewport — scroll rows go canonical-EMPTY (§3.3 縮退帯の縦対称; 3.5.0 で −H_T を一般化). / 縮退帯: H_F + H_T が実測ビューポートを食い尽くす — スクロール行は正準空窓 (§3.3 の縦対称。3.5.0 で −H_T を一般化)。 */
     const degenerateBand = viewport.height > 0 && viewport.height - frozenHeight - trailingHeight <= 0
     degenerateBandRef.current = degenerateBand
     const hasExplicitViewport = explicitViewport !== null
-    useLayoutEffect(() => {
-        if (hasExplicitViewport) {
-            return
-        }
-        const root = rootRef.current
-        if (root === null) {
-            return
-        }
-        const measure = () => {
-            // ❗ 論理 (レイアウト) px で測る — getBoundingClientRect は祖先 transform scale 下で
-            // 視覚 px (論理 × z) を返し、ズームホストで窓寸・クランプ・列窓の全幾何が z 倍へ歪む。
-            // clientWidth / clientHeight は transform 非影響のレイアウト px (行側 ScrollPane の
-            // 自己計測と同じ座標系)
-            const width = Math.max(0, Math.round(root.clientWidth) - scrollBarWidth)
-            const height = Math.max(0, Math.round(root.clientHeight) - scrollBarWidth)
-            setMeasuredViewport((prev) => (prev.width === width && prev.height === height ? prev : { width, height }))
-        }
-        measure()
-        const observer = new ResizeObserver(measure)
-        observer.observe(root)
-        return () => observer.disconnect()
-    }, [scrollBarWidth, hasExplicitViewport])
+    /**
+     * Attaches the grid root: keeps `rootRef` on it and, while the viewport is self-measured, keeps `measuredRootSize` at
+     * the root's layout box with one ResizeObserver for as long as the root stays attached. A ref callback with a cleanup
+     * (React 19) receives the element itself, so the measurement never runs without one; the cleanup detaches the root and
+     * stops the observer. Its identity changes only when the viewport mode changes.
+     *
+     * グリッドのルートを取り付ける処理。`rootRef` をルートに保ち、ビューポートを自分で測る間は、ルートが付いている限り 1 つの
+     * ResizeObserver で `measuredRootSize` をルートのレイアウトの箱に保つ。後始末を返す ref コールバック (React 19) は要素そのものを
+     * 受け取るので、要素の無いまま測ることはない。後始末はルートを外して監視を止める。同一性はビューポートの方式が変わるときだけ変わる。
+     *
+     * @param root - The grid root element / グリッドのルート要素
+     * @returns The cleanup that detaches the root / ルートを外す後始末
+     */
+    const attachRoot = useCallback(
+        (root: HTMLDivElement) => {
+            rootRef.current = root
+            if (hasExplicitViewport) {
+                /**
+                 * Detaches the root (the given viewport needs no observer).
+                 * ルートを外す処理 (与えられたビューポートには監視が要らない)。
+                 */
+                return () => {
+                    rootRef.current = null
+                }
+            }
+            /**
+             * Reads the root's layout box into `measuredRootSize` (an unchanged box keeps the state as it is).
+             *
+             * ルートのレイアウトの箱を `measuredRootSize` へ読み込む処理 (箱が変わらなければ状態をそのまま保つ)。
+             */
+            const measure = () => {
+                // ❗ 論理 (レイアウト) px で測る — getBoundingClientRect は祖先 transform scale 下で
+                // 視覚 px (論理 × z) を返し、ズームホストで窓寸・クランプ・列窓の全幾何が z 倍へ歪む。
+                // clientWidth / clientHeight は transform 非影響のレイアウト px (行側 ScrollPane の
+                // 自己計測と同じ座標系)
+                const width = Math.round(root.clientWidth)
+                const height = Math.round(root.clientHeight)
+                setMeasuredRootSize((previous) => (previous.width === width && previous.height === height ? previous : { width, height }))
+            }
+            measure()
+            const observer = new ResizeObserver(measure)
+            observer.observe(root)
+            /**
+             * Detaches the root and stops the observer.
+             * ルートを外し、監視を止める処理。
+             */
+            return () => {
+                observer.disconnect()
+                rootRef.current = null
+            }
+        },
+        [hasExplicitViewport],
+    )
 
     // ---- 残差 var の書き手 (1 点)。コミット済みアンカー基準 — スクロール中の中間フレームでも
     //      セル left (コミット済みアンカー) と常に同一基準で整合する ----
@@ -1233,7 +1273,7 @@ const VirtualGridInner = <T,>(
             // colCount 縮小で範囲外化したアンカーは最終列へ明示クランプ (fail-safe — 木側の暗黙
             // クランプへ依存しない。挙動は §7 の既知の制約として記録)
             const safeCol = minmax(anchor.col, 0, Math.max(0, colCount - 1))
-            const prefix = colTree.prefixSum(safeCol, { materializeOption: { materialize: false } })
+            const prefix = colTree.prefixSum(safeCol, FENWICK_LOOKUP_ONLY)
             const colLeft = prefix.cumulative - prefix.currentValue
             const colWidth = prefix.currentValue
             // 凍結帯 (§8): 整列先はスクロール帯 [W_F, viewport − W_T) — 列座標から W_F を引き、
@@ -1247,7 +1287,7 @@ const VirtualGridInner = <T,>(
     )
 
     // ---- 幅 self-heal (窓内の getColWidth と木の乖離をバッチ適用 — 行 memo の toUpdateHeights 双子)。
-    //      適用後はエポックを繰上げ、治癒前の stale な左座標で確定したセル配置を再計算させる ----
+    //      適用は木の版数を進め、治癒前の stale な左座標で確定したセル配置を再計算させる ----
     const pendingWidthUpdatesRef = useRef<Array<{ index: number; value: number }> | null>(null)
     const flushWidthUpdates = useCallback(() => {
         const updates = pendingWidthUpdatesRef.current
@@ -1255,17 +1295,16 @@ const VirtualGridInner = <T,>(
         if (updates === null || updates.length === 0) {
             return
         }
-        commitTotalWidth(colTree.updates(updates))
-        setWidthEpoch((epoch) => epoch + 1)
-    }, [colTree, commitTotalWidth])
+        commitTotalWidth(changeColTree(() => colTree.updates(updates)))
+    }, [colTree, changeColTree, commitTotalWidth])
 
     // ---- 凍結帯の列挙 (設計 §8 — 窓化されない静的帯)。幅 self-heal は共有バッチへ合流し、
     //      暴走ガードは帯専用カウンタ (スクロール窓側と独立 — 凍結専用振動アクセサが窓側の
     //      収束リセットで永久にガードを回避する穴を作らない) ----
     const frozenHealBurstRef = useRef({ count: 0, warned: false })
     const { frozenColumns, frozenWidth } = useMemo(() => {
-        // widthEpoch は木内容バージョンの反応辺 (スクロール窓 memo と同じ規律)
-        void widthEpoch
+        // 列幅木の版数は木の中身の反応辺 (スクロール窓 memo と同じ規律)
+        void colTreeRevision
         if (effectiveFrozenCols === 0) {
             // 凍結解除は帯ガードのエピソードも閉じる — 次の凍結エピソードが停止状態を継承して
             // 無言で self-heal 不能になる越境リークの遮断 (R3 実証)
@@ -1295,7 +1334,7 @@ const VirtualGridInner = <T,>(
             frozenHealBurstRef.current.warned = false
         }
         return { frozenColumns: columns, frozenWidth: width }
-    }, [effectiveFrozenCols, widthEpoch, validatedGetColWidth, colTree, flushWidthUpdates])
+    }, [effectiveFrozenCols, colTreeRevision, validatedGetColWidth, colTree, flushWidthUpdates])
     frozenWidthRef.current = frozenWidth
     // 凍結幅 var の書き手 (1 点): クリップ左端 (.aqvs-grid-row-scroll の left) と残差の −W_F 項
     // (.aqvs-grid-row-scroll-inner の calc) の両消費者が読む
@@ -1314,8 +1353,8 @@ const VirtualGridInner = <T,>(
     //      閉じる — 先頭帯の「越境リーク遮断」と同文) ----
     const trailingHealBurstRef = useRef({ count: 0, warned: false })
     const { trailingColumns, trailingWidth } = useMemo(() => {
-        // widthEpoch は木内容バージョンの反応辺 (先頭帯 memo と同じ規律)
-        void widthEpoch
+        // 列幅木の版数は木の中身の反応辺 (先頭帯 memo と同じ規律)
+        void colTreeRevision
         if (effectiveTrailingCols === 0) {
             // 末尾凍結解除は帯ガードのエピソードも閉じる (先頭帯の R3 実証と同文の遮断)
             trailingHealBurstRef.current.count = 0
@@ -1344,7 +1383,7 @@ const VirtualGridInner = <T,>(
             trailingHealBurstRef.current.warned = false
         }
         return { trailingColumns: columns, trailingWidth: width }
-    }, [effectiveTrailingCols, colCount, widthEpoch, validatedGetColWidth, colTree, flushWidthUpdates])
+    }, [effectiveTrailingCols, colCount, colTreeRevision, validatedGetColWidth, colTree, flushWidthUpdates])
     trailingWidthRef.current = trailingWidth
     // 末尾幅 var の書き手 (3.5.0 プラン §6.1-8 — **単一書き手規律**: この effect だけが書く)。
     // 消費者はクリップ右端 (.aqvs-grid-row-scroll の right)・末尾クリップの max() 左端と inner 幅。
@@ -1408,24 +1447,24 @@ const VirtualGridInner = <T,>(
      * throttled `onScroll` relay (`handleVerticalScroll`) — which regresses it by up to the
      * `callbackThrottleMs` window mid-drive; a driver base read from the mirror overstates
      * `actualDelta` by the staleness gap, drives the axis residual negative, and the driver
-     * then issues REAL backward `scrollBy` writes (the 3.6.0 y-axis tap yo-yo — v3.6.1).
+     * then issues REAL backward `scrollBy` writes (the 3.6.0 y-axis tap yo-yo — v3.6.1). The grid
+     * handle's `getScrollPosition` reads its y here too. Only once the grid has unmounted (a kept
+     * handle, a tap frame between the unmount commit and the passive cleanup) is the embedded
+     * handle gone; then the mirror is the position `applyVy` holds still at, and it is returned.
      * 埋め込みハンドル経由の鮮度 y 位置 — `applyVy` の `scrollBy` が updater を解決するのと
      * **同一の権威** (ペイン内部 ref)。`getMaxVy` の鮮度チャネル、および「`getHx` が `applyHx`
      * の書き先セルそのものを読む」x 側と対称。ここで `vyRef` を読んではならない: あの鏡像には
      * 第 2 の書き手 (スロットル済み `onScroll` 中継 = `handleVerticalScroll`) が居て、駆動中に
      * 最大 `callbackThrottleMs` 窓ぶん巻き戻す。鏡像基準の `actualDelta` は staleness ギャップ
      * ぶん過大になり、軸残差が負へ落ちて、ドライバ自身が**実後退**の `scrollBy` を発行する
-     * (3.6.0 の y 軸タップヨーヨー — v3.6.1)。
+     * (3.6.0 の y 軸タップヨーヨー — v3.6.1)。グリッドのハンドルの `getScrollPosition` も y をここで読む。
+     * 埋め込みハンドルが無いのはグリッドがアンマウントした後だけ (保持したハンドル・アンマウントの確定から
+     * 受け身の後始末までのタップのフレーム) で、そのときは `applyVy` が留まる位置である鏡像を返す。
      */
     const getVy = useCallback(() => {
         const inner = scrollHandleRef.current
-        if (inner === null) {
-            // ハンドル未接続時は applyVy と同じ「動かない」姿勢 — 同じ座標 (vyRef) を基準に返す
-            return vyRef.current
-        }
-        const position = inner.getScrollPosition()
-        // ペイン未接続の番兵 (-1) も applyVy の不動姿勢と同じ座標へ落とす (負位置は実在しない)
-        return position < 0 ? vyRef.current : position
+        // 埋め込みのペインは埋め込みのハンドルと同じ確定で付き外れするので、ハンドルがある間は未接続の番兵 (-1) が返らない
+        return inner === null ? vyRef.current : inner.getScrollPosition()
     }, [])
     /**
      * Fresh y extent through the embedded handle — the same freshness channel the vertical bar
@@ -1442,17 +1481,19 @@ const VirtualGridInner = <T,>(
     }, [])
     /**
      * The y apply seam (§3.5-8): wraps the embedded `scrollBy` AND syncs `vyRef.current =
-     * applied` before returning — the grid handle `scrollBy` y-half twin, symmetric with
-     * `applyHxRef`. Without the sync, x-frame `onScroll({ x, y: vyRef.current })` notifications
-     * during a diagonal drag carry y stale by up to the `callbackThrottleMs` window (MV-XY29).
+     * applied` before returning — the y half of the grid handle's `scrollBy` as well, symmetric
+     * with `applyHxRef`. Without the sync, x-frame `onScroll({ x, y: vyRef.current })`
+     * notifications during a diagonal drag carry y stale by up to the `callbackThrottleMs` window
+     * (MV-XY29). Without the embedded handle (only after the grid unmounted) nothing moves and the
+     * current mirror is returned.
      * y 適用シーム (§3.5-8): 埋め込み `scrollBy` をラップし、**返す前に** `vyRef.current =
-     * applied` を同期する — グリッドハンドル `scrollBy` の y 半分の双子で `applyHxRef` と対称。
-     * 同期が無いと対角ドラッグ中の x フレーム通知が stale y を運ぶ (MV-XY29)。
+     * applied` を同期する — グリッドハンドルの `scrollBy` の y 半分もこれを通り、`applyHxRef` と対称。
+     * 同期が無いと対角ドラッグ中の x フレーム通知が stale y を運ぶ (MV-XY29)。埋め込みハンドルが無い
+     * (グリッドのアンマウントの後だけ) ときは何も動かさず、今の鏡像を返す。
      */
     const applyVy = useCallback((delta: number): number => {
         const inner = scrollHandleRef.current
         if (inner === null) {
-            // ハンドル未接続時は現在値を返して動かない (グリッドハンドル scrollBy と同じ姿勢)
             return vyRef.current
         }
         const applied = inner.scrollBy(delta)
@@ -1488,7 +1529,7 @@ const VirtualGridInner = <T,>(
         return minmax(baseOpacity * resolvedTapX.opacity, 0, 1)
     }, [isTapActive, resolvedTapX.opacity])
 
-    // ---- ビューポート / 総幅 / 幅エポック変化での再クランプ + 列窓追随。保留列アンカーが
+    // ---- ビューポート / 総幅 / 列幅木の版数の変化での再クランプ + 列窓追随。保留列アンカーが
     //      あれば位置はアンカーから再導出 (単なる再クランプでは推定空間の hx が残留する) ----
     useLayoutEffect(() => {
         const pending = pendingColAnchorRef.current
@@ -1498,7 +1539,7 @@ const VirtualGridInner = <T,>(
             applyHxRef.current(resolveColumnAnchorHx(pending))
         }
         refreshColumns()
-    }, [viewport.width, totalWidth, widthEpoch, frozenWidth, trailingWidth, refreshColumns, resolveColumnAnchorHx])
+    }, [viewport.width, totalWidth, colTreeRevision, frozenWidth, trailingWidth, refreshColumns, resolveColumnAnchorHx])
 
     // ---- 初期アンカー復元 (横) — 生 px でなく {col, offsetX} (行と同一契約)。マウント時 1 回。
     //      保留列アンカーとして張り、以後の self-heal による列左の実測化へ追随させる ----
@@ -1526,7 +1567,6 @@ const VirtualGridInner = <T,>(
     // ---- 縦軸の結線 ----
     const handleVerticalScroll = useCallback((position: number) => {
         vyRef.current = position
-        attachedRef.current = true
         onScrollRef.current?.({ x: hxRef.current, y: position })
     }, [])
     const handleVerticalRangeChange = useCallback(
@@ -1571,14 +1611,14 @@ const VirtualGridInner = <T,>(
     // (行凍結設計 §4-7、3.5.0 プラン §6.1-13)
     const maxColsPerRow = resolveMaxColsPerRow(__maxRenderedCells, effectiveRenderedRows + frozenRows.length + trailingRows.length)
     // self-heal の暴走ガード: 乖離→治癒→再乖離の非収束が連続する = getColWidth が自身の
-    // 過去値と不一致を繰り返す契約違反 (振動アクセサ)。放置すると治癒→エポック→再走査の
+    // 過去値と不一致を繰り返す契約違反 (振動アクセサ)。放置すると治癒→版数→再走査の
     // マイクロタスクループが無限旋回するため、上限で治癒を停止し 1 回だけ警告する。
     // 状態は {count, warned} のみ — 窓キーは保持しない (キー基準の解消は窓端を動かす振動に
     // 永久回避されるため構造的に持たない。解消は収束パスのみ)
     const healBurstRef = useRef({ count: 0, warned: false })
     const { placedColumns, truncatedCols } = useMemo(() => {
-        // widthEpoch は木の内容バージョンの反応辺 (木は identity 安定のため値経由では失効しない)
-        void widthEpoch
+        // 列幅木の版数は木の中身の反応辺 (木は同一性を保つので、木の参照では失効しない)
+        void colTreeRevision
         // 凍結帯 (§8): スクロール帯幅 ≤ 0 (W_F + W_T ≥ viewport の縮退 — 3.5.0 一般化) は
         // スクロール列を描かない — 凍結帯 / 末尾帯自体は独立 memo が描き続ける定義済み縮退
         const bandWidth = Math.max(0, viewport.width - frozenWidth - trailingWidth)
@@ -1621,7 +1661,7 @@ const VirtualGridInner = <T,>(
         // deps へ trailingWidth / trailingColumns.length を明示追加 (3.5.0 プラン §6.1-6 / F4):
         // bandWidth 式とスクロール列予算が同 memo 内で両値を読む — 追加を怠ると列窓キー不変の
         // T トグルで memo が stale 化し、予算が trailing 分だけ過大に残る
-    }, [columnWindow, colCount, viewport.width, frozenWidth, trailingWidth, frozenColumns.length, trailingColumns.length, widthEpoch, validatedGetColWidth, colTree, maxColsPerRow, flushWidthUpdates])
+    }, [columnWindow, colCount, viewport.width, frozenWidth, trailingWidth, frozenColumns.length, trailingColumns.length, colTreeRevision, validatedGetColWidth, colTree, maxColsPerRow, flushWidthUpdates])
 
     // 打切りは無言にしない (設計 §3.2 — 行側の病的ガードと違い正当構成で到達し得る)
     const lastTruncationKeyRef = useRef("")
@@ -1774,6 +1814,12 @@ const VirtualGridInner = <T,>(
     useImperativeHandle(
         ref,
         (): VirtualGridHandle => ({
+            /**
+             * Applies `y` through the embedded row list's `scrollTo` (it floors and pins a row anchor) and `x` through `applyHx`,
+             * clearing any column anchor; returns the applied position.
+             * `y` は埋め込みの行の一覧の `scrollTo` (切り捨てて行のアンカーを張る) で、`x` は列のアンカーを外して `applyHx` で当て、当てた位置を
+             * 返す処理。
+             */
             scrollTo: (pos) => {
                 const inner = scrollHandleRef.current
                 let y = vyRef.current
@@ -1790,13 +1836,14 @@ const VirtualGridInner = <T,>(
                 }
                 return { x, y }
             },
+            /**
+             * Applies a non-zero `y` delta through `applyVy` and a non-zero `x` delta through `applyHx` (clearing any column anchor);
+             * returns the applied position.
+             * 0 でない `y` の差分は `applyVy` で、0 でない `x` の差分は列のアンカーを外して `applyHx` で当て、当てた位置を返す処理。
+             */
             scrollBy: (delta) => {
-                const inner = scrollHandleRef.current
-                let y = vyRef.current
-                if (delta.y !== undefined && delta.y !== 0 && inner !== null) {
-                    y = inner.scrollBy(delta.y)
-                    vyRef.current = y
-                }
+                // 縦の差分はタップの駆動と同じ継ぎ目 (applyVy) で当て、適用と鏡像の同期を 2 通りに書かない
+                const y = delta.y !== undefined && delta.y !== 0 ? applyVy(delta.y) : vyRef.current
                 let x = hxRef.current
                 if (delta.x !== undefined && delta.x !== 0) {
                     pendingColAnchorRef.current = null
@@ -1804,6 +1851,12 @@ const VirtualGridInner = <T,>(
                 }
                 return { x, y }
             },
+            /**
+             * Reveals a cell: a scroll row through the embedded row list's `scrollToIndex` (translated by −R), a scroll column by
+             * arming a column anchor and applying its position; a frozen or trailing band row or column leaves its axis as it is.
+             * セルを見せる処理。スクロール行は −R へ訳して埋め込みの行の一覧の `scrollToIndex` で、スクロール列は列のアンカーを張ってその位置を
+             * 当てる。先頭・末尾の帯の行や列を狙った軸はそのまま。
+             */
             scrollToCell: (row, col, options) => {
                 const inner = scrollHandleRef.current
                 if (inner !== null && rowCount > 0) {
@@ -1828,7 +1881,18 @@ const VirtualGridInner = <T,>(
                     }
                 }
             },
-            getScrollPosition: () => (attachedRef.current || scrollHandleRef.current !== null ? { x: hxRef.current, y: scrollHandleRef.current?.getScrollPosition() ?? vyRef.current } : { x: -1, y: -1 }),
+            /**
+             * Reads the position: `x` from the horizontal cell, `y` through `getVy` (the embedded handle, or the last position once the
+             * grid has unmounted).
+             * 位置を読む処理。`x` は横の位置のセルから、`y` は `getVy` (埋め込みのハンドル。グリッドのアンマウントの後は最後の位置) から。
+             */
+            getScrollPosition: () => ({ x: hxRef.current, y: getVy() }),
+            /**
+             * Captures the `{ row, col, offsetX, offsetY }` anchor of the first visible cell of the scroll band, on the same boundary
+             * rule as the row side; null when either count is 0 or there is no scroll row.
+             * スクロール帯の最初に見えるセルの `{ row, col, offsetX, offsetY }` のアンカーを、行の側と同じ境界の規則で捕える処理。どちらかの数が 0、
+             * またはスクロール行が無ければ null。
+             */
             getScrollAnchor: () => {
                 if (rowCount === 0 || colCount === 0) {
                     return null
@@ -1843,7 +1907,7 @@ const VirtualGridInner = <T,>(
                 // 凍結帯 (§8): アンカーはスクロール帯の可視先頭 = 木座標 W_F + hx で捕獲する
                 // (復元側 resolveColumnAnchorHx が W_F を引き戻すため往復が恒等)
                 const bandStart = frozenWidthRef.current + hxRef.current
-                const found = colTree.findIndexAtOrAfter(bandStart, { materializeOption: { materialize: false } })
+                const found = colTree.findIndexAtOrAfter(bandStart, FENWICK_LOOKUP_ONLY)
                 if (found.index === -1) {
                     return { row: rowAnchor.index + effectiveFrozenRows, col: colCount - 1, offsetX: 0, offsetY: rowAnchor.offsetPx }
                 }
@@ -1851,15 +1915,30 @@ const VirtualGridInner = <T,>(
                     return { row: rowAnchor.index + effectiveFrozenRows, col: minmax(found.index + 1, 0, colCount - 1), offsetX: 0, offsetY: rowAnchor.offsetPx }
                 }
                 // 見つけた列の左端は木から読み直す (探索の結果の型は列が無い場合の undefined を含むため)
-                const column = colTree.prefixSum(found.index, { materializeOption: { materialize: false } })
+                const column = colTree.prefixSum(found.index, FENWICK_LOOKUP_ONLY)
                 // 行はシフト空間 → フル行空間へ +R 翻訳 (行凍結設計 §3 — 復元側は −R で往復恒等)
                 return { row: rowAnchor.index + effectiveFrozenRows, col: found.index, offsetX: Math.max(0, bandStart - (column.cumulative - column.currentValue)), offsetY: rowAnchor.offsetPx }
             },
+            /**
+             * Reads the cell viewport (the measured or given box without the bars).
+             * セルのビューポート (測ったか与えられた箱からバーを除いたもの) を読む処理。
+             */
             getViewportSize: () => ({ width: viewportRef.current.width, height: viewportRef.current.height }),
+            /**
+             * Reads the content size: the total column width, and the band heights plus the embedded row list's content size
+             * (insets included; 0 once the grid has unmounted).
+             * 中身の寸法を読む処理。列の総幅と、帯の高さに埋め込みの行の一覧の中身の高さ (インセット込み。グリッドのアンマウントの後は 0) を足したもの。
+             */
             // 縦はインセット込みの行側 getContentSize を単一情報源にする (range.totalHeight は木総高のみ)。
             // 3.5.0: height = H_F + 埋め込み + H_T
             getContentSize: () => ({ width: totalWidthRef.current, height: scrollHandleRef.current === null ? 0 : frozenHeightRef.current + trailingHeightRef.current + Math.max(0, scrollHandleRef.current.getContentSize()) }),
             getRange: buildRange,
+            /**
+             * Takes a row's new height (validated first): a leading or trailing band row re-reads its accessor through its epoch, a
+             * scroll row goes to the embedded row list's `updateItemSize` (translated by −R).
+             * 行の新しい高さを受け取る処理 (先に検証)。先頭・末尾の帯の行は epoch でアクセサを読み直させ、スクロール行は −R へ訳して埋め込みの
+             * 行の一覧の `updateItemSize` へ渡す。
+             */
             updateRowSize: (row, px) => {
                 validateTrackSize(px, "row", row)
                 // 凍結行はグリッド所有バンド — epoch 繰上げでアクセサ再読 (帯に第 2 の格納庫は
@@ -1873,13 +1952,20 @@ const VirtualGridInner = <T,>(
                     scrollHandleRef.current?.updateItemSize(Math.trunc(row) - effectiveFrozenRows, px)
                 }
             },
+            /**
+             * Takes a column's new width (validated first) into the width tree and mirrors the new total width at once.
+             * 列の新しい幅を (先に検証して) 幅木へ入れ、新しい総幅をすぐに写す処理。
+             */
             updateColSize: (col, px) => {
                 validateTrackSize(px, "col", col)
-                // 総幅は ref へも即時反映 (同 tick の scrollBy/scrollTo が旧上限でクランプしないため)
-                commitTotalWidth(colTree.update(minmax(Math.trunc(col), 0, Math.max(0, colCount - 1)), px))
-                // 窓キー不変の幅変更でもセル配置を失効させる (バッチループは React 自動バッチングで 1 コミット)
-                setWidthEpoch((epoch) => epoch + 1)
+                // 総幅は ref へも即時反映 (同 tick の scrollBy/scrollTo が旧上限でクランプしないため)。幅が変われば木の版数が進み、
+                // 窓キー不変でもセル配置を失効させる (バッチループは React 自動バッチングで 1 コミット)。同じ幅は何も失効させない
+                commitTotalWidth(changeColTree(() => colTree.update(minmax(Math.trunc(col), 0, Math.max(0, colCount - 1)), px)))
             },
+            /**
+             * Reads the effective frozen bands of both axes and both ends (the visible trailing sizes through `trailingVisibleSize`).
+             * 両軸・両端の実効の凍結帯を読む処理 (見えている末尾の寸法は `trailingVisibleSize` で求める)。
+             */
             getFrozenSize: () => ({
                 cols: effectiveFrozenCols,
                 width: frozenWidthRef.current,
@@ -1893,7 +1979,18 @@ const VirtualGridInner = <T,>(
                 trailingVisibleWidth: trailingVisibleSize(trailingWidthRef.current, frozenWidthRef.current, viewportRef.current.width),
                 trailingVisibleHeight: trailingVisibleSize(trailingHeightRef.current, frozenHeightRef.current, viewportRef.current.height),
             }),
+            /**
+             * Applies one wheel event through the embedded row list (its horizontal part reaches the grid's own axis through the
+             * row list's `onWheelHorizontal`); returns whether the event was consumed, false once the grid has unmounted.
+             * ホイールのイベント 1 つを埋め込みの行の一覧で当てる処理 (横の成分は行の一覧の `onWheelHorizontal` を通ってグリッド自身の軸へ届く)。
+             * 消費したかを返し、グリッドのアンマウントの後は false。
+             */
             applyWheel: (event) => scrollHandleRef.current?.applyWheel(event) ?? false,
+            /**
+             * Focuses a row: a leading or trailing band row through its band DOM, a scroll row through the embedded row list's
+             * `focusItemAtIndex` (translated by −R).
+             * 行へフォーカスする処理。先頭・末尾の帯の行は帯の DOM へ直接、スクロール行は −R へ訳して埋め込みの行の一覧の `focusItemAtIndex` で。
+             */
             focusRowAtIndex: (row, options) => {
                 // 凍結行はバンド行 DOM へ直接フォーカス、末尾帯行も帯行 DOM へ直接フォーカス
                 // (3.5.0 — 3 分岐。T = 0 は分岐不成立で従来挙動と恒等)、スクロール行は −R 翻訳して委譲
@@ -1907,11 +2004,11 @@ const VirtualGridInner = <T,>(
                 }
             },
         }),
-        [rowCount, colCount, colTree, buildRange, commitTotalWidth, resolveColumnAnchorHx, effectiveFrozenCols, effectiveFrozenRows, effectiveTrailingCols, effectiveTrailingRows],
+        [rowCount, colCount, colTree, changeColTree, buildRange, commitTotalWidth, resolveColumnAnchorHx, getVy, applyVy, effectiveFrozenCols, effectiveFrozenRows, effectiveTrailingCols, effectiveTrailingRows],
     )
 
     return (
-        <div ref={rootRef} className={twMerge("aqvs-grid", effectiveFrozenRows > 0 ? "aqvs-grid-has-frozen-rows" : "", effectiveTrailingRows > 0 ? "aqvs-grid-has-trailing-rows" : "", className)} data-testid={testId}>
+        <div ref={attachRoot} className={twMerge("aqvs-grid", effectiveFrozenRows > 0 ? "aqvs-grid-has-frozen-rows" : "", effectiveTrailingRows > 0 ? "aqvs-grid-has-trailing-rows" : "", className)} data-testid={testId}>
             {effectiveFrozenRows > 0 ? (
                 // 凍結行帯 (行凍結設計 §4-2): グリッド所有の帯外バンド — 行本体は renderRow を
                 // そのまま再利用する (F > 0 の凍結セル / クリップ / hx 残差 var は継承で無償追随