@aiquants/virtualscroll 3.10.0 → 3.11.0

package/src/VirtualScroll.tsx

@@ -1,10 +1,10 @@
-import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
+import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useReducer, 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 { keepFocusOnPress, minmax } from "./utils.ts"
+import { getAxisScale, keepFocusOnPress, minmax } from "./utils.ts"
 
 /**
  * Represents the current state of the rendered range and scroll metrics.
@@ -140,18 +140,41 @@ export type VirtualScrollHandle = {
     /**
      * Scrolls to a specific item index, landing exactly on the aligned position (clamped to the content). A `"top"`
      * (default) or `"bottom"` alignment is remembered at that position, so the device-pixel snap of the items wrapper
-     * keeps the aligned edge there (see the README's device-pixel snapping section).
+     * keeps the aligned edge there (see the README's device-pixel snapping section). `"top"`, `"bottom"` and `"center"`
+     * align to the viewport itself, and `offset` (px) is subtracted from the aligned position.
+     *
+     * `"nearest"` is the reveal, the rule focus moves and the row keyboard steps use too: it scrolls the least distance that
+     * brings the row wholly into the viewport, minus the edge a visible scroll-to-edge pill covers (from that edge to the
+     * pill's far side), and does nothing when the row already lies wholly inside. A row above lands with its top at the
+     * band's top, a row below with its bottom at the band's bottom, and a row taller than the band with its top at the
+     * band's top; the landing is kept like a `"top"` / `"bottom"` alignment, so a pill that hides later moves nothing.
+     * `"nearest"` takes no `offset`.
      *
      * 指定したアイテムインデックスへスクロールする処理。揃えた位置 (中身の範囲へクランプ) へ厳密に着地する。`"top"` (既定) と
      * `"bottom"` の揃えはその位置で覚えるので、そこでは行ラッパーの装置の画素への揃えが揃えた端を守る (README の装置の画素への
-     * 揃えの節を参照)。
+     * 揃えの節を参照)。`"top"`・`"bottom"`・`"center"` は表示域そのものに揃え、`offset` (px) を揃えた位置から引く。
+     *
+     * `"nearest"` は見せる操作で、フォーカスの移動と行のキー移動も同じ規則を使う。行が表示域から、見えている端へ戻るピルが覆う
+     * 端 (その端からピルの向こう側まで) を除いた帯にまるごと入る最短の距離だけスクロールし、既にまるごと入っていれば何もしない。
+     * 上の行は上端を帯の上端へ、下の行は下端を帯の下端へ、帯より高い行は上端を帯の上端へ着地させ、着地は `"top"` / `"bottom"`
+     * の揃えと同じく保つので、後でピルが隠れても何も動かない。`"nearest"` は `offset` を取らない。
+     *
+     * @throws {RangeError} When `"nearest"` comes with an `offset` / `"nearest"` に `offset` を渡したとき
      */
-    scrollToIndex: (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number }) => void
+    scrollToIndex: (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number } | { align: "nearest"; offset?: never }) => void
     /** Gets the total height managed by the Fenwick Tree / Fenwick Tree で管理されている総高さを取得 */
     getFenwickTreeTotalHeight: () => number
     /** Gets the number of items in the Fenwick Tree / Fenwick Tree 内のアイテム数を取得 */
     getFenwickSize: () => number
-    /** Focuses an item at the specified index / 指定したインデックスのアイテムにフォーカス */
+    /**
+     * Focuses the row at the specified index (with `behaviorOptions.enableKeyboardNavigation`). With `ensureVisible` (default
+     * `true`) it first reveals the row like `scrollToIndex(index, { align: "nearest" })`, so a row a visible scroll-to-edge
+     * pill covers is brought out from under it; with `false` it focuses a rendered row without scrolling.
+     *
+     * 指定したインデックスの行へフォーカスする処理 (`behaviorOptions.enableKeyboardNavigation` のとき)。`ensureVisible` (既定
+     * `true`) では先に `scrollToIndex(index, { align: "nearest" })` と同じく行を見せるので、見えている端へ戻るピルが覆う行は
+     * その下から出る。`false` では描いてある行をスクロールせずにフォーカスする。
+     */
     focusItemAtIndex: (index: number, options?: { ensureVisible?: boolean }) => void
     /** Gets the current scroll range information / 現在のスクロール範囲情報を取得 */
     getRange: () => VirtualScrollRange
