@aiquants/virtualscroll 3.11.1 → 3.11.2

package/dist/residualQuantizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"residualQuantizer.d.ts","sourceRoot":"","sources":["../src/residualQuantizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACnC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,wBAAwB,KAAG,iBAmC3E,CAAA"}
+{"version":3,"file":"residualQuantizer.d.ts","sourceRoot":"","sources":["../src/residualQuantizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACnC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,wBAAwB,KAAG,iBAiD3E,CAAA"}

package/dist/useGridTapScroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGridTapScroll.d.ts","sourceRoot":"","sources":["../src/useGridTapScroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAEvG,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAG5F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAalD,4MAA4M;AAC5M,MAAM,MAAM,sBAAsB,GAAG;IACjC,uIAAuI;IACvI,OAAO,EAAE,OAAO,CAAA;IAChB,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAA;IACnB,gIAAgI;IAChI,YAAY,EAAE,wBAAwB,CAAA;IACtC,6IAA6I;IAC7I,YAAY,EAAE,wBAAwB,CAAA;IACtC,sHAAsH;IACtH,UAAU,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAA;IAC1D,gDAAgD;IAChD,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,mJAAmJ;IACnJ,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,oVAAoV;IACpV,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,8YAA8Y;IAC9Y,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,2HAA2H;IAC3H,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,mLAAmL;IACnL,mBAAmB,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IACzC,qKAAqK;IACrK,gBAAgB,EAAE,OAAO,CAAA;IACzB,4JAA4J;IAC5J,gBAAgB,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG;IACjC,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAA;IACpB,qGAAqG;IACrG,yBAAyB,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACpE,4HAA4H;IAC5H,kBAAkB,EAAE,KAAK,CAAC,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;CACpE,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,KAAG,sBAuQjE,CAAA"}
+{"version":3,"file":"useGridTapScroll.d.ts","sourceRoot":"","sources":["../src/useGridTapScroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAEvG,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAG5F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAalD,4MAA4M;AAC5M,MAAM,MAAM,sBAAsB,GAAG;IACjC,uIAAuI;IACvI,OAAO,EAAE,OAAO,CAAA;IAChB,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAA;IACnB,gIAAgI;IAChI,YAAY,EAAE,wBAAwB,CAAA;IACtC,6IAA6I;IAC7I,YAAY,EAAE,wBAAwB,CAAA;IACtC,sHAAsH;IACtH,UAAU,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAA;IAC1D,gDAAgD;IAChD,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,mJAAmJ;IACnJ,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,oVAAoV;IACpV,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,8YAA8Y;IAC9Y,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,2HAA2H;IAC3H,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,mLAAmL;IACnL,mBAAmB,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IACzC,qKAAqK;IACrK,gBAAgB,EAAE,OAAO,CAAA;IACzB,4JAA4J;IAC5J,gBAAgB,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG;IACjC,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAA;IACpB,qGAAqG;IACrG,yBAAyB,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACpE,4HAA4H;IAC5H,kBAAkB,EAAE,KAAK,CAAC,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;CACpE,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,KAAG,sBAiSjE,CAAA"}

package/dist/useWheelBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useWheelBridge.d.ts","sourceRoot":"","sources":["../src/useWheelBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;CAC7C,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,EAAE,UAAU,kBAAkB,KAAG,WAAW,CAAC,WAAW,CA+DjI,CAAA"}
+{"version":3,"file":"useWheelBridge.d.ts","sourceRoot":"","sources":["../src/useWheelBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;CAC7C,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,EAAE,UAAU,kBAAkB,KAAG,WAAW,CAAC,WAAW,CA6EjI,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "3.11.1",
+  "version": "3.11.2",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"
@@ -29,6 +29,7 @@
     "src",
     "!src/**/*.spec.ts",
     "!src/**/*.spec.tsx",
+    "!src/test-helpers/**",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -103,6 +104,8 @@
     "check:coverage": "node scripts/ratchet-coverage.mjs",
     "coverage:ratchet": "node scripts/ratchet-coverage.mjs --write",
     "coverage:adopt": "node scripts/ratchet-coverage.mjs --adopt",
+    "check:docstrings": "node scripts/ratchet-docstrings.mjs",
+    "docstrings:ratchet": "node scripts/ratchet-docstrings.mjs --write",
     "lint": "biome check src tests",
     "lint:fix": "biome check --write src tests",
     "format": "biome format --write src tests",

package/src/ScrollBar.tsx

@@ -379,7 +379,15 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
             mainSizeKey: "width",
             crossSizeKey: "height",
             thumbTranslateFunction: "translateX",
+            /**
+             * Picks the component of a pointer drag along the horizontal bar.
+             * ポインタのドラッグの、横のバーに沿う成分を選ぶ処理。
+             */
             selectDelta: (deltaX: number, _deltaY: number) => deltaX,
+            /**
+             * Reads a pointer's coordinate along the horizontal bar.
+             * ポインタの、横のバーに沿う座標を読む処理。
+             */
             getPointerCoordinate: ({ clientX }) => clientX,
             arrowIcons: ["◀", "▶"],
             directionClass: "aqvs-scrollbar-horizontal",
@@ -391,7 +399,15 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
         mainSizeKey: "height",
         crossSizeKey: "width",
         thumbTranslateFunction: "translateY",
+        /**
+         * Picks the component of a pointer drag along the vertical bar.
+         * ポインタのドラッグの、縦のバーに沿う成分を選ぶ処理。
+         */
         selectDelta: (_deltaX: number, deltaY: number) => deltaY,
+        /**
+         * Reads a pointer's coordinate along the vertical bar.
+         * ポインタの、縦のバーに沿う座標を読む処理。
+         */
         getPointerCoordinate: ({ clientY }) => clientY,
         arrowIcons: ["▲", "▼"],
         directionClass: "aqvs-scrollbar-vertical",
@@ -476,44 +492,55 @@ const useArrowAutoRepeat = ({ canUseArrowButtons, enableArrowButtons, keyboardOp
     }, [clearArrowTimers])
 
     const handleArrowPointerDown = useCallback(
-        (direction: 1 | -1) => (event: React.PointerEvent<HTMLButtonElement>) => {
-            if (!canUseArrowButtons) {
-                return
-            }
-            if (event.cancelable) {
-                event.preventDefault()
-            }
-            event.stopPropagation()
-            resetTapScroll()
-            clearArrowTimers()
-            scrollByStep(direction)
-            arrowHoldTimeoutRef.current = window.setTimeout(() => {
-                arrowHoldIntervalRef.current = window.setInterval(() => {
-                    scrollByStep(direction)
-                }, ARROW_HOLD_INTERVAL)
-            }, ARROW_HOLD_DELAY)
-            // ボタンが disabled 化 / ウィンドウ blur で pointerup を取りこぼしてもリピートを確実に止める保険。
-            const release = () => clearArrowTimers()
-            globalReleaseRef.current = release
-            window.addEventListener("pointerup", release)
-            window.addEventListener("pointercancel", release)
-            window.addEventListener("blur", release)
-        },
+        (direction: 1 | -1) =>
+            /**
+             * Handles a press on an arrow: one step at once, then a repeat while the press is held, ended by the release anywhere,
+             * a cancel or the window losing focus.
+             * 矢印の押下を扱う処理。すぐに 1 段進め、押している間は繰り返し、どこでの解放・取り消し・ウィンドウのフォーカスの喪失で止める。
+             */
+            (event: React.PointerEvent<HTMLButtonElement>) => {
+                if (!canUseArrowButtons) {
+                    return
+                }
+                if (event.cancelable) {
+                    event.preventDefault()
+                }
+                event.stopPropagation()
+                resetTapScroll()
+                clearArrowTimers()
+                scrollByStep(direction)
+                arrowHoldTimeoutRef.current = window.setTimeout(() => {
+                    arrowHoldIntervalRef.current = window.setInterval(() => {
+                        scrollByStep(direction)
+                    }, ARROW_HOLD_INTERVAL)
+                }, ARROW_HOLD_DELAY)
+                // ボタンが disabled 化 / ウィンドウ blur で pointerup を取りこぼしてもリピートを確実に止める保険。
+                const release = () => clearArrowTimers()
+                globalReleaseRef.current = release
+                window.addEventListener("pointerup", release)
+                window.addEventListener("pointercancel", release)
+                window.addEventListener("blur", release)
+            },
         [canUseArrowButtons, clearArrowTimers, resetTapScroll, scrollByStep],
     )
 
     const handleArrowKeyDown = useCallback(
-        (direction: 1 | -1) => (event: React.KeyboardEvent<HTMLButtonElement>) => {
-            // ポインタ専用のバーは支援技術から隠れていて、キーボードのスクロールはホストが持つ。スクリプトがフォーカスした矢印でも
-            // キーを受けると、隠れた部品がホストのキー操作と重なって一覧を動かす
-            if (!(enableArrowButtons && keyboardOperable)) {
-                return
-            }
-            if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
-                event.preventDefault()
-                scrollByStep(direction)
-            }
-        },
+        (direction: 1 | -1) =>
+            /**
+             * Handles Enter and Space on a focused arrow as one step, unless the bar is pointer-only or its arrows are disabled.
+             * フォーカスした矢印での Enter と Space を 1 段として扱う処理 (バーがポインタ専用か矢印が無効なら何もしない)。
+             */
+            (event: React.KeyboardEvent<HTMLButtonElement>) => {
+                // ポインタ専用のバーは支援技術から隠れていて、キーボードのスクロールはホストが持つ。スクリプトがフォーカスした矢印でも
+                // キーを受けると、隠れた部品がホストのキー操作と重なって一覧を動かす
+                if (!(enableArrowButtons && keyboardOperable)) {
+                    return
+                }
+                if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
+                    event.preventDefault()
+                    scrollByStep(direction)
+                }
+            },
         [enableArrowButtons, keyboardOperable, scrollByStep],
     )
 

package/src/ScrollPane.tsx

@@ -1064,12 +1064,28 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         useImperativeHandle(
             ref,
             () => ({
+                /**
+                 * Stops any inertia, then jumps to a pane position (clamped); returns the applied position.
+                 * 慣性を止めてからペインの位置へ跳ぶ (クランプする) 処理。当てた位置を返す。
+                 */
                 scrollTo: (pos, dimsOverride) => {
                     stopInertia()
                     return scrollTo(pos, dimsOverride)
                 },
+                /**
+                 * Reads the pane position (synchronously fresh, from the position ref).
+                 * ペインの位置を読む処理 (位置の ref から読むので同期で最新)。
+                 */
                 getScrollPosition: () => scrollPositionRef.current,
+                /**
+                 * Reads the content size the pane was given.
+                 * ペインが受け取った中身の寸法を読む処理。
+                 */
                 getContentSize: () => contentSize,
+                /**
+                 * Reads the viewport size the pane uses (given or measured).
+                 * ペインが使う表示域の寸法 (与えられたか測ったもの) を読む処理。
+                 */
                 getViewportSize: () => viewportSize,
                 applyWheel,
             }),

package/src/TapScrollCircle.tsx

@@ -360,9 +360,17 @@ export const TapScrollCircle = memo(
         useImperativeHandle(
             ref,
             () => ({
+                /**
+                 * Returns the circle to its resting state and reports it through `onDragChange`.
+                 * サークルを静止の状態へ戻し、`onDragChange` で知らせる処理。
+                 */
                 reset: () => {
                     resetState(true)
                 },
+                /**
+                 * Reads the circle's root element (null while it is not mounted).
+                 * サークルのルートの要素を読む処理 (マウントしていない間は null)。
+                 */
                 getElement: () => rootRef.current,
             }),
             [resetState],

package/src/VirtualGrid.tsx

@@ -1038,6 +1038,10 @@ const VirtualGridInner = <T,>(
         (root: HTMLDivElement) => {
             rootRef.current = root
             if (hasExplicitViewport) {
+                /**
+                 * Detaches the root (the given viewport needs no observer).
+                 * ルートを外す処理 (与えられたビューポートには監視が要らない)。
+                 */
                 return () => {
                     rootRef.current = null
                 }
@@ -1059,6 +1063,10 @@ const VirtualGridInner = <T,>(
             measure()
             const observer = new ResizeObserver(measure)
             observer.observe(root)
+            /**
+             * Detaches the root and stops the observer.
+             * ルートを外し、監視を止める処理。
+             */
             return () => {
                 observer.disconnect()
                 rootRef.current = null
@@ -1806,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
@@ -1822,6 +1836,11 @@ 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) => {
                 // 縦の差分はタップの駆動と同じ継ぎ目 (applyVy) で当て、適用と鏡像の同期を 2 通りに書かない
                 const y = delta.y !== undefined && delta.y !== 0 ? applyVy(delta.y) : vyRef.current
@@ -1832,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) {
@@ -1856,7 +1881,18 @@ const VirtualGridInner = <T,>(
                     }
                 }
             },
+            /**
+             * 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
@@ -1883,11 +1919,26 @@ const VirtualGridInner = <T,>(
                 // 行はシフト空間 → フル行空間へ +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 の格納庫は
@@ -1901,12 +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 が旧上限でクランプしないため)。幅が変われば木の版数が進み、
                 // 窓キー不変でもセル配置を失効させる (バッチループは 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,
@@ -1920,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 翻訳して委譲

package/src/VirtualScroll.tsx

@@ -1124,10 +1124,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 +1243,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 +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
 
@@ -1329,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
@@ -1575,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()
@@ -3031,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) {
@@ -3101,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)
@@ -3235,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/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])