@aiquants/virtualscroll 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/ScrollPane.tsx

@@ -234,7 +234,16 @@ const toggleListeners = (target: HTMLElement | Window, entries: ListenerEntry[],
 }
 
 export type ScrollPaneHandle = {
-    scrollTo: (newPosition: number | ((prev: number) => number)) => number
+    /**
+     * Jumps to a position, clamped against the last-committed dims (or an explicit override).
+     * 位置へジャンプする。クランプは**最後に commit された寸法** (または明示指定) に対して行う。
+     *
+     * `dimsOverride` は「commit より新しい寸法を知っている呼び出し元」専用の口である
+     * (例: Fenwick 木を同期更新した直後のレイアウトシフト補正は、まだ commit されていない
+     * 木の合計高さでクランプしたい)。通常の呼び出しでは指定しないこと — 指定を誤ると
+     * 画面に出ていない寸法でクランプされ、A-1 の汚染を自分の手で再現することになる。
+     */
+    scrollTo: (newPosition: number | ((prev: number) => number), dimsOverride?: { contentSize: number; viewportSize: number }) => number
     getScrollPosition: () => number
     getContentSize: () => number
     getViewportSize: () => number
@@ -477,12 +486,20 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         // contentSize と viewportSize を ref として保持
         // const sizeRef = useRef({ contentSize, viewportSize })
 
-        // ❗ render 本体で代入する。layout effect へ移すと、サイズ変更と同じコミット内で走る
-        // 他の layout effect からの scrollTo が 1 コミット古い寸法でクランプされ、タップスクロールの
-        // 走破が短くなる (実機 E2E の等速性テストがサンプル数不足で落ちる形で退行が出る)。
-        // 既知の代償は下の wheelPolicyRef のコメントを参照。
+        // ❗ **render 本体では代入しない (layout effect のみ = 常に「最後に commit された寸法」)。**
+        // render 中に書くと、中断されたトランジションの**コミットされなかった寸法**が残り、
+        // 保留中のホイール/ジャンプが画面に出ていない寸法でクランプされる (実測: 保留中の縮小で
+        // 一覧が先頭へ飛ぶ / ホイールが死ぬ。transitionClamp.spec.tsx が固定)。
+        //
+        // かつて「layout effect 化はタップスクロール E2E を退行させる」と記録されていたが、
+        // 8 回 x 3 系列の A/B/A 対照実験で**反証済み** (失敗は書き込み位置と無関係の
+        // コールドスタート負荷フレークで、両変種とも 6-7/8 で同率に失敗した)。加えて全計 1,893 回の
+        // scrollTo クランプ監査で committed 値と render 新値の食い違いは 0 件 — 同 commit 内で
+        // 新値を要する呼び出し元は存在しない (子 effect は本 effect より先に走るが、その窓に
+        // scrollTo 呼び出し元は無いことを確認済み)。commit より新しい寸法が要る唯一の呼び出し元
+        // (レイアウトシフト補正) は「committed + 今適用した delta」を `dimsOverride` で明示的に
+        // 渡す (木合計は渡さない — 木は破棄された WIP render にも変異される共有物)。
         const sizeRef = useRef({ contentSize, viewportSize })
-        sizeRef.current = { contentSize, viewportSize }
 
         const isScrollable = useMemo(() => contentSize > viewportSize, [contentSize, viewportSize])
 
@@ -520,8 +537,18 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         // )
 
         const scrollTo = useCallback(
-            (newPosition: number | ((prev: number) => number)) => {
-                const { contentSize: currentContentSize, viewportSize: currentViewportSize } = sizeRef.current
+            (newPosition: number | ((prev: number) => number), dimsOverride?: { contentSize: number; viewportSize: number }) => {
+                // 既定は「最後に commit された寸法」。dimsOverride は commit より新しい寸法を
+                // 知っている呼び出し元 (レイアウトシフト補正) だけが渡す。
+                // ❗ 非有限の override は警告して無視する (position の NaN ガードと同じ姿勢)。
+                // NaN の contentSize は「スクロール不能」判定へ落ち、位置を 0 へ強制 +
+                // onScroll(0) まで発火してしまう
+                let effectiveDims = dimsOverride ?? sizeRef.current
+                if (dimsOverride && !(Number.isFinite(dimsOverride.contentSize) && Number.isFinite(dimsOverride.viewportSize))) {
+                    Logger.warn("[ScrollPane] scrollTo received non-finite dimsOverride; falling back to the committed dims", { dimsOverride })
+                    effectiveDims = sizeRef.current
+                }
+                const { contentSize: currentContentSize, viewportSize: currentViewportSize } = effectiveDims
                 const currentIsScrollable = currentContentSize > currentViewportSize
                 const prevPosition = scrollPositionRef.current
 
@@ -743,18 +770,14 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
 
         // ホイール適用の方針値。保持されたハンドル越しの呼び出しでも凍結させないため ref で持つ。
         //
-        // ❗ **代入のタイミングは `sizeRef` と必ず揃える。** 片方だけを layout effect にすると、
-        // 中断されたトランジション中に `applyWheel` は「スクロール可能」と判断して消費する一方、
-        // `scrollTo` は 1 コミット古い寸法でクランプして 0 を返す、という最悪の組み合わせになる
-        // (実測: 5,000 行の一覧が 1 ノッチで先頭へ飛び、以後 0 に貼り付く)。
-        //
-        // ❗ **既知の限界 (未修正)**: render 本体での ref 書き込みは、中断されたトランジションで
-        // **コミットされなかった値**を残す。その間のホイールは画面に出ていない寸法で判断されるため、
-        // 「スクロール可能な一覧なのにホイールが効かない」状態が保留中だけ起きる。両 ref を
-        // layout effect へ移すのが筋だが、それだけではタップスクロールの走破が 1 コミット遅れて
-        // 短くなる退行が出る (実機 E2E で実証済み)。恒久対応にはクランプ経路の見直しが必要。
+        // ❗ **代入のタイミングは `sizeRef` と必ず揃える (どちらも layout effect のみ)。**
+        // 片方だけ render 本体に残すと、中断されたトランジション中に `applyWheel` と `scrollTo` が
+        // 別々の世界の寸法で判断する最悪の組み合わせになる。
         const wheelPolicyRef = useRef({ isScrollable, viewportSize, wheelSpeedMultiplier })
-        wheelPolicyRef.current = { isScrollable, viewportSize, wheelSpeedMultiplier }
+        useLayoutEffect(() => {
+            // sizeRef と同じ理由で「最後に commit された値」だけを保持する (A-1。sizeRef のコメント参照)
+            wheelPolicyRef.current = { isScrollable, viewportSize, wheelSpeedMultiplier }
+        }, [isScrollable, viewportSize, wheelSpeedMultiplier])
 
         /**
          * Applies one wheel event with the pane's own rules and reports whether it was consumed.
@@ -905,9 +928,9 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         useImperativeHandle(
             ref,
             () => ({
-                scrollTo: (pos) => {
+                scrollTo: (pos, dimsOverride) => {
                     stopInertia()
-                    return scrollTo(pos)
+                    return scrollTo(pos, dimsOverride)
                 },
                 getScrollPosition: () => scrollPositionRef.current,
                 getContentSize: () => contentSize,

package/src/VirtualScroll.tsx

@@ -1305,7 +1305,7 @@ const VirtualScrollInner = <T,>(
      * 乖離した場合 (同一同期バッチ内の旧 contentSize によるクランプ) は、新 contentSize
      * コミット後の補正再発行を予約。
      */
-    const issueCompensationScroll = useCallback((targetPosition: number): number => {
+    const issueCompensationScroll = useCallback((targetPosition: number, appliedDelta = 0): number => {
         const pane = scrollPaneRef.current
         if (!pane) {
             return targetPosition
@@ -1313,7 +1313,20 @@ const VirtualScrollInner = <T,>(
         // クランプで位置が変化しない場合 onScroll は発火しない。事前位置と比較して増分を戻すために保持する
         const beforePosition = pane.getScrollPosition()
         isCompensatingRef.current += 1
-        const appliedPosition = pane.scrollTo(targetPosition)
+        // ❗ クランプは **「committed 寸法 + 今適用した delta」**で行う (dimsOverride)。この補正は木を
+        // 同期更新した**直後・commit 前**に走るため、ペインの committed sizeRef は必ず 1 commit 古く、
+        // 既定のままだと旧最大値でクランプされ二段補正 (§8.6) の再発行に頼ることになる。
+        //
+        // ❗ `fenwickTree.getTotal()` ではなく committed + delta を使う。木は**破棄された WIP render
+        // にも変異される共有物** (保留トランジション中は未 commit の行数の合計を返すことを
+        // transitionClamp.spec.tsx の前提アサートで実証済み) であり、木合計でのクランプは
+        // fenwick の並行安全設計の内部タイミングに依存する。committed + delta は定義から
+        // 「この補正が保とうとしている committed 空間 + 今適用した変化」そのものであり、
+        // WIP 変異のタイミングと無関係に正しい (通常時は木合計と同値で、一段目がそのまま
+        // 目標へ届き、二段補正はバックストップとして休眠する)
+        const freshContentSize = pane.getContentSize() + appliedDelta
+        const freshViewportSize = pane.getViewportSize()
+        const appliedPosition = pane.scrollTo(targetPosition, { contentSize: freshContentSize, viewportSize: freshViewportSize })
         if (appliedPosition === beforePosition) {
             // onScroll 不発: 補正カウンタの増分を巻き戻し、次の手動スクロールが補正扱いされるのを防ぐ
             isCompensatingRef.current = Math.max(0, isCompensatingRef.current - 1)
@@ -1507,7 +1520,7 @@ const VirtualScrollInner = <T,>(
                 // 同一同期バッチ内では ScrollPane の sizeRef が旧 contentSize のままのため、scrollTo は
                 // 旧最大値でクランプされ得る。issueCompensationScroll がカウンタのリークを防ぎつつ乖離時の
                 // 再発行を予約し、論理位置 (latestScrollPositionRef) には補正目標を保持して二段目の収束先とする。
-                issueCompensationScroll(newPosition)
+                issueCompensationScroll(newPosition, delta)
                 updateScrollPositionImmediate(newPosition, { immediate: true })
                 Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (manual update)", { from: currentPanePosition, to: newPosition, causedByIndex: safeIndex, delta, activeVisibleStartIndex })
             }
@@ -1746,7 +1759,18 @@ const VirtualScrollInner = <T,>(
 
             // If manual scroll (neither programmatic nor compensating), clear the pending anchor
             // This ensures that manual scrolling immediately detaches from any previous scroll target
-            if (!(isProgrammatic || isCompensating || isResizingRef.current)) {
+            // ❗ isResizingRef は render 本体で立つ (in-commit の §9 クランプ連鎖が読むため必須) が、
+            // 中断されたトランジションの render でも立ってしまい、commit が無いので降りない。
+            // このクロージャの itemCount は **commit を通ってしか届かない** (破棄 render のクロージャは
+            // committed ツリーに残らない) ため、ref と閉じ込め値の照合で「committed な resize か」を
+            // 判別できる。保留中 (ref=新 / クロージャ=旧) は不一致 → 手動スクロール扱いでアンカーが
+            // 正しく外れる。resize の commit 内連鎖 (ref=新 / クロージャ=新) は一致 → 従来どおり。
+            // ❗ 純粋な同数往復 (500→300 保留→500 bailout) は照合が正しく効く (bailout は ref の
+            // 再前進も防ぐため不一致になる)。残存する盲点は「戻りに別 state 変更が同伴して一覧が
+            // 再 render される」形のみ (ref が committed と同値へ前進し、同伴 commit ではリセット
+            // 経路が走らない)。仕様書 §8.4 の既知の盲点を参照
+            const isCommittedResize = isResizingRef.current && prevItemCountRef.current === itemCount
+            if (!(isProgrammatic || isCompensating || isCommittedResize)) {
                 pendingVisibleStartIndexRef.current = null
             }
 
@@ -1775,7 +1799,7 @@ const VirtualScrollInner = <T,>(
                 }
             }
         },
-        [updateScrollPositionImmediate, enableScrollToTopBottomButtons],
+        [updateScrollPositionImmediate, enableScrollToTopBottomButtons, itemCount],
     )
 
     // レンダリング範囲を計算
@@ -2189,7 +2213,7 @@ const VirtualScrollInner = <T,>(
                     const newPosition = panePosition + shiftAmount
                     // updateItemSize と同型: scrollTo は旧 contentSize でクランプされ得るため、
                     // issueCompensationScroll でリークを防ぎつつ、乖離時は contentSize 同期 effect で再発行する。
-                    issueCompensationScroll(newPosition)
+                    issueCompensationScroll(newPosition, shiftAmount)
                     updateScrollPositionImmediate(newPosition, { immediate: true })
                     Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (auto update)", { from: panePosition, to: newPosition, shiftAmount })
                 } else if (panePosition !== latestScrollPositionRef.current) {