@@ -431,12 +454,13 @@ export type VirtualScrollProps<T> = {
     liveRegion?: VirtualScrollLiveRegionOptions
     /**
      * UI chrome locale of the built-in strings (default `"en"`): the scrollbar's accessible names
-     * (the bar, its thumb and its arrows), the scroll-to-edge pills and the empty-state text. Live-region wording is not affected (see
+     * (the bar, its thumb and its arrows), the scroll-to-edge pills and the empty-state text, and of the
+     * percentage the bar and its thumb carry as their value text. Live-region wording is not affected (see
      * {@link VirtualScrollLiveRegionOptions.format}). An unsupported value throws a RangeError at
      * render; no language negotiation happens.
-     * 内蔵文言 (スクロールバーのアクセシブルネーム — バー・つまみ・矢印 —、端スクロールピル、空状態文言) の UI クロームロケール
-     * (既定 `"en"`)。ライブリージョンの文言には影響しない ({@link VirtualScrollLiveRegionOptions.format}
-     * 参照)。非対応値は描画時に RangeError、言語ネゴシエーションなし。
+     * 内蔵文言 (スクロールバーのアクセシブルネーム — バー・つまみ・矢印 —、端スクロールピル、空状態文言) と、バーとつまみが
+     * 値の文字として持つ百分率の UI クロームロケール (既定 `"en"`)。ライブリージョンの文言には影響しない
+     * ({@link VirtualScrollLiveRegionOptions.format} 参照)。非対応値は描画時に RangeError、言語ネゴシエーションなし。
      */
     locale?: VirtualScrollLocale
     /**
@@ -698,6 +722,70 @@ const edgeOfAlignment = (align: "top" | "bottom" | "center" | undefined): Aligne
  */
 const canonicalAlignedEdge = (alignment: AlignedEdge | null): AlignedEdge | null => (alignment !== null && alignment.panePosition <= 0 ? null : alignment)
 
+/**
+ * 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
+ * `resolveRevealAlignment`.
+ *
+ * 行の上に描いたもの (見えている端へ戻るピル) が覆う表示域の部分。各端から覆うものの向こう側までの px。モジュールレベル
+ * export (バレル非公開)。`resolveRevealAlignment` の引数の型。
+ */
+export type ObscuredInsets = {
+    /** Covered px from the top edge / 上端から覆われた px */
+    readonly top: number
+    /** Covered px from the bottom edge / 下端から覆われた px */
+    readonly bottom: number
+}
+
+/** A viewport nothing covers / 何も覆わない表示域 */
+const NO_OBSCURED_INSETS: ObscuredInsets = Object.freeze({ top: 0, bottom: 0 })
+
+/**
+ * How a reveal lands a row: with its top at the top of the band the obscured insets leave (`"top"`) or with its bottom at the
+ * band's bottom (`"bottom"`), as the alignment and the `offset` `scrollToIndex` subtracts from the position aligned to the
+ * viewport's edge. Module-level export (NOT in the package barrel), the return type of `resolveRevealAlignment`.
+ *
+ * 見せる操作が行を着地させる揃え。覆われた部分を除いた帯の上端へ行の上端を (`"top"`)、帯の下端へ行の下端を (`"bottom"`) 置く
+ * 揃えと、表示域の端に揃えた位置から `scrollToIndex` が引く `offset`。モジュールレベル export (バレル非公開)。
+ * `resolveRevealAlignment` の戻り値の型。
+ */
+export type RevealAlignment = {
+    /** The edge of the band the row lands at / 行が着地する帯の端 */
+    readonly align: "top" | "bottom"
+    /** Px subtracted from the position aligned to the viewport's edge (the covered px; negative at the bottom) / 表示域の端に揃えた位置から引く px (覆われた px。下端では負) */
+    readonly offset: number
+}
+
+/**
+ * Resolves the reveal of a row — the one rule of `scrollToIndex` with `align: "nearest"`, of `focusItemAtIndex` and of the
+ * row keyboard steps: the least scroll that brings the row wholly into the band of the viewport the obscured insets leave.
+ * A row above the band lands with its top at the band's top, a row below with its bottom at the band's bottom, and a row
+ * taller than the band with its top at the band's top. A row within `EDGE_POSITION_TOLERANCE` of the band counts as inside.
+ * Module-level export (NOT in the package barrel).
+ *
+ * 行を見せる操作を解決する処理。`align: "nearest"` の `scrollToIndex`・`focusItemAtIndex`・行のキー移動に共通のただ 1 つの
+ * 規則で、覆われた部分を除いた表示域の帯へ行をまるごと入れる最短のスクロール。帯より上の行は上端を帯の上端へ、下の行は
+ * 下端を帯の下端へ、帯より高い行は上端を帯の上端へ着地させる。帯から `EDGE_POSITION_TOLERANCE` 以内の行は中にあるとみなす。
+ * モジュールレベル export (バレル非公開)。
+ *
+ * @param row - The row's logical top and bottom (px) / 行の論理上端と論理下端 (px)
+ * @param position - Logical scroll position (px) / 論理スクロール位置 (px)
+ * @param viewportSize - Viewport size (px) / 表示域の高さ (px)
+ * @param insets - The obscured insets / 覆われた部分
+ * @returns How to land the row, or `null` when it already lies wholly inside the band / 行の着地のさせ方 (既に帯にまるごと入っていれば `null`)
+ */
+export const resolveRevealAlignment = (row: { readonly top: number; readonly bottom: number }, position: number, viewportSize: number, insets: ObscuredInsets): RevealAlignment | null => {
+    const bandTop = position + insets.top
+    const bandBottom = position + viewportSize - insets.bottom
+    if (row.top >= bandTop - EDGE_POSITION_TOLERANCE && row.bottom <= bandBottom + EDGE_POSITION_TOLERANCE) {
+        return null
+    }
+    if (row.top < bandTop || row.bottom - row.top > bandBottom - bandTop) {
+        return { align: "top", offset: insets.top }
+    }
+    return { align: "bottom", offset: -insets.bottom }
+}
+
 /**
  * Chooses the edge the items-wrapper translate keeps when it is snapped to the device-pixel grid
  * (`snapToDevicePixelGrid`), so that aligned content never loses part of its edge gutter to the snap:
@@ -756,6 +844,8 @@ type ItemsWrapperProps = {
     readonly snapEdge: DevicePixelSnapEdge
     /** The rendered rows and the bottom inset / 描いた行と下のインセット */
     readonly children: ReactNode
+    /** Receives the boundary box, whose top is the top of the viewport (the reveals measure a visible pill against it) / 境界の箱を受け取る ref。箱の上端は表示域の上端 (見せる操作は見えているピルをこれに対して測る) */
+    readonly boundaryRef: React.Ref<HTMLDivElement>
 }
 
 /**
@@ -784,12 +874,12 @@ type ItemsWrapperProps = {
  * する 1 段の配置は、文書の根ではなくこの箱から始まる。行は箱から切り取られずにはみ出し (ペインの中身のスクロールできる範囲に
  * 数えないインクのはみ出し)、箱自身は当たり判定を取らない。
  *
- * @param props - The exact translate, the edge it keeps and the wrapped rows / 厳密な平行移動・守る端・包む行
+ * @param props - The exact translate, the edge it keeps, the wrapped rows and the boundary box's ref / 厳密な平行移動・守る端・包む行・境界の箱の ref
  * @returns The boundary box holding the wrapper element / ラッパーの要素を包む境界の箱
  * @throws {Error} When the wrapper attaches to a document without a window (see `usePaintingDevicePixelRatio`) / ウィンドウを持たない文書へ取り付いたとき (`usePaintingDevicePixelRatio` を参照)
  * @throws {RangeError} When the painting window reports a ratio that is not a finite number > 0 (see `snapToDevicePixelGrid`) / 描くウィンドウの比が 0 より大きい有限数でないとき (`snapToDevicePixelGrid` を参照)
  */
