@aiquants/virtualscroll 3.11.1 → 3.11.3

package/src/VirtualScroll.tsx

@@ -241,7 +241,12 @@ export type VirtualScrollScrollBarOptions = {
     enableArrowButtonTabStops?: boolean
     /**
      * Whether to show the auto-hiding Top / Bottom pills (default `false`; texts from `labels.scrollToTop` / `labels.scrollToBottom`).
+     * A user scroll shows the pill of the edge it moves toward, or the other edge's pill once the pane rests at that edge; a pill
+     * shows only while the pane can still scroll toward its edge, so it hides as soon as the pane comes to rest there, and a pane
+     * that cannot scroll shows neither.
      * 自動で隠れる Top / Bottom ピルを表示するかどうか (既定 `false`。文言は `labels.scrollToTop` / `labels.scrollToBottom`)。
+     * 利用者のスクロールは向かう端のピルを出し、ペインがその端に着いていれば反対の端のピルを出す。ピルはペインがまだその端の方へ
+     * スクロールできる間だけ見えるので、ペインがその端に着くとすぐ隠れ、スクロールできないペインはどちらも出さない。
      */
     enableScrollToTopBottomButtons?: boolean
     /** Renderer for UI anchored near the thumb. / つまみ付近に重ねる UI のレンダラー。 */
@@ -722,6 +727,54 @@ const edgeOfAlignment = (align: "top" | "bottom" | "center" | undefined): Aligne
  */
 const canonicalAlignedEdge = (alignment: AlignedEdge | null): AlignedEdge | null => (alignment !== null && alignment.panePosition <= 0 ? null : alignment)
 
+/**
+ * The edge a scroll-to-edge pill scrolls to: `"top"` (the Top pill, to the first row) or `"bottom"` (the Bottom pill, to the
+ * last row).
+ *
+ * 端へ戻るピルが送る先の端。`"top"` (Top ピル。最初の行へ) か `"bottom"` (Bottom ピル。最後の行へ)。
+ */
+type EdgePill = "top" | "bottom"
+
+/** How long a pill stays after the user scroll that showed it, unless the pane comes to rest at its edge first (ms) / ピルを出した利用者のスクロールからピルが消えるまでの時間 (ms。先にペインがその端に着けばそこで消える) */
+const EDGE_PILL_HIDE_DELAY_MS = 2000
+
+/**
+ * Whether the pane can still scroll toward an edge: toward the top while its position exceeds 0, toward the bottom while
+ * its position stays under the max scroll position, each by more than `EDGE_POSITION_TOLERANCE` (closer counts as resting
+ * at that edge). A pane that cannot scroll (max scroll position 0) can scroll toward neither edge.
+ *
+ * ペインがまだその端の方へスクロールできるかの判定。上端へは位置が 0 を上回り、下端へは位置が最大位置を下回り、どちらも
+ * `EDGE_POSITION_TOLERANCE` を超えて離れている間だけ (それより近ければその端に着いている)。スクロールできないペイン
+ * (最大位置 0) はどちらの端へもスクロールできない。
+ *
+ * @param edge - The edge / 端
+ * @param panePosition - Pane position (px) / ペイン位置 (px)
+ * @param maxScrollPosition - The pane's max scroll position (px) / ペインの最大位置 (px)
+ * @returns True while the pane can scroll toward the edge / その端の方へスクロールできる間は true
+ */
+const canScrollTowardEdge = (edge: EdgePill, panePosition: number, maxScrollPosition: number): boolean => (edge === "top" ? panePosition > EDGE_POSITION_TOLERANCE : panePosition < maxScrollPosition - EDGE_POSITION_TOLERANCE)
+
+/**
+ * Picks the pill a user scroll shows: the pill of the edge the scroll moves toward while the pane can still scroll toward
+ * that edge; once the pane rests at that edge, the pill of the other edge; and no pill when the pane can scroll toward
+ * neither edge.
+ *
+ * 利用者のスクロールが出すピルを選ぶ処理。スクロールが向かう端の方へまだスクロールできる間はその端のピル、ペインがその端に
+ * 着いたら反対の端のピル、どちらの端へもスクロールできなければピル無し。
+ *
+ * @param toward - The edge the scroll moves toward / スクロールが向かう端
+ * @param panePosition - Pane position after the scroll (px) / スクロール後のペイン位置 (px)
+ * @param maxScrollPosition - The pane's max scroll position (px) / ペインの最大位置 (px)
+ * @returns The pill to show, or `null` for none / 出すピル (無ければ `null`)
+ */
+const pickEdgePill = (toward: EdgePill, panePosition: number, maxScrollPosition: number): EdgePill | null => {
+    if (canScrollTowardEdge(toward, panePosition, maxScrollPosition)) {
+        return toward
+    }
+    const opposite: EdgePill = toward === "top" ? "bottom" : "top"
+    return canScrollTowardEdge(opposite, panePosition, maxScrollPosition) ? opposite : null
+}
+
 /**
  * The parts of the viewport that something drawn over the rows covers — the visible scroll-to-edge pill — as px from each
  * edge to the far side of what covers it. Module-level export (NOT in the package barrel), the parameter type of
@@ -1124,10 +1177,9 @@ export const computeRenderingRangesHuge = (effectiveScrollPosition: number, view
                     if (!Number.isSafeInteger(indexNumber)) {
                         break
                     }
+                    // 後方の行は先頭の可視行より上にあり、木の値は負にならないので、その累積は先頭の可視行の上端 (有限の位置以下) を
+                    // 越えない。前方と違い、累積が溢れた行へは後方の走査が届かない
                     const { cumulative: runBottom } = fenwickTree.prefixSum(indexNumber, FENWICK_LOOKUP_ONLY)
-                    if (!Number.isFinite(runBottom)) {
-                        break
-                    }
                     const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, FENWICK_LOOKUP_ONLY)
                     const jumpBig = jumpIndex === -1 ? -1n : toSafeBigInt(jumpIndex)
                     if (jumpBig >= 0n && jumpBig < backwardStart) {
@@ -1244,9 +1296,10 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
             if (itemHeight === 0) {
                 backwardZeroRun++
                 if (backwardZeroRun > ZERO_HEIGHT_RUN_LIMIT) {
-                    // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)
+                    // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)。後方の行は先頭の可視行より上にあり、
+                    // 木の値は負にならないので、その累積は先頭の可視行の上端 (有限の位置以下) を越えない
                     const { cumulative: runBottom } = fenwickTree.prefixSum(backwardCursor, FENWICK_LOOKUP_ONLY)
-                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom - 0.5, FENWICK_LOOKUP_ONLY) : { index: -1 }
+                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, FENWICK_LOOKUP_ONLY)
                     if (jumpIndex !== -1 && jumpIndex < backwardCursor) {
                         // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
                         backwardCursor = jumpIndex
@@ -1301,8 +1354,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
 
@@ -1329,6 +1382,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
@@ -1575,19 +1634,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()
@@ -1721,9 +1780,51 @@ const VirtualScrollInner = <T,>(
     const pendingFocusIndexRef = useRef<number | null>(null)
     const lastFocusedIndexRef = useRef<number | null>(null)
 
-    const [scrollDirection, setScrollDirection] = useState<"up" | "down" | null>(null)
+    // スクロールの向きではなくピルそのものを持つ。端に着いたスクロールは反対の端のピルを出すので、向きからピルは決まらない。
+    // 隠れた後も同じピルを描き続けるのは、隠れるフェードをそのピルのまま見せるため
+    const [edgePill, setEdgePill] = useState<EdgePill | null>(null)
     const [showScrollButtons, setShowScrollButtons] = useState(false)
+    // 見えているピルの同期の写し (隠れている間は null)。スクロールの処理は状態を閉じ込めずに要否を決め、隠れているピルへ同じ値を
+    // 書いて確定を足さない
+    const shownEdgePillRef = useRef<EdgePill | null>(null)
     const scrollButtonTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+    /**
+     * Hides the visible scroll-to-edge pill and cancels its auto-hide timer; writes no state while no pill shows.
+     *
+     * 見えている端へ戻るピルを隠し、自動非表示のタイマーを止める処理。ピルが見えていない間は状態を書かない。
+     */
+    const hideEdgePill = useCallback((): void => {
+        if (scrollButtonTimerRef.current !== null) {
+            clearTimeout(scrollButtonTimerRef.current)
+            scrollButtonTimerRef.current = null
+        }
+        if (shownEdgePillRef.current === null) {
+            return
+        }
+        shownEdgePillRef.current = null
+        setShowScrollButtons(false)
+    }, [])
+
+    /**
+     * Shows a scroll-to-edge pill and (re)starts its auto-hide timer (`EDGE_PILL_HIDE_DELAY_MS`).
+     *
+     * 端へ戻るピルを出し、自動非表示のタイマー (`EDGE_PILL_HIDE_DELAY_MS`) を掛け直す処理。
+     *
+     * @param pill - The pill to show / 出すピル
+     */
+    const showEdgePill = useCallback(
+        (pill: EdgePill): void => {
+            shownEdgePillRef.current = pill
+            setEdgePill(pill)
+            setShowScrollButtons(true)
+            if (scrollButtonTimerRef.current !== null) {
+                clearTimeout(scrollButtonTimerRef.current)
+            }
+            scrollButtonTimerRef.current = setTimeout(hideEdgePill, EDGE_PILL_HIDE_DELAY_MS)
+        },
+        [hideEdgePill],
+    )
     // 見せる操作は、画面に出ているピルを表示域 (行ラッパーの境界の箱の上端が表示域の上端) に対して測る
     const edgeOverlayRef = useRef<HTMLDivElement>(null)
     const edgePillRef = useRef<HTMLButtonElement>(null)
@@ -2528,9 +2629,17 @@ const VirtualScrollInner = <T,>(
     const applyWheel = useCallback((event: WheelEvent): boolean => scrollPaneRef.current?.applyWheel(event) ?? false, [])
 
     /**
-     * Handles scroll events from the pane.
+     * Handles scroll events from the pane. With the scroll-to-edge pills on, a scroll of any kind (user, programmatic or
+     * compensating) that leaves the pane resting at the visible pill's edge hides that pill at once (`canScrollTowardEdge`),
+     * and a user scroll of more than 1 px shows the pill `pickEdgePill` picks for its direction (none when the pane can
+     * scroll toward neither edge) and restarts the auto-hide timer.
+     *
+     * ペインのスクロールイベントを処理。端へ戻るピルが有効なら、ペインを見えているピルの端に止めたスクロール (利用者・プログラム・
+     * 補正のどれでも) はそのピルをすぐ隠し (`canScrollTowardEdge`)、1px を超える利用者のスクロールは向きから `pickEdgePill` が
+     * 選ぶピルを出して (どちらの端へもスクロールできなければ出さない) 自動非表示のタイマーを掛け直す。
      *
-     * ペインのスクロールイベントを処理。
+     * @param newPosition - Pane position after the scroll (px) / スクロール後のペイン位置 (px)
+     * @param prevPosition - Pane position before the scroll (px) / スクロール前のペイン位置 (px)
      */
     const handleScroll = useCallback(
         (newPosition: number, prevPosition: number) => {
@@ -2566,30 +2675,31 @@ const VirtualScrollInner = <T,>(
 
             updateScrollPositionImmediate(newPosition)
 
-            if (enableScrollToTopBottomButtons) {
-                if (isProgrammatic || isCompensating) {
-                    return
-                }
-
-                const diff = newPosition - prevPosition
-                Logger.debug("[VirtualScroll] Scroll diff:", diff, "New:", newPosition, "Prev:", prevPosition)
-                if (Math.abs(diff) > 1) {
-                    const direction = diff > 0 ? "down" : "up"
-                    setScrollDirection(direction)
-                    setShowScrollButtons(true)
-                    Logger.debug("[VirtualScroll] Showing scroll buttons. Direction:", direction)
+            if (!enableScrollToTopBottomButtons) {
+                return
+            }
+            // 最大位置は確定済みの寸法でなく今の木から測る。補正のスクロールは確定前の新しい寸法でクランプされるため
+            const maxScrollPosition = Math.max(0, fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom - viewportSize)
+            const shownPill = shownEdgePillRef.current
+            // 端に着いたピルはもう何も動かさず、焦点を受けた端の行を覆うだけなので、着いた経路を問わず自動非表示を待たずに隠す
+            if (shownPill !== null && !canScrollTowardEdge(shownPill, newPosition, maxScrollPosition)) {
+                hideEdgePill()
+            }
+            if (isProgrammatic || isCompensating) {
+                return
+            }
 
-                    if (scrollButtonTimerRef.current) {
-                        clearTimeout(scrollButtonTimerRef.current)
-                    }
-                    scrollButtonTimerRef.current = setTimeout(() => {
-                        setShowScrollButtons(false)
-                        Logger.debug("[VirtualScroll] Hiding scroll buttons")
-                    }, 2000)
+            const diff = newPosition - prevPosition
+            Logger.debug("[VirtualScroll] Scroll diff:", diff, "New:", newPosition, "Prev:", prevPosition)
+            if (Math.abs(diff) > 1) {
+                const pill = pickEdgePill(diff > 0 ? "bottom" : "top", newPosition, maxScrollPosition)
+                if (pill !== null) {
+                    showEdgePill(pill)
+                    Logger.debug("[VirtualScroll] Showing scroll-to-edge pill:", pill)
                 }
             }
         },
-        [updateScrollPositionImmediate, forgetAlignedEdge, enableScrollToTopBottomButtons, itemCount],
+        [updateScrollPositionImmediate, forgetAlignedEdge, enableScrollToTopBottomButtons, itemCount, fenwickTree, resolvedInsets.top, resolvedInsets.bottom, viewportSize, hideEdgePill, showEdgePill],
     )
 
     // レンダリング範囲を計算
@@ -2834,10 +2944,14 @@ const VirtualScrollInner = <T,>(
 
     /**
      * Renders the auto-hiding top/bottom pill overlay (texts from the resolved `scrollToTop` /
-     * `scrollToBottom` labels), neutralized while hidden.
+     * `scrollToBottom` labels), neutralized while hidden. It draws one pill — the one the last user
+     * scroll picked (`edgePill`; the Bottom pill before any) — which shows only while the pane can
+     * still scroll toward that pill's edge (`handleScroll` and the size check hide it at the edge).
      *
      * 自動非表示の先頭/末尾ピルのオーバーレイ (文言は解決済みラベルの `scrollToTop` /
-     * `scrollToBottom`) を描画し、非表示中は無効化する処理。
+     * `scrollToBottom`) を描画し、非表示中は無効化する処理。描くピルは 1 つで、最後の利用者の
+     * スクロールが選んだもの (`edgePill`。スクロールの前は Bottom ピル)。ペインがまだそのピルの端の
+     * 方へスクロールできる間だけ見える (端に着くと `handleScroll` と大きさの照合が隠す)。
      *
      * ❗ 非表示は `opacity: 0` で表現するため、要素は DOM に残り続ける (フェードのために
      * アンマウントしない)。`opacity` はフォーカス可能性に影響せず、CSS の `pointer-events: none`
@@ -2868,8 +2982,8 @@ const VirtualScrollInner = <T,>(
             return null
         }
 
-        const isVisible = showScrollButtons && scrollDirection !== null
-        const isTop = scrollDirection === "up"
+        const isVisible = showScrollButtons
+        const isTop = edgePill === "top"
         const pillTabIndex = isVisible && !scrollChromeIsPointerOnly ? 0 : -1
 
         return (
@@ -2886,7 +3000,7 @@ const VirtualScrollInner = <T,>(
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
                                 scrollToIndex(0)
-                                setShowScrollButtons(false)
+                                hideEdgePill()
                             }}>
                             {resolvedLabels.scrollToTop}
                         </button>
@@ -2903,7 +3017,7 @@ const VirtualScrollInner = <T,>(
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
                                 scrollToIndex(itemCount - 1)
-                                setShowScrollButtons(false)
+                                hideEdgePill()
                             }}>
                             {resolvedLabels.scrollToBottom}
                         </button>
@@ -2911,7 +3025,7 @@ const VirtualScrollInner = <T,>(
                 )}
             </div>
         )
-    }, [enableScrollToTopBottomButtons, scrollChromeIsPointerOnly, showScrollButtons, scrollDirection, scrollToIndex, itemCount, resolvedLabels])
+    }, [enableScrollToTopBottomButtons, scrollChromeIsPointerOnly, showScrollButtons, edgePill, scrollToIndex, hideEdgePill, itemCount, resolvedLabels])
 
     // 量子化アンカー (fix: LayoutUnit/f32 精度対策)。行 top はコンテンツ絶対座標そのままではなく
     // 「絶対座標 - アンカー」で描画し、ラッパー側 translateY にアンカーを足し戻す。
@@ -3031,13 +3145,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) {
@@ -3101,7 +3214,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)
@@ -3235,21 +3348,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,
@@ -3258,6 +3396,18 @@ const VirtualScrollInner = <T,>(
     )
 
     const totalContentHeight = fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom
+    const paneMaxScrollPosition = Math.max(0, totalContentHeight - viewportSize)
+
+    useLayoutEffect(() => {
+        // 目的: 中身や表示域の大きさが変わると、位置が動かなくても最大位置が動いてペインが端に着く (中身が表示域に収まれば両端)。
+        // スクロールの知らせが来ないこの着き方でも、見えているピルを描画の前に隠す。端から離れても出し直さないのは、ピルを出すのが
+        // 利用者のスクロールだけだから (下に行が足されても、Bottom ピルは次の利用者のスクロールで出る)
+        // 依存関係: paneMaxScrollPosition, hideEdgePill
+        const shownPill = shownEdgePillRef.current
+        if (shownPill !== null && !canScrollTowardEdge(shownPill, latestScrollPositionRef.current, paneMaxScrollPosition)) {
+            hideEdgePill()
+        }
+    }, [paneMaxScrollPosition, hideEdgePill])
 
     // ライブリージョン無効時はペインをそのまま根要素として返す (既存消費者の DOM 形状を変えない)
     const pane = (

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/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/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 は張り直さず、現状この分岐が