@aiquants/virtualscroll 3.9.1 → 3.10.0

package/src/VirtualScroll.tsx

@@ -4,7 +4,7 @@ import { resolveVirtualScrollLabels, type VirtualScrollLabelOverrides, type Virt
 import { Logger } from "./logger.ts"
 import { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneProps } from "./ScrollPane.tsx"
 import { useFenwickMapTree } from "./useFenwickMapTree.ts"
-import { minmax } from "./utils.ts"
+import { keepFocusOnPress, minmax } from "./utils.ts"
 
 /**
  * Represents the current state of the rendered range and scroll metrics.
@@ -196,21 +196,23 @@ export type VirtualScrollScrollBarOptions = {
     /** Whether the arrow buttons scroll (default `true`). / 矢印ボタンによるスクロールを許可するかどうか (既定 `true`)。 */
     enableArrowButtons?: boolean
     /**
-     * Whether the scrollbar's arrow buttons are Tab stops (default `true`). Set it to `false` when
-     * the host already provides keyboard scrolling (roving row focus with Arrow / Page / Home / End):
-     * the arrows then only add two redundant Tab stops per bar — native scrollbars are never Tab
-     * stops either. `false` changes `tabIndex` alone (`-1`): the arrows stay pointer-operable and
-     * named, and Enter / Space still scroll when one is focused from script.
-     * The default stays `true` because the rows are not Tab stops, so without a host keyboard model
-     * the arrows are the only scrolling control a keyboard user can reach with Tab. Full contract:
+     * Whether the scroll chrome is the keyboard user's scrolling control (default `true`), or pointer-only because the
+     * host scrolls the list by keyboard itself (`false`: roving row focus with Arrow / Page / Home / End).
+     * `true`: the scrollbar is a named `role="scrollbar"` with a named `role="slider"` thumb, and its arrows (and the
+     * visible scroll-to-edge pills) are Tab stops — the rows are not Tab stops, so without a host keyboard model they are
+     * the only scrolling controls a keyboard user can reach with Tab.
+     * `false`: the scrollbar and the scroll-to-edge pills become pointer-only, like a native scrollbar: both carry
+     * `aria-hidden="true"`, nothing in them is a Tab stop, and a press on them never moves focus (neither onto them nor
+     * away from where the host put it); pointer scrolling and the pills' clicks are unchanged. Full contract:
      * `ScrollBarProps["enableArrowButtonTabStops"]`.
-     * スクロールバーの矢印ボタンを Tab の止まり先にするかどうか (既定 `true`)。ホストがキーボード
-     * スクロールを既に提供する場合 (行のロービングフォーカスと矢印 / Page / Home / End) に `false` —
-     * 矢印はバー 1 本あたり冗長な Tab の止まり先を 2 つ足すだけになるため (ネイティブのスクロールバーも
-     * Tab の止まり先にならない)。`false` が変えるのは `tabIndex` (`-1`) だけで、ポインタ操作・
-     * アクセシブルネームと、スクリプトからフォーカスした矢印の Enter / Space は維持。既定が `true`
-     * なのは、行が Tab の止まり先ではないため、ホストのキーボードモデルが無ければ矢印がキーボード
-     * 利用者の Tab で届く唯一のスクロール操作部品だから。契約の全文は
+     * スクロールの部品がキーボード利用者のスクロール操作部品か (既定 `true`)、ホストが一覧のキーボードスクロールを
+     * 自分で持つためポインタ専用か (`false`: 行のロービングフォーカスと矢印 / Page / Home / End) の指定。
+     * `true`: スクロールバーは名前付きの `role="scrollbar"` で名前付きの `role="slider"` のつまみを持ち、矢印 (と見えている
+     * 端へ戻るピル) は Tab の止まり先 — 行は Tab の止まり先ではないため、ホストのキーボードモデルが無ければ Tab で届く
+     * 唯一のスクロール操作部品。
+     * `false`: スクロールバーと端へ戻るピルはネイティブのスクロールバーと同じくポインタ専用になる。どちらも
+     * `aria-hidden="true"` を持ち、中に Tab の止まり先は無く、押下はフォーカスを動かさない (部品へも、ホストが置いた
+     * 場所の外へも)。ポインタのスクロールとピルの click は変わらない。契約の全文は
      * `ScrollBarProps["enableArrowButtonTabStops"]`。
      */
     enableArrowButtonTabStops?: boolean
@@ -314,12 +316,12 @@ export type VirtualScrollLiveRegionOptions = {
      * Formats the announcement text. Called after the visible range settles; returning the same
      * string as last time leaves the DOM untouched (no re-announcement), returning `""` clears
      * the region. The live-region wording and its language are consumer-owned: the package's
-     * built-in catalog (`locale` / `labels`) covers only the seven chrome strings (scrollbar arrow
-     * aria-labels, the scroll-to-edge pills and the empty state), never announcements.
+     * built-in catalog (`locale` / `labels`) covers only the eleven chrome strings (the scrollbar's
+     * accessible names, the scroll-to-edge pills and the empty state), never announcements.
      * 読み上げ文言を組み立てる。可視範囲が静定した後に呼ばれ、前回と同じ文字列なら DOM を
      * 触らない (再読み上げしない)。`""` を返すとリージョンを空にする。読み上げの文面と言語は
-     * 消費側の所有物 — パッケージの内蔵カタログ (`locale` / `labels`) が扱うのはクローム 7 文言
-     * (スクロールバー矢印の aria-label、端スクロールピル、空状態) だけで、読み上げは対象外。
+     * 消費側の所有物 — パッケージの内蔵カタログ (`locale` / `labels`) が扱うのはクローム 11 文言
+     * (スクロールバーのアクセシブルネーム、端スクロールピル、空状態) だけで、読み上げは対象外。
      *
      * @param range - The settled visible range / 静定した可視範囲
      * @returns Announcement text / 読み上げ文言
@@ -428,11 +430,11 @@ export type VirtualScrollProps<T> = {
      */
     liveRegion?: VirtualScrollLiveRegionOptions
     /**
-     * UI chrome locale of the built-in strings (default `"en"`): the scrollbar arrow aria-labels,
-     * the scroll-to-edge pills and the empty-state text. Live-region wording is not affected (see
+     * 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
      * {@link VirtualScrollLiveRegionOptions.format}). An unsupported value throws a RangeError at
      * render; no language negotiation happens.
-     * 内蔵文言 (スクロールバー矢印の aria-label、端スクロールピル、空状態文言) の UI クロームロケール
+     * 内蔵文言 (スクロールバーのアクセシブルネーム — バー・つまみ・矢印 —、端スクロールピル、空状態文言) の UI クロームロケール
      * (既定 `"en"`)。ライブリージョンの文言には影響しない ({@link VirtualScrollLiveRegionOptions.format}
      * 参照)。非対応値は描画時に RangeError、言語ネゴシエーションなし。
      */
@@ -678,6 +680,24 @@ const edgeOfAlignment = (align: "top" | "bottom" | "center" | undefined): Aligne
     return align === "bottom" ? "end" : "start"
 }
 
+/**
+ * Returns the canonical form of an alignment to remember: `null` for one that can never change the edge the items
+ * wrapper keeps, the alignment itself otherwise. An alignment at pane position 0 or below holds only at positions within
+ * `EDGE_POSITION_TOLERANCE` of position 0, where `resolveItemsWrapperSnapEdge` answers `"start"` from the position
+ * alone, so it means the same as remembering nothing. Storing only the canonical form keeps one state for one meaning:
+ * a list the user scrolled back to the top and a list `scrollToIndex` aligned there hold the same state, so aligning it
+ * to the top again writes nothing.
+ *
+ * 覚える揃えの正規形を返す処理。行ラッパーが守る端を決して変えない揃えは `null`、それ以外は揃えそのもの。ペイン位置 0 以下の
+ * 揃えが成り立つのは位置 0 から `EDGE_POSITION_TOLERANCE` 以内の位置だけで、そこでは `resolveItemsWrapperSnapEdge` が位置
+ * だけから `"start"` を返すため、何も覚えないのと同じ意味。正規形だけを持つことで 1 つの意味に 1 つの状態となり、利用者が
+ * 先頭へ戻した一覧と `scrollToIndex` が先頭へ揃えた一覧が同じ状態を持ち、先頭へ揃え直しても何も書かない。
+ *
+ * @param alignment - The alignment, or `null` / 揃え (無ければ `null`)
+ * @returns The canonical alignment, or `null` / 正規形の揃え (無ければ `null`)
+ */
+const canonicalAlignedEdge = (alignment: AlignedEdge | null): AlignedEdge | null => (alignment !== null && alignment.panePosition <= 0 ? null : alignment)
+
 /**
  * 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:
@@ -747,14 +767,25 @@ type ItemsWrapperProps = {
  * render anchor is a whole number of device px — for example when every row height is a multiple of a lattice L with
  * L × ratio a whole number (L = 4 px at ratios in quarter steps).
  *
+ * The wrapper sits in `.aqvs-items-boundary`, its containing block and a relayout boundary: a positioned box with size and
+ * layout containment that is neither a flex nor a grid item, attached to the top, left and right padding edges of the pane
+ * content (so the wrapper keeps its position and width) with a height of 0. A step that mounts or unmounts rows therefore
+ * lays out from that box instead of from the document root. The rows overflow it unclipped, as ink overflow that is not
+ * part of the pane content's scrollable area, and the box takes no hit test of its own.
+ *
  * 行ラッパー。`translateY` で動かす合成層 (`will-change: transform`) で、平行移動は描くウィンドウの装置の画素の格子へ
  * `snapEdge` の側で揃える (`snapToDevicePixelGrid`。比は `usePaintingDevicePixelRatio` が描画の中で読むので、自分の
  * ウィンドウの文書に描いた一覧は最初の確定から揃う)。揃えるのは層の平行移動だけ。層の中の行は厳密なレイアウトの位置に
  * 描かれ、角の丸い枠線・輪・輪郭はそこで滲む。行が装置の画素の整数から始まるのは、描画のアンカーからの行の位置が装置 px の
  * 整数のときだけ (例: どの行の高さも、L × 比が整数になる格子 L の倍数のとき。比が 4 分の 1 刻みなら L = 4px)。
  *
+ * ラッパーは包含ブロックで配置の境界の `.aqvs-items-boundary` の中に置く。位置指定され、大きさと配置を封じ込め、flex の子でも
+ * grid の子でもない箱で、ペインの中身のパディングの上・左・右の辺に付き (ラッパーの位置と幅は変わらない)、高さは 0。行を足し引き
+ * する 1 段の配置は、文書の根ではなくこの箱から始まる。行は箱から切り取られずにはみ出し (ペインの中身のスクロールできる範囲に
+ * 数えないインクのはみ出し)、箱自身は当たり判定を取らない。
+ *
  * @param props - The exact translate, the edge it keeps and the wrapped rows / 厳密な平行移動・守る端・包む行
- * @returns The wrapper element / ラッパーの要素
+ * @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` を参照)
  */
@@ -767,9 +798,13 @@ const ItemsWrapper = ({ translateY, snapEdge, children }: ItemsWrapperProps) =>
     // ❗ 層の様式は will-change: transform だけ。perspective や 3D の変換を足すと Chromium は描画の切り取り (cull rect) を
     // 外して描くが、行を非 2D の変換の下で合成するので画素比によっては層ごと再標本化する (実測: 比 1.25 の明色で選択の輪と
     // フォーカスの輪の間の帯が混ざる)。窓をずらす 1 段がはみ出しを切る中身の行を描き直す費用は、その代わりに受け入れる
+    // ❗ ペインの中身は flex の子で配置の境界になれない。境界の箱を挟まないと、行を足し引きする 1 段の配置が毎回文書の根から
+    // 始まる (実測: 4 倍の CPU で 1 段の配置の時間のすべてが文書の根から)
     return (
-        <div ref={attach} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
-            {children}
+        <div className="aqvs-items-boundary">
+            <div ref={attach} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
+                {children}
+            </div>
         </div>
     )
 }
@@ -982,9 +1017,72 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
  * 高精度タイムスタンプを可能なら取得。
  */
 /**
- * Calculates rendering boundaries from current scroll metrics.
+ * 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.
+ *
+ * 現在のスクロール情報から描画範囲を算出。可視の行は `resolveVisibleStartRow` が解決する行から始まる。
  */
 export const computeRenderingRanges = (scrollPosition: number, viewportSize: number, overscanCount: number, itemSize: number, getItemHeight: (index: number) => number, fenwickTree: ReturnType<typeof useFenwickMapTree>, totalHeight: number) => {
     if (itemSize === 0) {
@@ -995,31 +1093,9 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
     if (itemSize >= Number.MAX_SAFE_INTEGER) {
         return computeRenderingRangesHuge(effectiveScrollPosition, viewportSize, overscanCount, itemSize, getItemHeight, fenwickTree, totalHeight, hasFiniteTotal)
     }
-    const { index: rawStartIndex, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(effectiveScrollPosition, { materializeOption: { materialize: false } })
-    const startIndex =
-        rawStartIndex === -1
-            ? (() => {
-                  // Fenwick がインデックスを返さない場合は末尾に合わせて開始位置を再計算
-                  if (viewportSize <= 0) {
-                      return itemSize - 1
-                  }
-                  return (cumulative ?? 0) < effectiveScrollPosition + (currentValue ?? 0) ? itemSize - 1 : 0
-              })()
-            : rawStartIndex
-    let visibleStartIndex = sanitizeIndex(startIndex, itemSize)
-
-    let visibleHeight = 0
-    if (rawStartIndex !== -1 && cumulative === effectiveScrollPosition) {
-        visibleStartIndex = sanitizeIndex(rawStartIndex + 1, itemSize)
-        visibleHeight = 0
-    } else if (visibleStartIndex === rawStartIndex && cumulative !== undefined && currentValue !== undefined) {
-        const itemTop = cumulative - currentValue
-        visibleHeight = itemTop - effectiveScrollPosition
-    } else {
-        const { cumulative: startCumulative, currentValue: startHeight } = fenwickTree.prefixSum(visibleStartIndex, { materializeOption: { materialize: false } })
-        const itemTop = (startCumulative ?? 0) - (startHeight ?? 0)
-        visibleHeight = itemTop - effectiveScrollPosition
-    }
+    const startRow = resolveVisibleStartRow(fenwickTree, effectiveScrollPosition, itemSize)
+    let visibleStartIndex = startRow.index
+    let visibleHeight = startRow.top - effectiveScrollPosition
 
     const initialOffset = visibleHeight
 
@@ -1303,6 +1379,8 @@ const VirtualScrollInner = <T,>(
     ref: React.Ref<VirtualScrollHandle>,
 ) => {
     const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableArrowButtonTabStops, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
+    // 合図はスクロールバーと同じ 1 つ (既定 true)。端へ戻るピルもバーと同じくポインタ専用になる
+    const scrollChromeIsPointerOnly = enableArrowButtonTabStops === false
     const resolvedLabels = useMemo(() => resolveVirtualScrollLabels(locale, labels), [locale, labels])
 
     const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, enableEscapeRowReturn = false, wheelSpeedMultiplier, inertiaOptions, overscrollBehavior, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
@@ -1428,26 +1506,48 @@ const VirtualScrollInner = <T,>(
 
     const [scrollPosition, setScrollPosition] = useState(initialValues.position)
     const [contentSize, setContentSize] = useState<number>(initialValues.total)
-    // 初期位置の index とアンカーは上端揃えの scrollToIndex と同じ位置なので、その位置の上端揃えとして覚えておく。位置 0 から
-    // 始まる一覧も先頭の行の上端に揃っている (位置 0 の行ラッパーは覚えた揃えによらず上端で揃える) ため、同じく覚える。覚えずに
-    // 始めると、先頭へ戻すだけの最初の scrollToIndex (ホストが開いた直後の打鍵で先頭へ戻すなど) が状態を書き、確定を 1 回足す
-    const [alignedEdge, setAlignedEdge] = useState<AlignedEdge | null>(() => ((initialScrollAnchor && itemCount > 0) || typeof initialScrollIndex === "number" || initialValues.position <= EDGE_POSITION_TOLERANCE ? { edge: "start", panePosition: initialValues.position } : null))
+    // 初期位置の index とアンカーは上端揃えの scrollToIndex と同じ位置なので、その位置の上端揃えとして覚えておく。覚えずに
+    // 始めると、同じ行へ揃え直すだけの最初の scrollToIndex が状態を書き、確定を 1 回足す。位置 0 では正規形が null になる
+    const [alignedEdge, setAlignedEdge] = useState<AlignedEdge | null>(() => ((initialScrollAnchor && itemCount > 0) || typeof initialScrollIndex === "number" ? canonicalAlignedEdge({ edge: "start", panePosition: initialValues.position }) : null))
     // 状態の同期の写し。手動スクロールのたびに状態へ null を書くと、同じ値でも React が描画を予約し得るため、写しで要否を決める
     const alignedEdgeRef = useRef(alignedEdge)
+    // contentSize の同期の写し。確定の直後は同じ値の setState でも React が描画を 1 回予約するため、書くかどうかを写しで決める
+    const contentSizeRef = useRef(contentSize)
+
+    /**
+     * Writes the content size the pane and the scroll bar are sized by, and its synchronous copy, only when the value
+     * differs from the one last written (every writer of the content size goes through here, so the copy is the value the
+     * state settles on).
+     *
+     * ペインとスクロールバーの寸法の元になる中身の寸法と、その同期の写しへ、最後に書いた値と違うときだけ書く処理 (中身の寸法の
+     * 書き手はすべてここを通るため、写しは状態が落ち着く値)。
+     *
+     * @param next - The content size (px) / 中身の寸法 (px)
+     */
+    const writeContentSize = useCallback((next: number): void => {
+        if (contentSizeRef.current === next) {
+            return
+        }
+        contentSizeRef.current = next
+        setContentSize(next)
+    }, [])
 
     /**
-     * Remembers the alignment that holds at a pane position, or forgets it with `null`: writes the state the items wrapper
-     * snaps with and its synchronous copy, only when the edge or the pane position differs from the remembered one.
+     * Remembers the alignment that holds at a pane position, or forgets it with `null`: reduces it to its canonical form
+     * (`canonicalAlignedEdge`, so an alignment at position 0 is the same as none), then writes the state the items wrapper
+     * snaps with and its synchronous copy, only when the canonical form differs from the remembered one in edge or pane
+     * position.
      *
-     * あるペイン位置で成り立つ揃えを覚える処理 (`null` で忘れる)。行ラッパーが揃えに使う状態と、その同期の写しへ、覚えた揃えと
-     * 辺かペイン位置が違うときだけ書く。
+     * あるペイン位置で成り立つ揃えを覚える処理 (`null` で忘れる)。揃えを正規形にし (`canonicalAlignedEdge`。位置 0 の揃えは
+     * 揃え無しと同じ)、行ラッパーが揃えに使う状態と、その同期の写しへ、正規形が覚えた揃えと辺かペイン位置で違うときだけ書く。
      *
-     * @param next - The alignment, or `null` / 揃え (無ければ `null`)
+     * @param alignment - The alignment, or `null` / 揃え (無ければ `null`)
      */
-    const rememberAlignedEdge = useCallback((next: AlignedEdge | null): void => {
+    const rememberAlignedEdge = useCallback((alignment: AlignedEdge | null): void => {
         const current = alignedEdgeRef.current
+        const next = canonicalAlignedEdge(alignment)
         // 同じ揃えでも新しいオブジェクトを書けば React は描画を予約する。同じ位置への scrollToIndex (ホストが打鍵ごとに
-        // 先頭へ戻すなど) のたびに確定が 1 回増えるため、辺と位置が同じなら書かない
+        // 揃え直すなど) のたびに確定が 1 回増えるため、辺と位置が同じなら書かない
         if (current === next || (current !== null && next !== null && current.edge === next.edge && current.panePosition === next.panePosition)) {
             return
         }
@@ -1457,10 +1557,15 @@ const VirtualScrollInner = <T,>(
 
     /**
      * Moves the remembered alignment along with a position change that keeps the aligned row in place (layout-shift
-     * compensation): when the alignment held at `fromPanePosition`, it now holds at `toPanePosition`.
+     * compensation): when the alignment held at `fromPanePosition`, it now holds at `toPanePosition`. Only a remembered
+     * alignment moves: the top edge a list keeps at position 0 comes from the position (`resolveItemsWrapperSnapEdge`), not
+     * from the state (`canonicalAlignedEdge`), so a move away from position 0 carries no edge, and an alignment carried to
+     * position 0 or below is dropped.
      *
      * 揃えた行をその場に留める位置の変化 (レイアウトシフトの補正) に合わせて、覚えた揃えを動かす処理。揃えが
-     * `fromPanePosition` で成り立っていたなら、`toPanePosition` で成り立つ。
+     * `fromPanePosition` で成り立っていたなら、`toPanePosition` で成り立つ。動くのは覚えた揃えだけ。位置 0 の一覧が守る上端は
+     * 状態ではなく位置から決まる (`resolveItemsWrapperSnapEdge`・`canonicalAlignedEdge`) ため、位置 0 から離れる変化は端を
+     * 運ばず、位置 0 以下へ運んだ揃えは消える。
      *
      * @param fromPanePosition - Pane position before the change / 変化の前のペイン位置
      * @param toPanePosition - Pane position after the change / 変化の後のペイン位置
@@ -1826,9 +1931,9 @@ const VirtualScrollInner = <T,>(
     const didApplyInitialOffsetRef = useRef(false)
 
     /**
-     * Flushes queued onScroll notifications.
+     * Applies `initialScrollOffset` once, as the highest-priority initial position, synchronising the pane and the logical position.
      *
-     * キューされた onScroll 通知を実行。
+     * `initialScrollOffset` を最優先の初期位置として一度だけ適用し、ペインと論理位置を同期させる effect。
      */
     useEffect(() => {
         if (didApplyInitialOffsetRef.current) return
@@ -1861,7 +1966,7 @@ const VirtualScrollInner = <T,>(
 
         const totalHeight = fenwickTree.getTotal()
         if (contentSize !== totalHeight) {
-            setContentSize(totalHeight)
+            writeContentSize(totalHeight)
             return
         }
 
@@ -1933,7 +2038,7 @@ const VirtualScrollInner = <T,>(
             }
         }
         isResizingRef.current = false
-    }, [contentSize, fenwickTree, itemCount, resolvedInsets.top, applySelfAdjustment, rememberAlignedEdge, updateScrollPositionImmediate, viewportSize, resolvedInsets.bottom])
+    }, [contentSize, fenwickTree, itemCount, resolvedInsets.top, applySelfAdjustment, rememberAlignedEdge, updateScrollPositionImmediate, viewportSize, resolvedInsets.bottom, writeContentSize])
 
     useEffect(() => {
         // 目的: 上部インセットが動的に変更された場合、論理スクロール位置を維持したまま、ペインのスクロール位置を再計算してずらす。
@@ -1961,13 +2066,15 @@ const VirtualScrollInner = <T,>(
      * Updates the size of a specific item. Contract: after this call, `getItemHeight(index)` must
      * return the same `size`; `getItemHeight` is the source of truth, so rows inside the current
      * rendering window (including overscan) are otherwise reverted to the `getItemHeight` value by
-     * height reconciliation on the next render. A change above the first visible row moves the scroll
+     * 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.
      *
      * 指定されたアイテムのサイズを更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を返すこと。
      * `getItemHeight` が正であるため、そうでない場合は描画ウィンドウ (オーバースキャン含む) 内の行が
-     * 次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。先頭の可視行より上の変化はスクロール位置を
+     * 次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。先頭の可視行 (保留中の揃えがあればその行、
+     * 無ければ `resolveVisibleStartRow` が解決する行) より上の変化はスクロール位置を
      * 同じ差だけ動かし (レイアウトシフトの補正)、覚えた揃えも一緒に動かして、戻る前に `onScrollAdjust`
      * (`"item-resize"`) で知らせる。
      *
@@ -1985,7 +2092,7 @@ const VirtualScrollInner = <T,>(
 
             const total = fenwickTree.update(safeIndex, size)
             if (total !== undefined) {
-                setContentSize(total)
+                writeContentSize(total)
             }
             Logger.debug("[VirtualScroll] Updated item size manually", { index: safeIndex, size, total })
 
@@ -2000,18 +2107,12 @@ const VirtualScrollInner = <T,>(
                 const currentScrollTop = latestScrollPositionRef.current
                 const insetsTop = normalizeInsets(contentInsets).top
                 const logicalScrollTop = toLogicalPositionWithInset(currentScrollTop, insetsTop)
-                // Use materialize: false for performance, we just need the index
-                const { index, cumulative } = fenwickTree.findIndexAtOrAfter(logicalScrollTop, { materializeOption: { materialize: false } })
-                // findIndexAtOrAfter は「下端(cumulative) >= scrollTop の最小 index」を返すため、
-                // アイテム index の下端がちょうど scrollTop に一致する場合、その行は完全にビューポート上方にある。
-                // computeRenderingRanges (cumulative === effectiveScrollPosition の特例) と同じく可視先頭を index+1 に補正する。
-                activeVisibleStartIndex = cumulative !== undefined && cumulative === logicalScrollTop ? index + 1 : index
+                activeVisibleStartIndex = resolveVisibleStartRow(fenwickTree, logicalScrollTop, itemCount).index
             }
 
-            // Allow for a small buffer in case of slight misalignments or stale refs
             // If the item is strictly above the visible start, it pushes content down.
-            // アイテムが（ほぼ）確実に可視領域より上にある場合、コンテンツ全体を押し下げます
-            if (activeVisibleStartIndex !== -1 && safeIndex < activeVisibleStartIndex && delta !== 0) {
+            // アイテムが可視領域より上にある場合、コンテンツ全体を押し下げます
+            if (safeIndex < activeVisibleStartIndex && delta !== 0) {
                 // Use latestScrollPositionRef as the source of truth for the current position
                 // to avoid reading stale DOM values during batched updates (e.g. multiple items resizing at once).
                 const currentPanePosition = latestScrollPositionRef.current
@@ -2028,16 +2129,23 @@ 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],
+        [fenwickTree, itemCount, applySelfAdjustment, carryAlignedEdge, issueCompensationScroll, updateScrollPositionImmediate, contentInsets, writeContentSize],
     )
 
     /**
      * Scrolls to the requested logical index: lands the pane exactly on the aligned position (clamped to the content),
      * pins it as the pending alignment for drift correction, and remembers the alignment's edge at that position for
-     * the device-pixel snap of the items wrapper (`resolveItemsWrapperSnapEdge`).
+     * the device-pixel snap of the items wrapper (`resolveItemsWrapperSnapEdge`, in its canonical form). The content size
+     * 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.
      *
      * 指定インデックスへのスクロールを実行する処理。ペインを揃えた位置 (中身の範囲へクランプ) へ厳密に着地させ、ドリフト補正の
-     * 保留中の揃えとして留め、行ラッパーの装置の画素への揃えのためにその位置で揃えの端を覚える (`resolveItemsWrapperSnapEdge`)。
+     * 保留中の揃えとして留め、行ラッパーの装置の画素への揃えのためにその位置で揃えの端を正規形で覚える
+     * (`resolveItemsWrapperSnapEdge`)。中身の寸法とスクロール位置は同期の写し (`writeContentSize`。位置は描画ループが止まって
+     * いる間の `latestScrollPositionRef` を、ペインを動かす前に読む) と違うときだけ書くため、一覧をその場に留める呼び出し (同じ行・揃え・中身) は状態を書かず、描画を予約せず、`onScroll` へ位置を
+     * 知らせない (現在位置への `scrollTo` と同じ)。
      *
      * @param index - Item index / アイテムのインデックス
      * @param options - Alignment (`"top"` by default) and offset / 揃え方 (既定は `"top"`) と offset
@@ -2099,6 +2207,10 @@ const VirtualScrollInner = <T,>(
             const edge = edgeOfAlignment(options?.align)
             rememberAlignedEdge(edge === null ? null : { edge, panePosition: clampedPaneOffset })
 
+            // ❗ 判定はペインを動かす前に行う。ペインの scrollTo はスクロールの処理を同期で呼び、位置の写しを着地位置へ進めて
+            // 描画ループを起こすが、状態はそのループの次のフレームまで古いまま。描画ループが止まっている間だけ、状態 (予約済みの
+            // 値を含む) が位置の写しと一致する
+            const stateHoldsLanding = !renderLoopRef.current.loopActive && latestScrollPositionRef.current === clampedPaneOffset
             const currentPanePosition = scrollPaneRef.current?.getScrollPosition() ?? -1
             // ❗ 揃えは厳密に着地させる。半ピクセル未満のずれを残すと、揃えた行の端の余白をそのずれが削り、行ラッパーを
             // 揃えた端の側へ丸めても取り戻せない (覚えた揃えもペインの位置と一致せず効かない)
@@ -2120,12 +2232,15 @@ const VirtualScrollInner = <T,>(
                 scrollPaneRef.current?.scrollTo(clampedPaneOffset)
             }
 
-            setContentSize(total)
-            updateScrollPositionImmediate(clampedPaneOffset, { immediate: true })
+            writeContentSize(total)
+            // 確定の直後は同じ値の setState でも React が描画を 1 回予約するため、状態が既に着地位置なら書かない
+            if (!stateHoldsLanding) {
+                updateScrollPositionImmediate(clampedPaneOffset, { immediate: true })
+            }
 
             Logger.debug("[VirtualScroll] Setting scroll position to:", clampedPaneOffset, { original: paneOffset, max: maxScrollPosition })
         },
-        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, rememberAlignedEdge, updateScrollPositionImmediate],
+        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, rememberAlignedEdge, updateScrollPositionImmediate, writeContentSize],
     )
 
     // アンカー付きマウントが itemCount 0 で始まった場合の遅延適用 (一度きり)。
@@ -2144,9 +2259,15 @@ const VirtualScrollInner = <T,>(
     }, [itemCount, scrollToIndex])
 
     /**
-     * Scrolls to a raw offset while resolving to an index.
+     * Scrolls to a raw logical offset by pinning the first visible row there (`resolveVisibleStartRow`) with the offset of
+     * its top, so the pending alignment is the row `getScrollAnchor` reports: a position on a row boundary pins the row that
+     * starts there at offset 0, never the hidden row above it.
+     *
+     * 論理オフセットへのスクロール。その位置の先頭の可視行 (`resolveVisibleStartRow`) を、その上端からのオフセットで留めるので、
+     * 保留中の揃えは `getScrollAnchor` が知らせる行になる。行の境界の位置では、そこから始まる行をオフセット 0 で留め、上に
+     * 隠れた行は留めない。
      *
-     * オフセットをインデックスに変換しつつスクロール。
+     * @param newPosition - Logical position in px (floored, then clamped to the content) / 論理位置 (px。切り捨ててから中身の範囲へクランプ)
      */
     const scrollTo = useCallback(
         (newPosition: number) => {
@@ -2155,43 +2276,33 @@ const VirtualScrollInner = <T,>(
             }
             const total = fenwickTree.getTotal()
             const safePosition = minmax(Math.floor(newPosition), 0, total)
-            const { index, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(safePosition, { materializeOption: { materialize: false } })
-
-            // Calculate offset relative to item top to ensure precise positioning
-            // itemTop = cumulative - currentValue
-            const itemTop = (cumulative ?? 0) - (currentValue ?? 0)
-            const offset = itemTop - safePosition
-
-            scrollToIndex(index, { offset })
+            const startRow = resolveVisibleStartRow(fenwickTree, safePosition, itemCount)
+            scrollToIndex(startRow.index, { offset: startRow.top - safePosition })
         },
         [fenwickTree, itemCount, scrollToIndex],
     )
 
     /**
-     * Captures the current top-row anchor for exact position restore across remounts.
-     * 再マウント越しの厳密な位置復元のために、現在の先頭可視行アンカーを取得する処理。
+     * Captures the current top-row anchor for exact position restore across remounts: the first visible row that
+     * `resolveVisibleStartRow` resolves (the same row `scrollTo` pins) and the px its top is hidden above the viewport top.
+     * Returns `null` while the list is empty.
+     * 再マウント越しの厳密な位置復元のために、現在の先頭可視行アンカーを取得する処理。行は `resolveVisibleStartRow` が解決する
+     * 先頭の可視行 (`scrollTo` が留める行と同じ) で、空の一覧では `null`。
      *
      * offsetPx は「先頭可視行の上端がビューポート上端より上に隠れている px」(正の値、論理座標)。
      * 復元は initialScrollAnchor へそのまま渡す。可視ウィンドウの行高さは描画のたびに実測が
      * ツリーへ照合されるため、保存時点のアンカーは常に正確で、生 px と違い再マウント後の
      * 推定空間の違いに対して不変 (px 復元は深い位置で別の行に着地する)。
+     *
+     * @returns The anchor, or `null` without rows / アンカー (行が無ければ `null`)
      */
     const getScrollAnchor = useCallback((): { index: number; offsetPx: number } | null => {
         if (itemCount === 0) {
             return null
         }
         const logical = toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top)
-        const { index, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(logical, { materializeOption: { materialize: false } })
-        if (index === -1) {
-            // 末尾越え (推定総高さより深い位置) は最終行アンカーへ丸める
-            return { index: itemCount - 1, offsetPx: 0 }
-        }
-        if (cumulative === logical) {
-            // 行の下端がちょうどビューポート上端 = 可視先頭は次の行 (可視域計算と同じ境界規約)
-            return { index: minmax(index + 1, 0, itemCount - 1), offsetPx: 0 }
-        }
-        const itemTop = (cumulative ?? 0) - (currentValue ?? 0)
-        return { index, offsetPx: Math.max(0, logical - itemTop) }
+        const startRow = resolveVisibleStartRow(fenwickTree, logical, itemCount)
+        return { index: startRow.index, offsetPx: Math.max(0, logical - startRow.top) }
     }, [fenwickTree, itemCount, resolvedInsets.top])
 
     /**
@@ -2591,6 +2702,12 @@ const VirtualScrollInner = <T,>(
      * ポインタ軸の下限は CSS 側の `.aqvs-scroll-to-edge-overlay[data-visible="false"]
      * .aqvs-scroll-to-edge-button { pointer-events: none }` が担う (配布 CSS 未読込のホストでは
      * `inert` が、`inert` 未実装のブラウザでは CSS が、互いの穴を埋める)。
+     *
+     * ホストがキーボードのスクロールを持つ (`scrollBarOptions.enableArrowButtonTabStops: false`) と、ピルはスクロールバーと
+     * 同じくポインタ専用になる。オーバーレイは見えている間も `aria-hidden="true"` で、ピルは Tab 順に入らず、オーバーレイ
+     * が押下の既定動作を取り消すのでピルの押下はフォーカスを動かさない (click は届く)。
+     *
+     * @returns The overlay, or `null` without the pills / オーバーレイ (ピルを出さないなら `null`)
      */
     const renderOverlay = useCallback(() => {
         if (!enableScrollToTopBottomButtons) {
@@ -2599,16 +2716,17 @@ const VirtualScrollInner = <T,>(
 
         const isVisible = showScrollButtons && scrollDirection !== null
         const isTop = scrollDirection === "up"
+        const pillTabIndex = isVisible && !scrollChromeIsPointerOnly ? 0 : -1
 
         return (
-            <div className="aqvs-scroll-to-edge-overlay" data-visible={isVisible} inert={!isVisible}>
+            <div 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
                             type="button"
                             className="aqvs-scroll-to-edge-button"
                             // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
-                            tabIndex={isVisible ? 0 : -1}
+                            tabIndex={pillTabIndex}
                             onClick={(e) => {
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
@@ -2624,7 +2742,7 @@ const VirtualScrollInner = <T,>(
                             type="button"
                             className="aqvs-scroll-to-edge-button"
                             // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
-                            tabIndex={isVisible ? 0 : -1}
+                            tabIndex={pillTabIndex}
                             onClick={(e) => {
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
@@ -2637,7 +2755,7 @@ const VirtualScrollInner = <T,>(
                 )}
             </div>
         )
-    }, [enableScrollToTopBottomButtons, showScrollButtons, scrollDirection, scrollToIndex, itemCount, resolvedLabels])
+    }, [enableScrollToTopBottomButtons, scrollChromeIsPointerOnly, showScrollButtons, scrollDirection, scrollToIndex, itemCount, resolvedLabels])
 
     // 量子化アンカー (fix: LayoutUnit/f32 精度対策)。行 top はコンテンツ絶対座標そのままではなく
     // 「絶対座標 - アンカー」で描画し、ラッパー側 translateY にアンカーを足し戻す。
@@ -2652,7 +2770,7 @@ const VirtualScrollInner = <T,>(
         // contentSize は memo 本体では直接使わないが「反応辺」として依存に含める:
         // fenwickTree は安定参照のため、非同期高さ更新 (updateItemSize / 高さ照合マイクロタスクの
         // fenwickTree.updates) で木の prefix 和が変わってもこの memo は自動では失効しない。
-        // 両経路とも setContentSize を伴うため、contentSize を依存へ含めることで
+        // 両経路とも中身の寸法の書き込み (writeContentSize) を伴うため、contentSize を依存へ含めることで
         // 行 top を最新の prefix 和で確実に再計算させる (報告座標と視覚描画の desync 防止)。
         void contentSize
 
@@ -2763,7 +2881,7 @@ const VirtualScrollInner = <T,>(
                 if (isUnmountedRef.current || typeof total !== "number") {
                     return
                 }
-                setContentSize(total)
+                writeContentSize(total)
                 Logger.debug("[VirtualScroll] Updated heights for items", toUpdateHeights, "New total height:", total)
                 const panePosition = scrollPaneRef.current?.getScrollPosition() ?? latestScrollPositionRef.current
 
@@ -2807,6 +2925,7 @@ const VirtualScrollInner = <T,>(
         resolvedLabels,
         updateScrollPositionImmediate,
         visibleStartIndex,
+        writeContentSize,
     ])
 
     /**