-const ItemsWrapper = ({ translateY, snapEdge, children }: ItemsWrapperProps) => {
+const ItemsWrapper = ({ translateY, snapEdge, children, boundaryRef }: ItemsWrapperProps) => {
     const { ratio, attach } = usePaintingDevicePixelRatio("[VirtualScroll] the items wrapper")
     // ❗ ラッパーは合成層なので、平行移動が装置の画素の端数を持つとブラウザは層ごと再標本化する (実測: -2440.5px で
     // 2px の輪郭・2px の隙間・2px の輪が 3+1+3 行に滲み、下辺の隙間が消える)。揃えるのは層の平行移動だけ —
@@ -801,7 +891,7 @@ const ItemsWrapper = ({ translateY, snapEdge, children }: ItemsWrapperProps) =>
     // ❗ ペインの中身は flex の子で配置の境界になれない。境界の箱を挟まないと、行を足し引きする 1 段の配置が毎回文書の根から
     // 始まる (実測: 4 倍の CPU で 1 段の配置の時間のすべてが文書の根から)
     return (
-        <div className="aqvs-items-boundary">
+        <div ref={boundaryRef} className="aqvs-items-boundary">
             <div ref={attach} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
                 {children}
             </div>
@@ -816,6 +906,17 @@ const ItemsWrapper = ({ translateY, snapEdge, children }: ItemsWrapperProps) =>
  */
 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.
  *
@@ -828,27 +929,106 @@ const toSafeBigInt = (value: number): bigint => {
 }
 
 /**
- * Computes rendering ranges for collections exceeding Number.MAX_SAFE_INTEGER.
- * Uses BigInt math to handle positions that cannot be represented by standard JavaScript numbers.
+ * The first visible row at a logical scroll position (`resolveVisibleStartRow`).
  *
- * Number.MAX_SAFE_INTEGER を超える巨大なコレクションに対して描画範囲を算出します。
- * 標準的な JavaScript 数値では表現できない位置を扱うために、内部計算には BigInt を使用します。
+ * 論理スクロール位置での先頭の可視行 (`resolveVisibleStartRow`)。
+ */
+export type VisibleStartRow = {
+    /** Index of the first visible row / 先頭の可視行の index */
+    readonly index: number
+    /** Logical top of that row (px); `position - top` is the part hidden above the viewport top / その行の論理上端 (px)。`position - top` がビューポートの上端より上に隠れた量 */
+    readonly top: number
+}
+
+/**
+ * The part of the Fenwick tree `resolveVisibleStartRow` reads.
  *
- * @param effectiveScrollPosition Clamped scroll position / 丸められた有効なスクロール位置
- * @param viewportSize Height of the viewport / ビューポートの高さ
- * @param overscanCount Number of items to render outside the viewport / ビューポート外に描画するアイテム数
- * @param itemSize Total number of items / 総アイテム数
- * @param getItemHeight Function to get height of an item / アイテムの高さを取得する関数
- * @param fenwickTree Fenwick Tree instance / Fenwick Tree インスタンス
- * @param totalHeight Total content height / コンテンツ総高さ
- * @param hasFiniteTotal Whether the total height is finite / 総高さが有限かどうか
+ * `resolveVisibleStartRow` が読む Fenwick 木の部分。
  */
-const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSize: number, overscanCount: number, itemSize: number, getItemHeight: (index: number) => number, fenwickTree: ReturnType<typeof useFenwickMapTree>, totalHeight: number, hasFiniteTotal: boolean) => {
+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
+ * (on both of its paths, `computeRenderingRangesHuge` included):
+ *
+ * - the row whose span contains the position: `top <= position < top + height`;
+ * - a row whose bottom equals the position lies entirely above the viewport, so the next row starts exactly there and is the
+ *   first visible row, at offset 0;
+ * - at the end, the last row stays the first visible row (the end clamp): when the position equals its bottom, and when the
+ *   position lies past the end of the content (a transient after the list shrinks, before the pane clamps).
+ *
+ * Module-level export (NOT in the package barrel).
+ *
+ * 先頭の可視行を、可視の先頭の境界の規則で論理スクロール位置から解決する処理。`scrollTo` が留め、`getScrollAnchor` が知らせ、
+ * `updateItemSize` がその上の変化を補正し、`computeRenderingRanges` が (`computeRenderingRangesHuge` を含む両方の経路で) 描き
+ * 始める、ただ 1 つの規則。
+ *
+ * - 位置を含む行 (`上端 <= 位置 < 上端 + 高さ`)。
+ * - 下端が位置に一致する行は丸ごとビューポートの上にあるので、ちょうどそこから始まる次の行がオフセット 0 で先頭の可視行。
+ * - 末尾では最後の行が先頭の可視行のまま (末尾のクランプ)。位置がその下端に一致するときと、位置が中身の末尾を越えるとき
+ *   (一覧が縮んでからペインがクランプするまでの過渡状態)。
+ *
+ * モジュールレベル export (バレル非公開)。
+ *
+ * @param fenwickTree - The row-height tree / 行の高さの木
+ * @param position - Logical scroll position (px, 0 or more) / 論理スクロール位置 (px。0 以上)
+ * @param itemCount - Number of rows, 1 or more / 行の数 (1 以上)
+ * @returns The first visible row and its logical top / 先頭の可視行とその論理上端
+ */
+export const resolveVisibleStartRow = (fenwickTree: VisibleStartRowTree, position: number, itemCount: number): VisibleStartRow => {
+    const lastIndex = itemCount - 1
+    const found = fenwickTree.findIndexAtOrAfter(position, LOOKUP_ONLY)
+    if (found.index === -1 || found.index > lastIndex || found.cumulative === undefined || found.currentValue === undefined) {
+        const last = fenwickTree.prefixSum(lastIndex, LOOKUP_ONLY)
+        return { index: lastIndex, top: last.cumulative - last.currentValue }
+    }
+    if (found.cumulative === position && found.index < lastIndex) {
+        return { index: found.index + 1, top: found.cumulative }
+    }
+    return { index: found.index, top: found.cumulative - found.currentValue }
+}
+
+/**
+ * Computes the rendering ranges of a list of `Number.MAX_SAFE_INTEGER` rows or more. The first visible row comes from the one
+ * visible-start boundary rule, `resolveVisibleStartRow`, exactly as in `computeRenderingRanges`, and the forward scan starts at
+ * that row's hidden offset as there; only then are the indices converted to `bigint`. The scans keep their own `bigint` loops
+ * because past 2^53 an index cannot be stepped by 1 in `number` (`x + 1 === x`, so a `number` loop over zero-height rows would
+ * never end); the tree's own lookups take `number` indices, so in that range the start row is as exact as the tree's answer.
+ * Below 2^53 both paths resolve every row boundary, zero-height rows at position 0 and the end clamp to the same ranges.
+ * Module-level export (NOT in the package barrel), for the spec that pins that agreement.
+ *
+ * `Number.MAX_SAFE_INTEGER` 行以上の一覧の描画範囲を求める処理。先頭の可視行は `computeRenderingRanges` とまったく同じく、ただ
+ * 1 つの可視の先頭の境界の規則 `resolveVisibleStartRow` から得て、前方の走査も同じくその行の隠れた量から始め、そのあとで添字を
+ * `bigint` へ変える。走査が `bigint` の繰り返しを持つのは、2^53 を越えると `number` では添字を 1 ずつ進められない
+ * (`x + 1 === x` なので、高さ 0 の行を `number` で走査すると終わらない) ため。木の引き当ては `number` の添字を取るので、その範囲の
+ * 先頭の行は木の答えと同じ精度。2^53 未満では、どちらの経路もどの行の境界・位置 0 の高さ 0 の行・末尾のクランプでも同じ範囲を
+ * 返す。モジュールレベル export (バレル非公開)。その一致を固定する spec のため。
+ *
+ * @param effectiveScrollPosition - Logical scroll position, clamped to the content (px) / 中身へクランプした論理スクロール位置 (px)
+ * @param viewportSize - Height of the viewport (px) / 表示域の高さ (px)
+ * @param overscanCount - Rows rendered beyond each edge / 端の外に描く行の数
+ * @param itemSize - Number of rows / 行の数
+ * @param getItemHeight - Height of a row / 行の高さ
+ * @param fenwickTree - The row-height tree / 行の高さの木
+ * @returns The rendering and visible ranges / 描画範囲と可視範囲
+ */
+export const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSize: number, overscanCount: number, itemSize: number, getItemHeight: (index: number) => number, fenwickTree: ReturnType<typeof useFenwickMapTree>) => {
     const sizeBig = toSafeBigInt(itemSize)
     if (sizeBig === 0n) {
         return { renderingStartIndex: 0, renderingEndIndex: 0, visibleStartIndex: 0, visibleEndIndex: 0 }
     }
 
+    /**
+     * Clamps a row index into the list.
+     * 行の添字を一覧の中へクランプする処理。
+     *
+     * @param value - Row index / 行の添字
+     * @returns The clamped index / クランプした添字
+     */
     const clampBig = (value: bigint): bigint => {
         if (value < 0n) {
             return 0n
@@ -859,46 +1039,31 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
         return value
     }
 
-    const materializeOption = { materializeOption: { materialize: false } }
-    const { index: rawStartIndex, cumulative } = fenwickTree.findIndexAtOrAfter(effectiveScrollPosition, materializeOption)
-
-    let startBig: bigint
-    if (rawStartIndex === -1) {
-        startBig = sizeBig - 1n
-    } else {
-        if (cumulative === effectiveScrollPosition) {
-            startBig = toSafeBigInt(rawStartIndex + 1)
-        } else {
-            startBig = toSafeBigInt(rawStartIndex)
-        }
-
-        if (startBig >= sizeBig) {
-            startBig = sizeBig - 1n
-        }
-    }
-
-    if (effectiveScrollPosition <= 0) {
-        startBig = 0n
-    }
-
-    if (hasFiniteTotal && effectiveScrollPosition >= totalHeight) {
-        startBig = sizeBig - 1n
-    }
+    const startRow = resolveVisibleStartRow(fenwickTree, effectiveScrollPosition, itemSize)
+    let startBig = clampBig(toSafeBigInt(startRow.index))
+    const initialOffset = startRow.top - effectiveScrollPosition
 
     // 高さ 0 (折りたたみ行) はスキップして走査を継続する (散発的な 0 行は正当な入力)。
     // 走査を打ち切るのは負値・非有限の高さ (不正入力) のみ。0 行が大量に連続する場合は
     // 連続数が閾値を超えた時点で Fenwick 木により次の非 0 行へ O(log n) でジャンプし、有界性を保つ。
+    /**
+     * Finds the first row past a long run of zero-height rows that ends at `lastScanned`, through the tree.
+     * `lastScanned` で終わる高さ 0 の行の長い連続の後の最初の行を、木で探す処理。
+     *
+     * @param lastScanned - The last scanned row / 最後に走査した行
+     * @returns The row to continue from, or `null` when the tree gives none ahead / 続ける行 (木が先を返さなければ `null`)
+     */
     const jumpPastZeroRun = (lastScanned: bigint): bigint | null => {
         const lastNumber = Number(lastScanned)
         if (!Number.isSafeInteger(lastNumber)) {
             // number へ安全に変換できない領域では木のクエリが不正確になるため打ち切る
             return null
         }
-        const { cumulative: runBottom } = fenwickTree.prefixSum(lastNumber, { materializeOption: { materialize: false } })
+        const { cumulative: runBottom } = fenwickTree.prefixSum(lastNumber, LOOKUP_ONLY)
         if (!Number.isFinite(runBottom)) {
             return null
         }
-        const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom + 0.5, { materializeOption: { materialize: false } })
+        const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom + 0.5, LOOKUP_ONLY)
         if (jumpIndex === -1) {
             return null
         }
@@ -906,11 +1071,18 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
         return jumpBig > lastScanned ? jumpBig : null
     }
 
-    const accumulateForward = (initial: bigint) => {
-        let height = 0
+    /**
+     * Adds row heights from a row onward until they fill the viewport.
+     * ある行から先の行の高さを、表示域が埋まるまで足す処理。
+     *
+     * @param initial - The first row / 最初の行
+     * @param initialHeight - The height already counted before it (the first row's hidden part, negative) / その前に数えた高さ (最初の行の隠れた量で負)
+     * @returns The counted height and the last counted row / 数えた高さと最後に数えた行
+     */
+    const accumulateForward = (initial: bigint, initialHeight: number) => {
+        let height = initialHeight
         let cursor = initial
         let last = initial
-        let iterations = 0n
         let zeroRun = 0
         while (cursor < sizeBig && height < viewportSize) {
             const cursorNumber = Number(cursor)
@@ -918,7 +1090,6 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
             height += currentHeight
             last = cursor
             cursor += 1n
-            iterations += 1n
             if (!Number.isFinite(currentHeight) || currentHeight < 0) {
                 break
             }
@@ -942,17 +1113,15 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
                 zeroRun = 0
             }
         }
-        if (iterations === 0n) {
-            last = initial
-        }
         return { height, end: last }
     }
 
-    let { height: forwardHeight, end: forwardEnd } = accumulateForward(startBig)
+    let { height: forwardHeight, end: forwardEnd } = accumulateForward(startBig, initialOffset)
 
     if (forwardHeight < viewportSize && startBig > 0n) {
         let backwardStart = startBig
-        let backwardHeight = forwardHeight
+        // 先頭の行の隠れた量は前方の走査が引いてあるので戻す (computeRenderingRanges と同じ数え方)
+        let backwardHeight = forwardHeight + Math.abs(Math.min(0, initialOffset))
         let backwardZeroRun = 0
         while (backwardStart > 0n && backwardHeight < viewportSize) {
             backwardStart -= 1n
@@ -966,15 +1135,14 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
                 backwardZeroRun += 1
                 if (backwardZeroRun > ZERO_HEIGHT_RUN_LIMIT) {
                     // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)
-                    const indexNum = Number(backwardStart)
-                    if (!Number.isSafeInteger(indexNum)) {
+                    if (!Number.isSafeInteger(indexNumber)) {
                         break
                     }
-                    const { cumulative: runBottom } = fenwickTree.prefixSum(indexNum, { materializeOption: { materialize: false } })
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(indexNumber, LOOKUP_ONLY)
                     if (!Number.isFinite(runBottom)) {
                         break
                     }
-                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, { materializeOption: { materialize: false } })
+                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, LOOKUP_ONLY)
                     const jumpBig = jumpIndex === -1 ? -1n : toSafeBigInt(jumpIndex)
                     if (jumpBig >= 0n && jumpBig < backwardStart) {
                         // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
@@ -993,7 +1161,7 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
             }
         }
         startBig = clampBig(backwardStart)
-        const forward = accumulateForward(startBig)
+        const forward = accumulateForward(startBig, 0)
         forwardHeight = forward.height
         forwardEnd = forward.end
     }
@@ -1011,73 +1179,6 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
     }
 }
 
