@aiquants/virtualscroll 3.11.0 → 3.11.2

package/src/VirtualScroll.tsx

@@ -1,9 +1,9 @@
-import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react"
+import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { type DevicePixelSnapEdge, snapToDevicePixelGrid, usePaintingDevicePixelRatio } from "./devicePixelGrid.ts"
 import { resolveVirtualScrollLabels, type VirtualScrollLabelOverrides, type VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
 import { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneProps } from "./ScrollPane.tsx"
-import { useFenwickMapTree } from "./useFenwickMapTree.ts"
+import { FENWICK_LOOKUP_ONLY, useFenwickMapTree, useFenwickTreeRevision } from "./useFenwickMapTree.ts"
 import { getAxisScale, keepFocusOnPress, minmax } from "./utils.ts"
 
 /**
@@ -906,17 +906,6 @@ const ItemsWrapper = ({ translateY, snapEdge, children, boundaryRef }: ItemsWrap
  */
 const DEFAULT_HORIZONTAL_KEY_STEP = 40
 
-/**
- * Advances VirtualScroll's tree revision by one (the reducer of the revision that the memos reading the row-height tree
- * depend on).
- *
- * VirtualScroll の木の版数を 1 つ進める処理 (行の高さの木を読む memo が依存する版数の reducer)。
- *
- * @param revision - The current revision / 今の版数
- * @returns The next revision / 次の版数
- */
-const nextTreeRevision = (revision: number): number => revision + 1
-
 /**
  * Converts a numeric size into a non-negative bigint for large collection handling.
  *
@@ -947,9 +936,6 @@ export type VisibleStartRow = {
  */
 type VisibleStartRowTree = Pick<ReturnType<typeof useFenwickMapTree>, "findIndexAtOrAfter" | "prefixSum">
 
-/** Tree reads that only look the rows up, never materialising them / 行を引くだけで具現化しない木の読み方 */
-const LOOKUP_ONLY = { materializeOption: { materialize: false } } as const
-
 /**
  * Resolves the first visible row at a logical scroll position by the visible-start boundary rule — the one rule that
  * `scrollTo` pins, `getScrollAnchor` reports, `updateItemSize` compensates above and `computeRenderingRanges` renders from
@@ -981,9 +967,9 @@ const LOOKUP_ONLY = { materializeOption: { materialize: false } } as const
  */
 export const resolveVisibleStartRow = (fenwickTree: VisibleStartRowTree, position: number, itemCount: number): VisibleStartRow => {
     const lastIndex = itemCount - 1
-    const found = fenwickTree.findIndexAtOrAfter(position, LOOKUP_ONLY)
+    const found = fenwickTree.findIndexAtOrAfter(position, FENWICK_LOOKUP_ONLY)
     if (found.index === -1 || found.index > lastIndex || found.cumulative === undefined || found.currentValue === undefined) {
-        const last = fenwickTree.prefixSum(lastIndex, LOOKUP_ONLY)
+        const last = fenwickTree.prefixSum(lastIndex, FENWICK_LOOKUP_ONLY)
         return { index: lastIndex, top: last.cumulative - last.currentValue }
     }
     if (found.cumulative === position && found.index < lastIndex) {
@@ -1059,11 +1045,11 @@ export const computeRenderingRangesHuge = (effectiveScrollPosition: number, view
             // number へ安全に変換できない領域では木のクエリが不正確になるため打ち切る
             return null
         }
-        const { cumulative: runBottom } = fenwickTree.prefixSum(lastNumber, LOOKUP_ONLY)
+        const { cumulative: runBottom } = fenwickTree.prefixSum(lastNumber, FENWICK_LOOKUP_ONLY)
         if (!Number.isFinite(runBottom)) {
             return null
         }
-        const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom + 0.5, LOOKUP_ONLY)
+        const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom + 0.5, FENWICK_LOOKUP_ONLY)
         if (jumpIndex === -1) {
             return null
         }
@@ -1138,11 +1124,10 @@ export const computeRenderingRangesHuge = (effectiveScrollPosition: number, view
                     if (!Number.isSafeInteger(indexNumber)) {
                         break
                     }
-                    const { cumulative: runBottom } = fenwickTree.prefixSum(indexNumber, LOOKUP_ONLY)
-                    if (!Number.isFinite(runBottom)) {
-                        break
-                    }
-                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, LOOKUP_ONLY)
+                    // 後方の行は先頭の可視行より上にあり、木の値は負にならないので、その累積は先頭の可視行の上端 (有限の位置以下) を
+                    // 越えない。前方と違い、累積が溢れた行へは後方の走査が届かない
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(indexNumber, FENWICK_LOOKUP_ONLY)
+                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, FENWICK_LOOKUP_ONLY)
                     const jumpBig = jumpIndex === -1 ? -1n : toSafeBigInt(jumpIndex)
                     if (jumpBig >= 0n && jumpBig < backwardStart) {
                         // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
@@ -1219,8 +1204,8 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
             if (currentHeight === 0) {
                 zeroRun++
                 if (zeroRun > ZERO_HEIGHT_RUN_LIMIT) {
-                    const { cumulative: runBottom } = fenwickTree.prefixSum(forwardCursor - 1, { materializeOption: { materialize: false } })
-                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom + 0.5, { materializeOption: { materialize: false } }) : { index: -1 }
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(forwardCursor - 1, FENWICK_LOOKUP_ONLY)
+                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom + 0.5, FENWICK_LOOKUP_ONLY) : { index: -1 }
                     if (jumpIndex > forwardCursor) {
                         // 0 行の連続を飛び越えて次の非 0 行から走査を続行する
                         forwardCursor = jumpIndex
@@ -1258,9 +1243,10 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
             if (itemHeight === 0) {
                 backwardZeroRun++
                 if (backwardZeroRun > ZERO_HEIGHT_RUN_LIMIT) {
-                    // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)
-                    const { cumulative: runBottom } = fenwickTree.prefixSum(backwardCursor, { materializeOption: { materialize: false } })
-                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom - 0.5, { materializeOption: { materialize: false } }) : { index: -1 }
+                    // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)。後方の行は先頭の可視行より上にあり、
+                    // 木の値は負にならないので、その累積は先頭の可視行の上端 (有限の位置以下) を越えない
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(backwardCursor, FENWICK_LOOKUP_ONLY)
+                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, FENWICK_LOOKUP_ONLY)
                     if (jumpIndex !== -1 && jumpIndex < backwardCursor) {
                         // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
                         backwardCursor = jumpIndex
@@ -1315,8 +1301,8 @@ type OnRangeChangeCallback = (range: VirtualScrollRange) => void
  * @param throttleMs Minimum time between invocations in ms / 実行間の最小時間（ミリ秒）
  * @param invoke Wrapper function to execute the callback (e.g. for argument unwrapping) / コールバックを実行するラッパー関数
  */
-const useThrottledInvoker = <Callback, Payload>(callbackRef: React.MutableRefObject<Callback | undefined>, throttleMs: number | undefined, invoke: (callback: Callback, payload: Payload) => void) => {
-    const throttle = Math.max(0, throttleMs ?? 0)
+const useThrottledInvoker = <Callback, Payload>(callbackRef: React.MutableRefObject<Callback | undefined>, throttleMs: number, invoke: (callback: Callback, payload: Payload) => void) => {
+    const throttle = Math.max(0, throttleMs)
     // last: 最終実行時刻, id: RAF ID, arg: 待機中の引数
     const state = useRef({ last: 0, id: null as number | null, arg: null as Payload | null }).current
 
@@ -1343,6 +1329,12 @@ const useThrottledInvoker = <Callback, Payload>(callbackRef: React.MutableRefObj
         [state, callbackRef, invoke],
     )
 
+    /**
+     * Schedules one invocation with the latest payload: at most once per animation frame, and not before `throttleMs` has passed
+     * since the previous one; a payload that arrives while one is pending replaces it.
+     * 最新のペイロードでの 1 回の実行を予約する処理。アニメーションのフレームごとに多くて 1 回で、前回から `throttleMs` が経つまでは実行しない。
+     * 予約中に届いたペイロードは前のものを置き換える。
+     */
     return useCallback(
         (payload: Payload) => {
             state.arg = payload
@@ -1572,34 +1564,10 @@ const VirtualScrollInner = <T,>(
     const fenwickTree = useFenwickMapTree(itemCount, getItemHeight, fenwickTreeOptions)
 
     // ❗ 木は同一性を保ったまま描画の外で書き換わる (updateItemSize・高さの照合・scrollToIndex の具現化)。接頭辞和の変化は総和が
-    // 変わらなくても (差の和が 0 の測り直しの組) 描いた行の上端と高さ、描画範囲を変えるので、木を読むどの memo もこの版数に
-    // 依存させる。総和 (中身の寸法) は相殺で変わらず、同じ値の書き込みは React が捨てるため、変化の合図にならない
-    const [treeRevision, advanceTreeRevision] = useReducer(nextTreeRevision, 0)
-
-    /**
-     * Runs one change of the row-height tree made outside render (`updateItemSize`, the height reconciliation, the
-     * materialisation of `scrollToIndex`) and, when the tree's revision moved (`FenwickMapTree.revision`), advances the tree
-     * revision, so the next commit re-places the rendered rows and re-resolves the rendering range whether or not the total
-     * changed.
-     *
-     * 描画の外で行う行の高さの木の変更を 1 回実行し (`updateItemSize`・高さの照合・`scrollToIndex` の具現化)、木の版
-     * (`FenwickMapTree.revision`) が動いたら木の版数を進める処理。総和が変わったかどうかによらず、次の確定が描いた行を置き直し、
-     * 描画範囲を解決し直す。
-     *
-     * @param change - The change of the tree / 木の変更
-     * @returns What `change` returned / `change` の戻り値
-     */
-    const changeTree = useCallback(
-        <Result,>(change: () => Result): Result => {
-            const revisionBefore = fenwickTree.revision
-            const result = change()
-            if (fenwickTree.revision !== revisionBefore) {
-                advanceTreeRevision()
-            }
-            return result
-        },
-        [fenwickTree],
-    )
+    // 変わらなくても (差の和が 0 の測り直しの組) 描いた行の上端と高さ、描画範囲を変えるので、描画の外の変更はどれも changeTree を
+    // 通し、木を読むどの memo も treeRevision に依存させる。総和 (中身の寸法) は相殺で変わらず、同じ値の書き込みは React が捨てるため、
+    // 変化の合図にならない
+    const { revision: treeRevision, change: changeTree } = useFenwickTreeRevision(fenwickTree)
 
     const [initialValues] = useState(() => {
         let position = 0
@@ -1613,19 +1581,19 @@ const VirtualScrollInner = <T,>(
             const safeIndexFrom = minmax(safeIndex - overscanCount * 2, 0, itemCount - 1)
             const safeIndexTo = minmax(safeIndex + overscanCount * 2, 0, itemCount - 1)
             const options = safeIndex > 0 || anchorOffsetPx > 0 ? { materializeOption: { materialize: true, ranges: [{ from: safeIndexFrom, to: safeIndexTo }] } } : undefined
-            const { cumulative, total: materializedTotal, currentValue } = fenwickTree.prefixSum(safeIndex, options)
+            const { cumulative, currentValue } = fenwickTree.prefixSum(safeIndex, options)
             const logicalOffset = Math.max(cumulative - currentValue + anchorOffsetPx, 0)
             position = toPanePositionWithInset(logicalOffset, resolvedInsets.top)
-            total = materializedTotal ?? fenwickTree.getTotal()
+            total = fenwickTree.getTotal()
         } else if (typeof initialScrollIndex === "number") {
             const safeIndex = minmax(initialScrollIndex, 0, itemCount - 1)
             const safeIndexFrom = minmax(safeIndex - overscanCount * 2, 0, itemCount - 1)
             const safeIndexTo = minmax(safeIndex + overscanCount * 2, 0, itemCount - 1)
             const options = initialScrollIndex > 0 ? { materializeOption: { materialize: true, ranges: [{ from: safeIndexFrom, to: safeIndexTo }] } } : undefined
-            const { cumulative, total: materializedTotal, currentValue } = fenwickTree.prefixSum(initialScrollIndex, options)
+            const { cumulative, currentValue } = fenwickTree.prefixSum(initialScrollIndex, options)
             const logicalOffset = Math.max(cumulative - currentValue, 0)
             position = toPanePositionWithInset(logicalOffset, resolvedInsets.top)
-            total = materializedTotal ?? fenwickTree.getTotal()
+            total = fenwickTree.getTotal()
         } else if (typeof initialScrollOffset === "number") {
             position = toPanePositionWithInset(Math.max(initialScrollOffset, 0), resolvedInsets.top)
             total = fenwickTree.getTotal()
@@ -2163,7 +2131,7 @@ const VirtualScrollInner = <T,>(
         if (pendingVisibleStartIndexRef.current !== null) {
             const { index, align, offset } = pendingVisibleStartIndexRef.current
             const safeIndex = sanitizeIndex(index, itemCount)
-            const { cumulative: itemBottom, currentValue: itemHeight } = fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: false } })
+            const { cumulative: itemBottom, currentValue: itemHeight } = fenwickTree.prefixSum(safeIndex, FENWICK_LOOKUP_ONLY)
 
             if (itemBottom !== undefined && itemHeight !== undefined) {
                 const itemTop = Math.max(itemBottom - itemHeight, 0)
@@ -2349,7 +2317,7 @@ const VirtualScrollInner = <T,>(
                     throw new RangeError(`[VirtualScroll] scrollToIndex: align "nearest" takes no offset (it lands the row at the edge of the band a visible scroll-to-edge pill leaves); received an offset of type ${typeof offset}.`)
                 }
                 // 見せるかどうかは今の木で決める。描画の窓とその周りの行は照合で実際の高さを持ち、窓から遠い行は表示域の中にない
-                const row = fenwickTree.prefixSum(safeIndex, LOOKUP_ONLY)
+                const row = fenwickTree.prefixSum(safeIndex, FENWICK_LOOKUP_ONLY)
                 const reveal = resolveRevealAlignment({ top: row.cumulative - row.currentValue, bottom: row.cumulative }, toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top), viewportSize, readObscuredInsets())
                 if (reveal === null) {
                     return
@@ -2978,7 +2946,7 @@ const VirtualScrollInner = <T,>(
 
         const safeRenderingStartIndex = sanitizeIndex(renderingStartIndex, itemCount)
         const safeRenderingEndIndex = sanitizeIndex(renderingEndIndex, itemCount)
-        const { cumulative, currentValue: oldHeight } = fenwickTree.prefixSum(safeRenderingStartIndex, { materializeOption: { materialize: false } })
+        const { cumulative, currentValue: oldHeight } = fenwickTree.prefixSum(safeRenderingStartIndex, FENWICK_LOOKUP_ONLY)
         const startPosition = cumulative - oldHeight
 
         // 量子化アンカーの再基準化: 描画ウィンドウ先頭が現アンカーから一定距離を超えて離れたときだけ
@@ -3069,13 +3037,12 @@ const VirtualScrollInner = <T,>(
                 }
 
                 // 照合した行の上端は描画の中で補ってあるが、木から導いた値 (getRange の総高さなど) は古い木のまま。総和が変わらない
-                // 変化でも、次の確定で木から導き直させる
-                const total = changeTree(() => fenwickTree.updates(toUpdateHeights))
-                if (isUnmountedRef.current || typeof total !== "number") {
-                    return
-                }
+                // 変化でも、次の確定で木から導き直させる。ここから先は同期で、上の確認の後にアンマウントは挟まらない
+                changeTree(() => fenwickTree.updates(toUpdateHeights))
+                const total = fenwickTree.getTotal()
                 writeContentSize(total)
                 Logger.debug("[VirtualScroll] Updated heights for items", toUpdateHeights, "New total height:", total)
+                // 並行の描画では、初回の描画のマイクロタスクがその確定 (ペインの取り付け) より先に走ることがある
                 const panePosition = scrollPaneRef.current?.getScrollPosition() ?? latestScrollPositionRef.current
 
                 if (shiftAmount !== 0) {
@@ -3139,7 +3106,7 @@ const VirtualScrollInner = <T,>(
      */
     const renderVisibleItems = useCallback(
         (currentScrollPosition: number) => {
-            const shouldUseThrottledPosition = (callbackThrottleMs ?? 0) > 0
+            const shouldUseThrottledPosition = callbackThrottleMs > 0
             const diff = Math.abs(currentScrollPosition - scrollPosition)
             const rawEffectiveScrollPosition = shouldUseThrottledPosition && diff > 0.5 ? scrollPosition : currentScrollPosition
             const effectiveScrollPosition = toLogicalPositionWithInset(rawEffectiveScrollPosition, resolvedInsets.top)
@@ -3273,21 +3240,46 @@ const VirtualScrollInner = <T,>(
     useImperativeHandle(
         ref,
         () => ({
+            /**
+             * Reads the logical scroll position (the pane's position less the top inset), or the `-1` sentinel while the pane is
+             * unconnected.
+             * 論理スクロール位置 (ペインの位置から上のインセットを引いたもの) を読む処理。ペインが未接続の間は番兵の `-1`。
+             */
             getScrollPosition: () => {
                 // ❗ 論理座標で返す (2.0.0)。ペイン座標を返す実装へ戻さないこと: 消費者の換算コードが
                 // 座標混在バグの温床になる (この統一が本質修正)。inset は走行中も最新を ref から読む
                 const panePosition = scrollPaneRef.current?.getScrollPosition()
                 return typeof panePosition === "number" ? toLogicalPositionWithInset(panePosition, resolvedInsetsTopRef.current) : -1
             },
+            /**
+             * Reads the pane's content size (insets included), or the `-1` sentinel while the pane is unconnected.
+             * ペインの中身の寸法 (インセット込み) を読む処理。ペインが未接続の間は番兵の `-1`。
+             */
             getContentSize: () => scrollPaneRef.current?.getContentSize() ?? -1,
+            /**
+             * Reads the pane's viewport size, or the `-1` sentinel while the pane is unconnected.
+             * ペインの表示域の寸法を読む処理。ペインが未接続の間は番兵の `-1`。
+             */
             getViewportSize: () => scrollPaneRef.current?.getViewportSize() ?? -1,
             scrollTo: scrollToHandle,
             scrollBy,
             applyWheel,
             scrollToIndex,
+            /**
+             * Reads the total of the row-height tree (insets excluded).
+             * 行の高さの木の合計 (インセットを除く) を読む処理。
+             */
             getFenwickTreeTotalHeight: () => fenwickTree.getTotal(),
+            /**
+             * Reads the number of rows the row-height tree holds.
+             * 行の高さの木が持つ行の数を読む処理。
+             */
             getFenwickSize: () => fenwickTree.getSize(),
             focusItemAtIndex,
+            /**
+             * Reads the range the last commit published (one render behind).
+             * 最後の確定が公開した範囲 (描画 1 回ぶん遅れる) を読む処理。
+             */
             getRange: () => currentRangeRef.current,
             getScrollAnchor,
             updateItemSize,

package/src/residualQuantizer.ts

@@ -105,6 +105,12 @@ export const createResidualQuantizer = (options: ResidualQuantizerOptions): Resi
     let residue = 0
 
     return {
+        /**
+         * Adds a delta to the residue and emits the whole quanta it holds (a non-finite delta, or one beyond
+         * `Number.MAX_SAFE_INTEGER`, emits 0 and leaves the residue as it is).
+         * 差分を残差へ足し、残差が持つ量子の整数倍を放出する処理 (非有限の差分と `Number.MAX_SAFE_INTEGER` を越える差分は 0 を放出し、
+         * 残差を変えない)。
+         */
         push: (delta: number): number => {
             // 非有限デルタは残差を汚さず 0 を返す (蓄積器に NaN が入ると以後全放出が死ぬ)。
             // ❗ |delta| > Number.MAX_SAFE_INTEGER も同じ契約で見送る: 2^53 超では
@@ -125,7 +131,15 @@ export const createResidualQuantizer = (options: ResidualQuantizerOptions): Resi
             residue -= emitted
             return emitted
         },
+        /**
+         * Reads the residue not yet emitted.
+         * まだ放出していない残差を読む処理。
+         */
         peekResidue: () => residue,
+        /**
+         * Drops the residue.
+         * 残差を捨てる処理。
+         */
         reset: () => {
             residue = 0
         },

package/src/useFenwickMapTree.ts

@@ -11,7 +11,7 @@
  * それを管理するための React フック `useFenwickMapTree` の提供。
  * 動的なアイテムサイズを持つ仮想スクロールのシナリオに最適化されている。
  */
-import { useRef } from "react"
+import { useCallback, useReducer, useRef } from "react"
 import { Logger } from "./logger.ts"
 import { minmax } from "./utils.ts"
 
@@ -32,6 +32,17 @@ type MaterializeConfig = { materializeOption?: MaterializeOption }
 type DeltaUpdate = { index: number; change: number }
 type ValueUpdate = { index: number; value: number }
 
+/**
+ * The options of a tree read that only looks rows up and never materialises them (`prefixSum`, `get`, `getTotal`,
+ * `findIndexAtOrAfter`, `findIndexAtOrBefore`): the read leaves the stored values, the size and `revision` as they are. One
+ * frozen value that every lookup passes, so no caller spells the option out. Internal to the package (not in the barrel).
+ *
+ * 行を引くだけで具現化しない木の読み取り (`prefixSum`・`get`・`getTotal`・`findIndexAtOrAfter`・`findIndexAtOrBefore`) の選択肢。
+ * 読み取りは保持する値・要素数・`revision` をそのまま残す。どの引き当ても渡す凍結した 1 つの値で、呼び出し側は選択肢を書き下さない。
+ * パッケージの内部用 (バレル非公開)。
+ */
+export const FENWICK_LOOKUP_ONLY = Object.freeze({ materializeOption: Object.freeze({ materialize: false }) })
+
 /**
  * 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
@@ -1432,3 +1443,73 @@ export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: num
 
     return tree
 }
+
+/**
+ * What `useFenwickTreeRevision` returns: the revision the memos that read one tree depend on, and the one way to change that
+ * tree outside render so that they see the change.
+ *
+ * `useFenwickTreeRevision` の戻り値。1 本の木を読む memo が依存する版数と、memo が変化に気付くように描画の外でその木を変える
+ * ただ 1 つの方法。
+ */
+export type FenwickTreeRevision = {
+    /** Advances by one per change made through `change` that moved the tree's revision / `change` を通した変更が木の版を動かすたびに 1 つ進む数 */
+    readonly revision: number
+    /** Runs one change of the tree made outside render and returns its result; advances `revision` only when the tree's revision moved / 描画の外で行う木の変更を 1 回実行してその結果を返し、木の版が動いたときだけ `revision` を進める処理 */
+    readonly change: <Result>(mutate: () => Result) => Result
+}
+
+/**
+ * Advances a component's tree revision by one (the reducer behind `FenwickTreeRevision["revision"]`).
+ *
+ * コンポーネントの木の版数を 1 つ進める処理 (`FenwickTreeRevision["revision"]` の reducer)。
+ *
+ * @param revision - The current revision / 今の版数
+ * @returns The next revision / 次の版数
+ */
+const nextTreeRevision = (revision: number): number => revision + 1
+
+/**
+ * Ties the memos of a component to the contents of a Fenwick tree. The tree keeps its identity while its contents change
+ * (`useFenwickMapTree`), so a memo that derives anything from its prefix sums (row tops, a rendering range, the placed
+ * columns) cannot see a change through the tree itself, and the total is no signal either: a batch of changes that cancel out
+ * leaves it as it was. Every change made outside render goes through `change`, which advances `revision` exactly when the
+ * tree's own revision (`FenwickMapTree.revision`) moved, so the next commit recomputes the memos that depend on `revision`,
+ * and a change that stores the same values (an update to the value a row already has, a materialisation that finds the stored
+ * value) adds no commit. Changes made during render (a reset or a resize by `useFenwickMapTree`) come with new props, which the
+ * memos depend on already. Internal to the package (not in the barrel).
+ *
+ * コンポーネントの memo を Fenwick 木の中身に結び付けるフック。木は中身が変わっても同一性を保つ (`useFenwickMapTree`) ので、
+ * 接頭辞和から何か (行の上端・描画範囲・配置した列) を導く memo は木そのものからは変化に気付けず、総和も合図にならない (打ち消し合う
+ * 変更の組は総和を変えない)。描画の外の変更はすべて `change` を通し、`change` は木自身の版 (`FenwickMapTree.revision`) が動いたとき
+ * ちょうどに `revision` を進める。だから次の確定は `revision` に依存する memo を計算し直し、同じ値を保つ変更 (行が既に持つ値への更新・
+ * 保持する値と同じ値を見つけた具現化) は確定を足さない。描画中の変更 (`useFenwickMapTree` のリセットと大きさの変更) は新しい props と
+ * 一緒に来るので、memo は既にそれに依存している。パッケージの内部用 (バレル非公開)。
+ *
+ * @param tree - The tree whose changes the memos must see / memo が変化に気付くべき木
+ * @returns The revision and the change runner / 版数と変更の実行関数
+ */
+export const useFenwickTreeRevision = (tree: FenwickMapTree): FenwickTreeRevision => {
+    const [revision, advanceRevision] = useReducer(nextTreeRevision, 0)
+
+    /**
+     * Runs one change of the tree and advances the revision when the tree's revision moved.
+     *
+     * 木の変更を 1 回実行し、木の版が動いたら版数を進める処理。
+     *
+     * @param mutate - The change of the tree / 木の変更
+     * @returns What `mutate` returned / `mutate` の戻り値
+     */
+    const change = useCallback(
+        <Result>(mutate: () => Result): Result => {
+            const revisionBefore = tree.revision
+            const result = mutate()
+            if (tree.revision !== revisionBefore) {
+                advanceRevision()
+            }
+            return result
+        },
+        [tree],
+    )
+
+    return { revision, change }
+}

package/src/useGridTapScroll.ts

@@ -8,7 +8,7 @@
  * immobile 停止則・延長成長の再武装・fail-closed のキャンセル 3 系。
  */
 
-import { useCallback, useEffect, useRef, useState } from "react"
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react"
 import { computeTapScrollVelocity, type TapScrollAxisSpeedParams } from "./computeTapScrollVelocity.ts"
 import { TAP_SCROLL_CANCEL_EVENT, TAP_SCROLL_MAX_FRAME_DELTA_SECONDS } from "./ScrollBar.tsx"
 import type { TapScrollCircleDragState, TapScrollCircleHandle } from "./TapScrollCircle.tsx"
@@ -113,6 +113,8 @@ export const useGridTapScroll = (params: UseGridTapScrollParams): UseGridTapScro
     const tapCircleHandleRef = useRef<TapScrollCircleHandle | null>(null)
     const [isTapActive, setIsTapActive] = useState(false)
     const frameRef = useRef<number | null>(null)
+    // 生きているのは、フックの部品を置いた確定から取り除く確定まで (レイアウトの副作用の本体と後始末が書く)
+    const isLiveRef = useRef(false)
     const lastTimestampRef = useRef<number | null>(null)
     const xDriveRef = useRef<AxisDriveState>({ residual: 0, direction: 0 })
     const yDriveRef = useRef<AxisDriveState>({ residual: 0, direction: 0 })
@@ -181,14 +183,20 @@ export const useGridTapScroll = (params: UseGridTapScrollParams): UseGridTapScro
     }, [])
 
     /**
-     * One integration frame of the two-axis loop.
-     * 2 軸ループの 1 積分フレーム。
+     * One integration frame of the two-axis loop. A frame that runs after the commit that unmounts the hook's component (one
+     * the browser had already scheduled, or one a drag report started after that commit) moves nothing and ends the loop.
+     * 2 軸ループの 1 積分フレーム。フックの部品をアンマウントする確定の後に走るフレーム (ブラウザが予約済みだったもの、またはその確定の
+     * 後のドラッグの知らせが始めたもの) は何も動かさず、ループを終える。
      */
     const step = useCallback(
         (timestamp: number) => {
             // この rAF ループ意味論は ScrollBar.tsx の tap ループ (stepAutoScroll) と双子 — 片方を直したらもう片方も直すこと
             const current = paramsRef.current
             const state = tapDragStateRef.current
+            if (!isLiveRef.current) {
+                stopLoop()
+                return
+            }
             if (!state.active || state.direction === 0) {
                 stopLoop()
                 return
@@ -348,20 +356,38 @@ export const useGridTapScroll = (params: UseGridTapScrollParams): UseGridTapScro
     }, [enabled, resetTapScroll])
 
     /**
-     * Cancel path (c): `enabled` → false resets; unmount stops the loop.
-     * キャンセル系 (c): `enabled` → false でリセット、アンマウントでループ停止。
+     * Cancel path (c), first half: `enabled` → false resets.
+     * キャンセル系 (c) の前半: `enabled` → false でリセット。
      *
-     * 目的: 無効化 / 退場時に rAF を残さない。
-     * 依存関係: [enabled, resetTapScroll] / [stopLoop]
-     * クリーンアップ: アンマウント時のループ停止。
+     * 目的: 無効化時に rAF を残さない。
+     * 依存関係: [enabled, resetTapScroll]
+     * クリーンアップ: 不要 (アンマウントの停止は後半が担う)。
      */
     useEffect(() => {
         if (!enabled) {
             resetTapScroll()
         }
     }, [enabled, resetTapScroll])
-    useEffect(() => {
+
+    /**
+     * Cancel path (c), second half: the liveness of the hook's component, and the stop at unmount. The loop stops in the commit
+     * that unmounts the component (a layout-effect cleanup), not in the passive cleanups after it: when the unmount is not
+     * synchronous, the browser can run a scheduled frame between that commit and the passive cleanups, and that frame would
+     * move the grid and call the host's `onScroll` after the grid is gone. A frame that still runs after the commit finds the
+     * hook not live (`step`).
+     * キャンセル系 (c) の後半: フックの部品が生きているかと、アンマウントでの停止。ループはその後の受け身の後始末ではなく、部品を
+     * アンマウントする確定 (レイアウトの副作用の後始末) で止める。アンマウントが同期でないとき、ブラウザはその確定と受け身の後始末の間に
+     * 予約済みのフレームを走らせられ、そのフレームはグリッドが消えた後にグリッドを動かしてホストの `onScroll` を呼んでしまう。確定の後に
+     * なお走るフレームは、フックが生きていないことを見て何もしない (`step`)。
+     *
+     * 目的: アンマウントの確定の後に位置を動かさない。
+     * 依存関係: [stopLoop] (同一性は不変なので、マウントで 1 回・アンマウントで 1 回)
+     * クリーンアップ: 生きていない印とループの停止。
+     */
+    useLayoutEffect(() => {
+        isLiveRef.current = true
         return () => {
+            isLiveRef.current = false
             stopLoop()
         }
     }, [stopLoop])

package/src/useLruCache.ts

@@ -91,10 +91,10 @@ class DoublyLinkedList<K, V> {
     }
 
     /**
-     * @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.
+     * Returns the head of the list (the least recently used item) without removing it.
+     * リストの先頭 (最も最近使用されていないアイテム) を外さずに返す処理。
+     *
+     * @returns {DoublyLinkedListNode<K, V> | null} The head node, or null if the list is empty / 先頭のノード (空なら null)
      */
     peekHead(): DoublyLinkedListNode<K, V> | null {
         return this.head

package/src/useWheelBridge.ts

@@ -95,6 +95,12 @@ export const useWheelBridge = (target: RefObject<WheelBridgeTarget | null>, opti
     // WeakMap なので、外し損ねた要素があっても要素ごと GC される。
     const attachedRef = useRef<WeakMap<HTMLElement, (event: WheelEvent) => void>>(new WeakMap())
 
+    /**
+     * The ref callback for an element outside the pane: it attaches one non-passive wheel listener per element, which applies each
+     * wheel event to the target, and returns the cleanup that removes it (React 19). Its identity never changes.
+     * ペインの外の要素に付ける ref コールバック。要素ごとに 1 つの非 passive なホイールのリスナーを付け (ホイールのイベントをそれぞれ対象へ当てる)、
+     * それを外す後始末を返す (React 19)。同一性は変わらない。
+     */
     return useCallback((node: HTMLElement | null) => {
         // ❗ null 呼び出しでは何も外さない。どの要素の話か分からないため、ここで外すと
         // 無関係の要素を巻き添えにする。解除は下のクリーンアップ (要素を知っている) が行う。
@@ -111,6 +117,10 @@ export const useWheelBridge = (target: RefObject<WheelBridgeTarget | null>, opti
             return
         }
 
+        /**
+         * Applies one wheel event to the target unless the bridge is disabled.
+         * ブリッジが無効でなければ、ホイールのイベント 1 つを対象へ当てる処理。
+         */
         const listener = (event: WheelEvent) => {
             if (optionsRef.current?.enableBridge === false) {
                 return
@@ -126,6 +136,10 @@ export const useWheelBridge = (target: RefObject<WheelBridgeTarget | null>, opti
         node.addEventListener("wheel", listener, { passive: false })
         attachedRef.current.set(node, listener)
 
+        /**
+         * Removes the element's listener, when it is still the one this call attached.
+         * 要素のリスナーを、この呼び出しが付けたものである限り外す処理。
+         */
         // React 19 はこのクリーンアップを受け取ると `null` 呼び出しの代わりに実行する。
         // ❗ listener の一致判定は**意図的な防御**である。ref コールバックの identity は固定
         // (依存配列が空) なので、要素がマウントされている限り React は張り直さず、現状この分岐が