-/**
- * Retrieves a high-resolution timestamp when available.
- *
- * 高精度タイムスタンプを可能なら取得。
- */
-/**
- * The first visible row at a logical scroll position (`resolveVisibleStartRow`).
- *
- * 論理スクロール位置での先頭の可視行 (`resolveVisibleStartRow`)。
- */
-export type VisibleStartRow = {
-    /** Index of the first visible row / 先頭の可視行の index */
-    readonly index: number
-    /** Logical top of that row (px); `position - top` is the part hidden above the viewport top / その行の論理上端 (px)。`position - top` がビューポートの上端より上に隠れた量 */
-    readonly top: number
-}
-
-/**
- * The part of the Fenwick tree `resolveVisibleStartRow` reads.
- *
- * `resolveVisibleStartRow` が読む Fenwick 木の部分。
- */
-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:
- *
- * - the row whose span contains the position: `top <= position < top + height`;
- * - a row whose bottom equals the position lies entirely above the viewport, so the next row starts exactly there and is the
- *   first visible row, at offset 0;
- * - at the end, the last row stays the first visible row (the end clamp): when the position equals its bottom, and when the
- *   position lies past the end of the content (a transient after the list shrinks, before the pane clamps).
- *
- * Module-level export (NOT in the package barrel).
- *
- * 先頭の可視行を、可視の先頭の境界の規則で論理スクロール位置から解決する処理。`scrollTo` が留め、`getScrollAnchor` が知らせ、
- * `updateItemSize` がその上の変化を補正し、`computeRenderingRanges` が描き始める、ただ 1 つの規則。
- *
- * - 位置を含む行 (`上端 <= 位置 < 上端 + 高さ`)。
- * - 下端が位置に一致する行は丸ごとビューポートの上にあるので、ちょうどそこから始まる次の行がオフセット 0 で先頭の可視行。
- * - 末尾では最後の行が先頭の可視行のまま (末尾のクランプ)。位置がその下端に一致するときと、位置が中身の末尾を越えるとき
- *   (一覧が縮んでからペインがクランプするまでの過渡状態)。
- *
- * モジュールレベル export (バレル非公開)。
- *
- * @param fenwickTree - The row-height tree / 行の高さの木
- * @param position - Logical scroll position (px, 0 or more) / 論理スクロール位置 (px。0 以上)
- * @param itemCount - Number of rows, 1 or more / 行の数 (1 以上)
- * @returns The first visible row and its logical top / 先頭の可視行とその論理上端
- */
-export const resolveVisibleStartRow = (fenwickTree: VisibleStartRowTree, position: number, itemCount: number): VisibleStartRow => {
-    const lastIndex = itemCount - 1
-    const found = fenwickTree.findIndexAtOrAfter(position, LOOKUP_ONLY)
-    if (found.index === -1 || found.index > lastIndex || found.cumulative === undefined || found.currentValue === undefined) {
-        const last = fenwickTree.prefixSum(lastIndex, LOOKUP_ONLY)
-        return { index: lastIndex, top: last.cumulative - last.currentValue }
-    }
-    if (found.cumulative === position && found.index < lastIndex) {
-        return { index: found.index + 1, top: found.cumulative }
-    }
-    return { index: found.index, top: found.cumulative - found.currentValue }
-}
-
 /**
  * Calculates rendering boundaries from current scroll metrics. The visible rows start at the row `resolveVisibleStartRow`
  * resolves.
@@ -1091,7 +1192,7 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
     const hasFiniteTotal = Number.isFinite(totalHeight)
     const effectiveScrollPosition = hasFiniteTotal ? Math.min(Math.max(0, scrollPosition), totalHeight) : Math.max(0, scrollPosition)
     if (itemSize >= Number.MAX_SAFE_INTEGER) {
-        return computeRenderingRangesHuge(effectiveScrollPosition, viewportSize, overscanCount, itemSize, getItemHeight, fenwickTree, totalHeight, hasFiniteTotal)
+        return computeRenderingRangesHuge(effectiveScrollPosition, viewportSize, overscanCount, itemSize, getItemHeight, fenwickTree)
     }
     const startRow = resolveVisibleStartRow(fenwickTree, effectiveScrollPosition, itemSize)
     let visibleStartIndex = startRow.index
@@ -1470,6 +1571,36 @@ 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],
+    )
+
     const [initialValues] = useState(() => {
         let position = 0
         let total = 0
@@ -1631,6 +1762,43 @@ const VirtualScrollInner = <T,>(
     const [scrollDirection, setScrollDirection] = useState<"up" | "down" | null>(null)
     const [showScrollButtons, setShowScrollButtons] = useState(false)
     const scrollButtonTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+    // 見せる操作は、画面に出ているピルを表示域 (行ラッパーの境界の箱の上端が表示域の上端) に対して測る
+    const edgeOverlayRef = useRef<HTMLDivElement>(null)
+    const edgePillRef = useRef<HTMLButtonElement>(null)
+    const itemsBoundaryRef = useRef<HTMLDivElement>(null)
+
+    /**
+     * Reads the parts of the viewport the visible scroll-to-edge pill covers (`ObscuredInsets`), in the px the rows are laid
+     * out in: the pill's box is measured on screen against the viewport's top (the items boundary box) and divided by the
+     * vertical scale of any transformed ancestor (`getAxisScale` on the overlay, which spans the viewport), and the pill covers
+     * the edge it lies nearer to, from that edge to its far side. Nothing is covered while no pill shows (the overlay's
+     * `data-visible` is not `"true"`, or the pills are off), nor while the viewport is not laid out (every box is empty).
+     *
+     * 見えている端へ戻るピルが覆う表示域の部分 (`ObscuredInsets`) を、行を配置する px で読む処理。ピルの箱を画面の上で表示域の
+     * 上端 (行ラッパーの境界の箱) に対して測り、変換を持つ祖先の縦の拡大縮小 (表示域にまたがる覆いの `getAxisScale`) で割る。
+     * ピルが覆うのは近い方の端で、その端からピルの向こう側まで。ピルが見えていない間 (覆いの `data-visible` が `"true"` でない、
+     * またはピルが無効) と、表示域が配置されていない間 (どの箱も空) は何も覆わない。
+     *
+     * @returns The covered parts, each clamped to the viewport / 覆われた部分 (どちらも表示域の中へクランプ)
+     */
+    const readObscuredInsets = useCallback((): ObscuredInsets => {
+        const overlay = edgeOverlayRef.current
+        const pill = edgePillRef.current
+        const boundary = itemsBoundaryRef.current
+        if (overlay === null || pill === null || boundary === null || overlay.dataset.visible !== "true") {
+            return NO_OBSCURED_INSETS
+        }
+        // 境界の箱は高さ 0 で縦の拡大縮小を測れないので、表示域と同じ高さの覆いで測る (測れなければ 1 なので割っても壊れない)
+        const scale = getAxisScale(overlay, "y")
+        const viewportTop = boundary.getBoundingClientRect().top
+        const pillBox = pill.getBoundingClientRect()
+        const pillTop = (pillBox.top - viewportTop) / scale
+        const pillBottom = (pillBox.bottom - viewportTop) / scale
+        if (pillTop + pillBottom < viewportSize) {
+            return { top: minmax(pillBottom, 0, viewportSize), bottom: 0 }
+        }
+        return { top: 0, bottom: minmax(viewportSize - pillTop, 0, viewportSize) }
+    }, [viewportSize])
     const isProgrammaticScrollRef = useRef(false)
     const isCompensatingRef = useRef(0)
     // レイアウトシフト補正の scrollTo が ScrollPane の旧 contentSize でクランプされた場合に true。
@@ -2069,14 +2237,19 @@ const VirtualScrollInner = <T,>(
      * height reconciliation on the next render. A change above the first visible row (the row of the pending
      * alignment while one is pending, otherwise the row `resolveVisibleStartRow` resolves) moves the scroll
      * position by the same delta (layout-shift compensation), carries the remembered alignment along and
-     * is reported through `onScrollAdjust` (`"item-resize"`) before this returns.
+     * is reported through `onScrollAdjust` (`"item-resize"`) before this returns. Every change of the size
+     * advances the tree revision (`changeTree`), so the next commit re-places the rendered rows and
+     * re-resolves the rendering range, whether or not the total changes (several calls in one batch whose
+     * changes cancel out included).
      *
      * 指定されたアイテムのサイズを更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を返すこと。
      * `getItemHeight` が正であるため、そうでない場合は描画ウィンドウ (オーバースキャン含む) 内の行が
      * 次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。先頭の可視行 (保留中の揃えがあればその行、
      * 無ければ `resolveVisibleStartRow` が解決する行) より上の変化はスクロール位置を
      * 同じ差だけ動かし (レイアウトシフトの補正)、覚えた揃えも一緒に動かして、戻る前に `onScrollAdjust`
-     * (`"item-resize"`) で知らせる。
+     * (`"item-resize"`) で知らせる。サイズのどの変化も木の版数を進める (`changeTree`) ので、総和が変わるか
+     * どうかによらず (同じバッチの中で差が打ち消し合う複数の呼び出しも含む)、次の確定が描いた行を置き直し、
+     * 描画範囲を解決し直す。
      *
      * @param index - Item index / アイテムのインデックス
      * @param size - New size in px / 新しいサイズ (px)
@@ -2090,7 +2263,7 @@ const VirtualScrollInner = <T,>(
             const oldSize = fenwickTree.get(safeIndex)
             const delta = size - oldSize
 
-            const total = fenwickTree.update(safeIndex, size)
+            const total = changeTree(() => fenwickTree.update(safeIndex, size))
             if (total !== undefined) {
                 writeContentSize(total)
             }
@@ -2129,7 +2302,7 @@ const VirtualScrollInner = <T,>(
                 Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (manual update)", { from: currentPanePosition, to: newPosition, causedByIndex: safeIndex, delta, activeVisibleStartIndex })
             }
         },
-        [fenwickTree, itemCount, applySelfAdjustment, carryAlignedEdge, issueCompensationScroll, updateScrollPositionImmediate, contentInsets, writeContentSize],
+        [fenwickTree, itemCount, applySelfAdjustment, carryAlignedEdge, changeTree, issueCompensationScroll, updateScrollPositionImmediate, contentInsets, writeContentSize],
     )
 
     /**
@@ -2139,26 +2312,56 @@ const VirtualScrollInner = <T,>(
      * and the scroll position are written only when they differ from their synchronous copies (`writeContentSize`; for the
      * position, `latestScrollPositionRef` while the render loop is stopped, read before the pane moves), so a call that
      * leaves the list where it is (the same row, alignment and content) writes no state, schedules no render and reports
-     * no position to `onScroll`, like `scrollTo` to the current position.
+     * no position to `onScroll`, like `scrollTo` to the current position. The tree revision advances (`changeTree`) only
+     * when materialising the rows around the target (±`overscanCount * 2`) changed the tree.
+     *
+     * `align: "nearest"` (the reveal) first resolves, from the tree as it is, how the row lands in the band the visible
+     * scroll-to-edge pill leaves (`resolveRevealAlignment` over `readObscuredInsets`): a row already wholly inside returns
+     * without touching anything, and any other row lands with the resolved `"top"` / `"bottom"` alignment and its offset,
+     * like an explicit call with them.
      *
      * 指定インデックスへのスクロールを実行する処理。ペインを揃えた位置 (中身の範囲へクランプ) へ厳密に着地させ、ドリフト補正の
      * 保留中の揃えとして留め、行ラッパーの装置の画素への揃えのためにその位置で揃えの端を正規形で覚える
      * (`resolveItemsWrapperSnapEdge`)。中身の寸法とスクロール位置は同期の写し (`writeContentSize`。位置は描画ループが止まって
      * いる間の `latestScrollPositionRef` を、ペインを動かす前に読む) と違うときだけ書くため、一覧をその場に留める呼び出し (同じ行・揃え・中身) は状態を書かず、描画を予約せず、`onScroll` へ位置を
-     * 知らせない (現在位置への `scrollTo` と同じ)。
+     * 知らせない (現在位置への `scrollTo` と同じ)。揃える行の周り (±`overscanCount * 2`) の具現化が木を変えたときだけ、木の版数を
+     * 進める (`changeTree`)。
+     *
+     * `align: "nearest"` (見せる操作) は、見えている端へ戻るピルが残す帯へ行をどう着地させるかを今の木から先に解決する
+     * (`readObscuredInsets` に対する `resolveRevealAlignment`)。既にまるごと入っている行は何にも触れずに戻り、それ以外の行は
+     * 解決した `"top"` / `"bottom"` の揃えと offset で、それを明示した呼び出しと同じく着地させる。
      *
      * @param index - Item index / アイテムのインデックス
-     * @param options - Alignment (`"top"` by default) and offset / 揃え方 (既定は `"top"`) と offset
+     * @param options - Alignment (`"top"` by default) and offset, or the reveal `{ align: "nearest" }` / 揃え方 (既定は `"top"`) と offset、または見せる操作 `{ align: "nearest" }`
+     * @throws {RangeError} When `"nearest"` comes with an `offset` / `"nearest"` に `offset` を渡したとき
      */
     const scrollToIndex = useCallback(
-        (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number }) => {
+        (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number } | { align: "nearest"; offset?: never }) => {
             if (!scrollPaneRef.current || itemCount === 0) {
                 return
             }
             const safeIndex = sanitizeIndex(index, itemCount)
+            let alignment: { align?: "top" | "bottom" | "center"; offset?: number } | undefined
+            if (options?.align === "nearest") {
+                // 型は offset を許さないが、型の無い呼び出し元の offset を黙って捨てない
+                const offset: unknown = (options as { readonly offset?: unknown }).offset
+                if (offset !== undefined) {
+                    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 reveal = resolveRevealAlignment({ top: row.cumulative - row.currentValue, bottom: row.cumulative }, toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top), viewportSize, readObscuredInsets())
+                if (reveal === null) {
+                    return
+                }
+                alignment = reveal
+            } else {
+                alignment = options
+            }
             const safeIndexFrom = sanitizeIndex(safeIndex - overscanCount * 2, itemCount)
             const safeIndexTo = sanitizeIndex(safeIndex + overscanCount * 2, itemCount)
-            const { cumulative: itemBottom, total, currentValue: itemHeight } = fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: true, ranges: [{ from: safeIndexFrom, to: safeIndexTo }] } })
+            // 揃える行の周りの具現化は推定の高さを実際の高さへ置き換え、描いた行の上端も変え得る (位置が動かない揃え直しでも)
+            const { cumulative: itemBottom, total, currentValue: itemHeight } = changeTree(() => fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: true, ranges: [{ from: safeIndexFrom, to: safeIndexTo }] } }))
 
             Logger.debug("[VirtualScroll] Scrolling to index:", safeIndex, "ItemBottom:", itemBottom, "Total height:", total, "ItemHeight:", itemHeight, "safeIndexFrom:", safeIndexFrom, "safeIndexTo:", safeIndexTo)
 
@@ -2169,14 +2372,14 @@ const VirtualScrollInner = <T,>(
             const itemTop = Math.max(itemBottom - itemHeight, 0)
             let targetLogicalPosition = itemTop
 
-            if (options?.align === "bottom") {
+            if (alignment?.align === "bottom") {
                 targetLogicalPosition = itemBottom - viewportSize
-            } else if (options?.align === "center") {
+            } else if (alignment?.align === "center") {
                 targetLogicalPosition = itemTop + itemHeight / 2 - viewportSize / 2
             }
 
-            if (options?.offset) {
-                targetLogicalPosition -= options.offset
+            if (alignment?.offset) {
+                targetLogicalPosition -= alignment.offset
             }
 
             // Ensure we don't scroll past the content
@@ -2201,10 +2404,10 @@ const VirtualScrollInner = <T,>(
             // レイアウトシフト補正のアンカーとして、保留中のターゲットインデックスを設定します
             pendingVisibleStartIndexRef.current = {
                 index: safeIndex,
-                align: options?.align,
-                offset: options?.offset,
+                align: alignment?.align,
+                offset: alignment?.offset,
             }
-            const edge = edgeOfAlignment(options?.align)
+            const edge = edgeOfAlignment(alignment?.align)
             rememberAlignedEdge(edge === null ? null : { edge, panePosition: clampedPaneOffset })
 
             // ❗ 判定はペインを動かす前に行う。ペインの scrollTo はスクロールの処理を同期で呼び、位置の写しを着地位置へ進めて
@@ -2240,7 +2443,7 @@ const VirtualScrollInner = <T,>(
 
             Logger.debug("[VirtualScroll] Setting scroll position to:", clampedPaneOffset, { original: paneOffset, max: maxScrollPosition })
         },
-        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, rememberAlignedEdge, updateScrollPositionImmediate, writeContentSize],
+        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, changeTree, readObscuredInsets, rememberAlignedEdge, updateScrollPositionImmediate, writeContentSize],
     )
 
     // アンカー付きマウントが itemCount 0 で始まった場合の遅延適用 (一度きり)。
@@ -2431,6 +2634,8 @@ const VirtualScrollInner = <T,>(
     const logicalScrollPosition = useMemo(() => toLogicalPositionWithInset(scrollPosition, resolvedInsets.top), [resolvedInsets.top, scrollPosition])
 
     const renderingRanges = useMemo(() => {
+        // 範囲は木から解くので、位置が動かなくても木の変化 (総和が変わらない変化を含む) で解き直す
+        void treeRevision
         // useMemo 内では State の contentSize ではなく、常に最新の計算結果を持つ fenwickTree.getTotal() を使用する。
         // これにより、アイテム数が大幅に減少した直後でも、古い contentSize (State) に基づく誤ったレンダリング範囲計算を防ぐことができる。
         // contentSize (State) の更新は非同期で行われるため、一瞬古い状態が残る可能性があるが、fenwickTree は同期的であり信頼性が高い。
@@ -2444,10 +2649,23 @@ const VirtualScrollInner = <T,>(
             viewportSize,
         }))
         return ranges
-    }, [logicalScrollPosition, viewportSize, overscanCount, itemCount, getItemHeight, fenwickTree]) // contentSize を依存配列から削除
+    }, [logicalScrollPosition, viewportSize, overscanCount, itemCount, getItemHeight, fenwickTree, treeRevision])
 
     const { renderingStartIndex, renderingEndIndex, visibleStartIndex, visibleEndIndex } = renderingRanges
 
+    /**
+     * Focuses the row at an index. With `ensureVisible` (default `true`) the row is first revealed by the one reveal rule
+     * (`scrollToIndex` with `align: "nearest"`: the least scroll into the band a visible scroll-to-edge pill leaves), then a
+     * rendered row takes focus at once and a row not rendered yet takes it when it mounts (`pendingFocusIndexRef`). With
+     * `false` only a rendered row takes focus, without scrolling.
+     *
+     * 指定 index の行へフォーカスする処理。`ensureVisible` (既定 `true`) では先にただ 1 つの見せる規則 (`align: "nearest"` の
+     * `scrollToIndex`。見えている端へ戻るピルが残す帯への最短のスクロール) で行を見せ、描いてある行はすぐに、まだ描いていない行は
+     * マウントしたときに (`pendingFocusIndexRef`) フォーカスを受ける。`false` では描いてある行だけがスクロールせずにフォーカスを受ける。
+     *
+     * @param index - Row index / 行の index
+     * @param options - Whether to reveal the row first (default `true`) / 先に行を見せるか (既定 `true`)
+     */
     const focusItemAtIndex = useCallback(
         (index: number, options?: { ensureVisible?: boolean }) => {
             if (!enableKeyboardNavigation || itemCount === 0) {
@@ -2455,50 +2673,24 @@ const VirtualScrollInner = <T,>(
             }
             const safeIndex = sanitizeIndex(index, itemCount)
             const ensureVisible = options?.ensureVisible ?? true
-            if (!ensureVisible) {
-                const existingElement = itemRefs.current.get(safeIndex)
-                if (existingElement) {
-                    pendingFocusIndexRef.current = null
-                    lastFocusedIndexRef.current = safeIndex
-                    tryFocusElement(existingElement)
-                }
-                return
-            }
-
-            const prefix = fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: false } })
-            const itemHeight = prefix.currentValue
-            const itemTop = Math.max(prefix.cumulative - itemHeight, 0)
-            const itemBottom = itemTop + itemHeight
-            const viewportTop = toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top)
-            const viewportBottom = viewportTop + viewportSize
-            const needsScroll = itemTop < viewportTop || itemBottom > viewportBottom
-            if (needsScroll) {
-                scrollToIndex(safeIndex)
-                // オーバースキャン内で既にマウント済みの行は、スクロールしても ref コールバックが
-                // 再実行されない (handleRef の identity 不変) ため、ここで直接フォーカスを適用する。
-                // マウント済み要素へフォーカスできたら pendingFocusIndexRef を残さない
-                // (残すと後刻の無関係な再マウント時にフォーカスを奪ってしまう)。
-                const mounted = itemRefs.current.get(safeIndex)
-                if (mounted) {
-                    pendingFocusIndexRef.current = null
-                    lastFocusedIndexRef.current = safeIndex
-                    tryFocusElement(mounted)
-                } else {
-                    pendingFocusIndexRef.current = safeIndex
-                }
-                return
+            if (ensureVisible) {
+                scrollToIndex(safeIndex, { align: "nearest" })
             }
-
-            const element = itemRefs.current.get(safeIndex)
-            if (element) {
+            // オーバースキャン内で既にマウント済みの行は、スクロールしても ref コールバックが再実行されない (handleRef の
+            // identity 不変) ため、ここで直接フォーカスを適用する。マウント済み要素へフォーカスできたら pendingFocusIndexRef を
+            // 残さない (残すと後刻の無関係な再マウント時にフォーカスを奪ってしまう)
+            const mounted = itemRefs.current.get(safeIndex)
+            if (mounted) {
                 pendingFocusIndexRef.current = null
                 lastFocusedIndexRef.current = safeIndex
-                tryFocusElement(element)
+                tryFocusElement(mounted)
                 return
             }
-            pendingFocusIndexRef.current = safeIndex
+            if (ensureVisible) {
+                pendingFocusIndexRef.current = safeIndex
+            }
         },
-        [enableKeyboardNavigation, itemCount, fenwickTree, resolvedInsets.top, scrollToIndex, tryFocusElement, viewportSize],
+        [enableKeyboardNavigation, itemCount, scrollToIndex, tryFocusElement],
     )
 
     const handleItemKeyDown = useCallback(
@@ -2719,10 +2911,11 @@ const VirtualScrollInner = <T,>(
         const pillTabIndex = isVisible && !scrollChromeIsPointerOnly ? 0 : -1
 
         return (
-            <div className="aqvs-scroll-to-edge-overlay" data-visible={isVisible} inert={!isVisible} aria-hidden={scrollChromeIsPointerOnly ? true : undefined} onPointerDown={scrollChromeIsPointerOnly ? keepFocusOnPress : undefined}>
+            <div ref={edgeOverlayRef} className="aqvs-scroll-to-edge-overlay" data-visible={isVisible} inert={!isVisible} aria-hidden={scrollChromeIsPointerOnly ? true : undefined} onPointerDown={scrollChromeIsPointerOnly ? keepFocusOnPress : undefined}>
                 {isTop ? (
                     <div className="aqvs-scroll-to-edge-button-container aqvs-scroll-to-edge-button-container-top">
                         <button
+                            ref={edgePillRef}
                             type="button"
                             className="aqvs-scroll-to-edge-button"
                             // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
@@ -2739,6 +2932,7 @@ const VirtualScrollInner = <T,>(
                 ) : (
                     <div className="aqvs-scroll-to-edge-button-container aqvs-scroll-to-edge-button-container-bottom">
                         <button
+                            ref={edgePillRef}
                             type="button"
                             className="aqvs-scroll-to-edge-button"
                             // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
@@ -2767,12 +2961,9 @@ const VirtualScrollInner = <T,>(
     const renderAnchorRef = useRef(0)
 
     const { visibleItems, renderAnchor } = useMemo(() => {
-        // contentSize は memo 本体では直接使わないが「反応辺」として依存に含める:
-        // fenwickTree は安定参照のため、非同期高さ更新 (updateItemSize / 高さ照合マイクロタスクの
-        // fenwickTree.updates) で木の prefix 和が変わってもこの memo は自動では失効しない。
-        // 両経路とも中身の寸法の書き込み (writeContentSize) を伴うため、contentSize を依存へ含めることで
-        // 行 top を最新の prefix 和で確実に再計算させる (報告座標と視覚描画の desync 防止)。
-        void contentSize
+        // 行の上端と高さは木の接頭辞和から決まる。木は同一性を保ったまま描画の外で変わるので、木の版数で失効させる。総和は
+        // 差の和が 0 の変化では変わらないため、中身の寸法を依存にしても上端は古いまま残る (報告する座標と描いた行の食い違い)
+        void treeRevision
 
         if (itemCount === 0) {
             return {
@@ -2877,7 +3068,9 @@ const VirtualScrollInner = <T,>(
                     }
                 }
 
-                const total = fenwickTree.updates(toUpdateHeights)
+                // 照合した行の上端は描画の中で補ってあるが、木から導いた値 (getRange の総高さなど) は古い木のまま。総和が変わらない
+                // 変化でも、次の確定で木から導き直させる
+                const total = changeTree(() => fenwickTree.updates(toUpdateHeights))
                 if (isUnmountedRef.current || typeof total !== "number") {
                     return
                 }
@@ -2905,9 +3098,9 @@ const VirtualScrollInner = <T,>(
     }, [
         applySelfAdjustment,
         carryAlignedEdge,
+        changeTree,
         children,
         clipItemHeight,
-        contentSize,
         enableKeyboardNavigation,
         itemCount,
         fenwickTree,
@@ -2923,6 +3116,7 @@ const VirtualScrollInner = <T,>(
         renderingEndIndex,
         renderingStartIndex,
         resolvedLabels,
+        treeRevision,
         updateScrollPositionImmediate,
         visibleStartIndex,
         writeContentSize,
@@ -3001,7 +3195,7 @@ const VirtualScrollInner = <T,>(
             }))
 
             return (
-                <ItemsWrapper translateY={containerTop} snapEdge={snapEdge}>
+                <ItemsWrapper translateY={containerTop} snapEdge={snapEdge} boundaryRef={itemsBoundaryRef}>
                     {visibleItems}
                     {bottomInset}
                 </ItemsWrapper>
@@ -3010,19 +3204,18 @@ const VirtualScrollInner = <T,>(
         [alignedEdge, callbackThrottleMs, itemCount, fenwickTree, logicalScrollPosition, renderAnchor, renderingEndIndex, renderingStartIndex, resolvedInsets, scrollPosition, viewportSize, visibleItems],
     )
 
-    const currentRange = useMemo<VirtualScrollRange>(
-        () => ({
+    const currentRange = useMemo<VirtualScrollRange>(() => {
+        // 総高さは木から読む。木は同一性を保ったまま変わるので、木の版数で読み直す
+        void treeRevision
+        return {
             renderingStartIndex: renderingRanges.renderingStartIndex,
             renderingEndIndex: renderingRanges.renderingEndIndex,
             visibleStartIndex: renderingRanges.visibleStartIndex,
             visibleEndIndex: renderingRanges.visibleEndIndex,
             scrollPosition: logicalScrollPosition,
-            totalHeight: fenwickTree.getTotal(), // contentSize (State) ではなく最新値を反映
-        }),
-        // contentSize を依存に含めることで、updateItemSize/updates 等で木の総高さが変わった際に
-        // (fenwickTree は安定参照のため getTotal() の変化だけでは再計算されない) 総高さを再取得する。
-        [renderingRanges, logicalScrollPosition, fenwickTree, contentSize],
-    )
+            totalHeight: fenwickTree.getTotal(),
+        }
+    }, [renderingRanges, logicalScrollPosition, fenwickTree, treeRevision])
 
     useEffect(() => {
         // 目的: 描画範囲を最新の状態で同期する ref を更新する。