@aiquants/virtualscroll 3.8.2 → 3.9.0

package/src/VirtualScroll.tsx

@@ -1,4 +1,5 @@
-import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react"
+import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, 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"
@@ -25,6 +26,44 @@ export type VirtualScrollRange = {
     totalHeight: number
 }
 
+/**
+ * Why VirtualScroll moved its scroll position on its own (see `VirtualScrollProps["onScrollAdjust"]`).
+ *
+ * - `"item-resize"`: `updateItemSize` changed the height of a row above the first visible row, and the position moved by
+ *   the same delta, so the visible rows stay where they were.
+ * - `"reconciliation"`: a render found that `getItemHeight` returns a new height for a rendered row above the first
+ *   visible row; the height reconciliation that follows the render (a microtask) moved the position by the same delta.
+ * - `"drift"`: after a size change (content, viewport, item count or insets) the pending alignment of the last
+ *   `scrollToIndex` (or of `initialScrollAnchor`) was pinned again, in an effect after the commit.
+ * - `"re-issue"`: a compensation that the pane clamped against the previous content size was issued again once the new
+ *   content size had committed, in an effect after the commit.
+ *
+ * VirtualScroll が自分でスクロール位置を動かした理由 (`VirtualScrollProps["onScrollAdjust"]` を参照)。
+ *
+ * - `"item-resize"`: `updateItemSize` が先頭の可視行より上の行の高さを変え、位置を同じ差だけ動かした (見えている行はその場に
+ *   留まる)。
+ * - `"reconciliation"`: 描画が、描いた行のうち先頭の可視行より上の行について `getItemHeight` の新しい高さを見つけ、描画の後の
+ *   高さの照合 (マイクロタスク) が位置を同じ差だけ動かした。
+ * - `"drift"`: 寸法の変化 (中身・ビューポート・件数・インセット) の後、最後の `scrollToIndex` (または `initialScrollAnchor`)
+ *   の保留中の揃えを、確定の後の effect で留め直した。
+ * - `"re-issue"`: ペインが前の中身の寸法でクランプした補正を、新しい中身の寸法が確定した後の effect でもう一度発行した。
+ */
+export type VirtualScrollAdjustmentCause = "item-resize" | "reconciliation" | "drift" | "re-issue"
+
+/**
+ * One position change VirtualScroll made on its own (the argument of `VirtualScrollProps["onScrollAdjust"]`).
+ *
+ * VirtualScroll が自分で行った 1 回の位置の変化 (`VirtualScrollProps["onScrollAdjust"]` の引数)。
+ */
+export type VirtualScrollAdjustment = {
+    /** The LOGICAL scroll position after the change — what `getScrollPosition()` returns at that moment / 変化の後の論理スクロール位置 (その時点の `getScrollPosition()` の値) */
+    readonly position: number
+    /** The applied change in LOGICAL px: `position` minus the position before the change; never 0 / 適用した変化 (論理 px)。`position` から変化の前の位置を引いた値で、0 にはならない */
+    readonly delta: number
+    /** Why the position moved / 位置が動いた理由 */
+    readonly cause: VirtualScrollAdjustmentCause
+}
+
 /**
  * Imperative handle of VirtualScroll. Every position it accepts or returns is in the
  * LOGICAL coordinate space (content px, insets excluded) — the same space as onScroll /
@@ -98,7 +137,15 @@ export type VirtualScrollHandle = {
     getContentSize: () => number
     /** Viewport size / ビューポートの高さ。未接続時は -1 */
     getViewportSize: () => number
-    /** Scrolls to a specific item index / 指定したアイテムインデックスへスクロール */
+    /**
+     * 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).
+     *
+     * 指定したアイテムインデックスへスクロールする処理。揃えた位置 (中身の範囲へクランプ) へ厳密に着地する。`"top"` (既定) と
+     * `"bottom"` の揃えはその位置で覚えるので、そこでは行ラッパーの装置の画素への揃えが揃えた端を守る (README の装置の画素への
+     * 揃えの節を参照)。
+     */
     scrollToIndex: (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number }) => void
     /** Gets the total height managed by the Fenwick Tree / Fenwick Tree で管理されている総高さを取得 */
     getFenwickTreeTotalHeight: () => number
@@ -119,10 +166,15 @@ export type VirtualScrollHandle = {
      * `getItemHeight(index)` must return the same `size`; `getItemHeight` is the source of truth,
      * so if it keeps returning the old value, rows inside the current rendering window (including
      * overscan) are reverted to the `getItemHeight` value by height reconciliation on the next render.
+     * When the item lies above the first visible row, the scroll position moves by the size change
+     * before this returns (layout-shift compensation), and `onScrollAdjust` reports it with the cause
+     * `"item-resize"`.
      *
      * 特定のアイテムのサイズを手動で更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を
      * 返すこと。`getItemHeight` が正であるため、旧値を返し続けると描画ウィンドウ (オーバースキャン
-     * 含む) 内の行は次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。
+     * 含む) 内の行は次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。アイテムが先頭の可視行より
+     * 上にあるときは、戻る前にスクロール位置をサイズの変化だけ動かし (レイアウトシフトの補正)、
+     * `onScrollAdjust` が理由 `"item-resize"` で知らせる。
      */
     updateItemSize: (index: number, size: number) => void
 }
@@ -330,6 +382,33 @@ export type VirtualScrollProps<T> = {
     testId?: string
     onScroll?: (scrollPosition: number, totalHeight: number) => void
     onRangeChange?: (range: VirtualScrollRange) => void
+    /**
+     * Called synchronously, without throttling, each time VirtualScroll moves its scroll position on its own: a
+     * layout-shift compensation (`"item-resize"`, `"reconciliation"`), the re-pinning of a pending alignment
+     * (`"drift"`) or the second stage of a clamped compensation (`"re-issue"`) — see `VirtualScrollAdjustmentCause`.
+     * It runs after the change is complete, so `getScrollPosition()` and `getScrollAnchor()` read inside it already
+     * see the adjusted position and row heights. It never runs for scrolls that the user or the host start (wheel,
+     * drag, scrollbar, inertia, keyboard row navigation, `scrollTo` / `scrollBy` / `scrollToIndex` / `applyWheel`),
+     * nor for a change that leaves `getScrollPosition()` where it was.
+     *
+     * `onScroll` and `onRangeChange` report every position, but throttled and one frame later. A host that keeps its
+     * own scroll anchor by item identity (re-finding the first visible item by key after a list change) records that
+     * anchor from the range report and from its own scrolls; it must also record it from here, or a list change
+     * committed before the next range report restores a position VirtualScroll has already moved.
+     *
+     * VirtualScroll が自分でスクロール位置を動かすたびに、間引かず同期で呼ぶ関数。レイアウトシフトの補正
+     * (`"item-resize"`・`"reconciliation"`)、保留中の揃えの留め直し (`"drift"`)、クランプされた補正の二段目
+     * (`"re-issue"`) が対象 (`VirtualScrollAdjustmentCause` を参照)。変化を終えてから呼ぶので、中で読む
+     * `getScrollPosition()` と `getScrollAnchor()` は動かした後の位置と行の高さを返す。利用者やホストが始めた
+     * スクロール (ホイール・ドラッグ・スクロールバー・慣性・行のキーボード移動・`scrollTo` / `scrollBy` /
+     * `scrollToIndex` / `applyWheel`) と、`getScrollPosition()` を変えない変化では呼ばない。
+     *
+     * `onScroll` と `onRangeChange` はどの位置も知らせるが、間引いたうえで 1 フレーム遅れる。項目の同一性で自前の
+     * スクロールの錨を持つホスト (一覧の変化の後に先頭の可視項目をキーで探し直す) は、範囲の知らせと自分のスクロールで
+     * 錨を記録するが、ここでも記録すること。さもないと、次の範囲の知らせより前に確定した一覧の変化が、VirtualScroll が
+     * 既に動かした位置を巻き戻す。
+     */
+    onScrollAdjust?: (adjustment: VirtualScrollAdjustment) => void
     /**
      * Opt-in `aria-live` region announcing the visible range to assistive technology (default:
      * none rendered). Virtualization removes off-screen rows from the DOM, so a screen-reader
@@ -557,127 +636,92 @@ export const MAX_RENDERED_ITEMS = 2000
 export const ANCHOR_REBASE_DISTANCE = 1_048_576 // 2^20 px — VirtualGrid の横アンカーが共有 import する (パッケージバレルへは非公開)
 
 /**
- * Snaps a CSS-px offset to the device-pixel grid of a window: the nearest offset whose device-px value is a
- * whole number, `Math.round(cssPx × ratio) / ratio` (an exact half rounds toward +∞, as `Math.round` does). The items-wrapper translate goes through it: a composited layer moved by a fraction of a
- * device pixel is resampled as a whole (2-px outlines, gaps and rings smear across neighbouring device rows and
- * text blurs), while fractional layout positions inside the layer are painted on whole pixels already.
- * Idempotent: a snapped value snaps to itself. A non-finite `cssPx` propagates (`NaN` in, `NaN` out).
- * Module-level export (NOT in the package barrel).
- *
- * CSS px のオフセットをウィンドウの装置の画素の格子へ揃える処理。装置 px で整数になる最も近いオフセット
- * `Math.round(cssPx × ratio) / ratio` (ちょうど半分は `Math.round` どおり +∞ 側)。
- * 行ラッパーの平行移動はここを通す — 合成層を装置の画素の端数だけ動かすとブラウザは層全体を再標本化し
- * (2px の輪郭・隙間・輪が隣の装置の行へ滲み、文字もぼける)、層の中の端数のレイアウト位置は描画が既に画素へ
- * 揃えるため。冪等 (揃えた値はそのまま)。有限でない `cssPx` はそのまま伝わる (`NaN` は `NaN`)。
- * モジュールレベル export (バレル非公開)。
+ * Distance in px within which a pane position counts as resting at an edge: position 0, the maximum position, or the
+ * position where a remembered alignment holds. It absorbs the rounding of the position arithmetic (the same sums of row
+ * heights and insets taken in a different order, which differ by far less), and it stays below a device pixel at any
+ * ratio and below the browser's layout unit (1/64 px): content resting this close to an edge crosses that edge by at most
+ * this distance.
  *
- * @param cssPx - Offset in CSS px; negative and fractional values included / CSS px のオフセット (負・小数を含む)
- * @param ratio - Device px per CSS px of the window that paints the offset (its `devicePixelRatio`); a finite number > 0 / オフセットを描くウィンドウの CSS px あたりの装置 px (そのウィンドウの `devicePixelRatio`。0 より大きい有限数)
- * @returns The snapped offset in CSS px / 揃えたオフセット (CSS px)
- * @throws {RangeError} When `ratio` is not a finite number greater than 0 / `ratio` が 0 より大きい有限数でないとき
+ * ペイン位置を端にあるとみなす距離 (px)。端は位置 0・最大位置・覚えた揃えが成り立つ位置。位置の計算の丸め (同じ行の高さと
+ * インセットの和を別の順で取った差で、これよりはるかに小さい) を吸収し、どの画素比でも装置の画素 1 つ未満、ブラウザの
+ * レイアウトの単位 (1/64 px) 未満に収まる。端にこれだけ近く止まった中身がその端を越える量は、この距離を超えない。
  */
-export const snapToDevicePixelGrid = (cssPx: number, ratio: number): number => {
-    if (!(Number.isFinite(ratio) && ratio > 0)) {
-        throw new RangeError(`[VirtualScroll] devicePixelRatio must be a finite number > 0, received ${ratio}`)
-    }
-    return Math.round(cssPx * ratio) / ratio
-}
+const EDGE_POSITION_TOLERANCE = 2 ** -10
 
 /**
- * Returns the window of the document the element belongs to — the window whose screen paints it.
- *
- * 要素が属する文書のウィンドウ (要素を描く画面を持つウィンドウ) を返す処理。大域の `window` は使わない
- * (別ウィンドウ・iframe へ描いた一覧の装置の画素比は、そのウィンドウのもの)。
+ * The viewport edge VirtualScroll aligned a row to, and the pane position at which that alignment holds. Module-level
+ * export (NOT in the package barrel), the parameter type of `resolveItemsWrapperSnapEdge`.
  *
- * @param element - Element of the list / 一覧の要素
- * @returns The window / ウィンドウ
- * @throws {Error} When the element's document has no window (a document outside any browsing context, which paints nothing) / 要素の文書がウィンドウを持たないとき (閲覧の文脈の外の文書で、何も描かれない)
+ * VirtualScroll が行を揃えた表示域の端と、その揃えが成り立つペイン位置。モジュールレベル export (バレル非公開)。
+ * `resolveItemsWrapperSnapEdge` の引数の型。
  */
-const windowOf = (element: Element): Window => {
-    const view = element.ownerDocument.defaultView
-    if (view === null) {
-        throw new Error("[VirtualScroll] the items wrapper belongs to a document without a window, so it has no device-pixel ratio")
-    }
-    return view
+export type AlignedEdge = {
+    /** `"start"` for a top alignment, `"end"` for a bottom alignment / 上端揃えは `"start"`、下端揃えは `"end"` */
+    readonly edge: "start" | "end"
+    /** Pane position (PANE coordinates) where the aligned row sits at that edge / 揃えた行がその端にあるペイン位置 (ペイン座標) */
+    readonly panePosition: number
 }
 
 /**
- * Unsubscribe that removes nothing: the subscription of a window without media queries, or of a wrapper with no
- * painting window yet.
+ * Returns the viewport edge an alignment of `scrollToIndex` keeps: `undefined` is the default top alignment, and a
+ * centred row keeps no edge.
  *
- * 何も外さない購読解除 (メディアクエリを持たないウィンドウ、または描くウィンドウがまだ無いラッパーの購読)。
+ * `scrollToIndex` の揃えが守る表示域の端を返す処理。`undefined` は既定の上端揃えで、中央に揃えた行はどの端も守らない。
+ *
+ * @param align - The alignment / 揃え方
+ * @returns The edge, or `null` for a centred row / 端 (中央揃えなら `null`)
  */
-const unsubscribeNothing = (): void => {}
+const edgeOfAlignment = (align: "top" | "bottom" | "center" | undefined): AlignedEdge["edge"] | null => {
+    if (align === "center") {
+        return null
+    }
+    return align === "bottom" ? "end" : "start"
+}
 
 /**
- * Server snapshot of the painting ratio for `useSyncExternalStore`. A server has no screen, so it is `null`
- * and the wrapper keeps the exact translate; hydration renders with it too, so the hydrated markup matches the
- * server HTML, and React replaces it with the snapped translate right after hydration.
+ * 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:
  *
- * `useSyncExternalStore` に渡す、描く比のサーバーのスナップショット。サーバーに画面は無いので `null` で、
- * ラッパーは厳密な平行移動のまま。ハイドレーションもこの値で描くのでサーバーの HTML と一致し、
- * ハイドレーションの直後に React が揃えた平行移動へ置き換える。
+ * - `"start"` while the pane rests at position 0: the first row and the top inset keep their place.
+ * - `"end"` while the pane rests at its maximum position: the last row and the bottom inset keep theirs.
+ * - The edge of the remembered alignment while the pane is at the position where it holds: a row revealed by
+ *   `scrollToIndex` with `align: "top"` (or the default) or `align: "bottom"`, kept through layout-shift compensation and
+ *   drift correction.
+ * - `"none"` (nearest) everywhere else.
  *
- * @returns Always `null` / 常に `null`
- */
-const readServerDevicePixelRatio = (): null => null
-
-/**
- * Returns the window of the JavaScript realm that runs React, or `null` outside a browser realm (server rendering).
- * It is the expected painting window of a wrapper that has not attached yet: render cannot see the document it
- * will be inserted into, and a host renders into its own window's document unless it deliberately renders into
- * another window's document (an iframe or an opened window), which the attach detects (see `ItemsWrapper`).
+ * Position 0 wins over the maximum position (a list that does not scroll stays top-aligned), and both win over a
+ * remembered alignment, since a clamp means that alignment was not reached. A position within `EDGE_POSITION_TOLERANCE`
+ * of one of these counts as that position. Module-level export (NOT in the package barrel).
  *
- * React を実行している JavaScript のレルムのウィンドウを返す処理 (ブラウザのレルムの外 = サーバー描画では
- * `null`)。まだ取り付いていないラッパーの、描くと見込むウィンドウ。描画からは挿入先の文書が見えず、ホストは
- * 別のウィンドウの文書 (iframe・開いたウィンドウ) へ意図して描くのでない限り自分のウィンドウの文書へ描くため。
- * 見込みの確かめは取り付けが行う (`ItemsWrapper` を参照)。
+ * 行ラッパーの平行移動を装置の画素の格子へ揃えるとき (`snapToDevicePixelGrid`) に守る端を選ぶ処理。揃えた中身の端の余白を
+ * 丸めが削らないようにする。
  *
- * @returns The realm's window, or `null` without one / レルムのウィンドウ (無ければ `null`)
- */
-const readRealmWindow = (): Window | null => (typeof window === "undefined" ? null : window)
-
-/**
- * Subscribes to the device-pixel-ratio changes of a window (browser zoom, or the window moving to a screen of
- * another density) through a `(resolution: <ratio>dppx)` media-query watch that is re-armed at each new ratio.
- * A window without media queries (jsdom) cannot change its ratio, so nothing is armed there.
+ * - ペインが位置 0 に止まっている間は `"start"`。最初の行と上のインセットがその場に留まる。
+ * - ペインが最大位置に止まっている間は `"end"`。最後の行と下のインセットがその場に留まる。
+ * - 覚えた揃えが成り立つ位置にペインがある間は、その揃えの端。`scrollToIndex` が `align: "top"` (既定を含む) か
+ *   `align: "bottom"` で見せた行で、レイアウトシフトの補正とドリフト補正を通して保つ。
+ * - それ以外は `"none"` (最も近い格子点)。
  *
- * ウィンドウの装置の画素比の変化 (ブラウザの拡大縮小・密度の違う画面へのウィンドウの移動) を、比が変わる
- * たびに新しい比で張り直す `(resolution: <比>dppx)` のメディアクエリの監視で購読する処理。メディアクエリを
- * 持たないウィンドウ (jsdom) は比が変わり得ないので何も張らない。
+ * 位置 0 は最大位置に勝ち (スクロールしない一覧は上端揃えのまま)、どちらも覚えた揃えに勝つ (クランプは揃えが届かなかった
+ * ことを意味する)。これらの位置から `EDGE_POSITION_TOLERANCE` 以内の位置はその位置とみなす。モジュールレベル export
+ * (バレル非公開)。
  *
- * @param view - Window whose ratio is watched / 比を監視するウィンドウ
- * @param onChange - Called after each ratio change, once the watch is re-armed at the new ratio / 比が変わるたび、新しい比で監視を張り直した後に呼ぶ
- * @returns Unsubscribe that removes the current watch / 今の監視を外す購読解除
+ * @param panePosition - The pane position the wrapper is rendered at (PANE coordinates) / ラッパーを描くペイン位置 (ペイン座標)
+ * @param maxPanePosition - The pane's maximum position: content plus insets minus the viewport / ペインの最大位置 (中身とインセットの和からビューポートを引いた値)
+ * @param alignedEdge - The remembered alignment, or `null` / 覚えた揃え (無ければ `null`)
+ * @returns The edge the snapped translate keeps / 揃えた平行移動が守る端
  */
-const subscribeToDevicePixelRatio = (view: Window, onChange: () => void): (() => void) => {
-    if (typeof view.matchMedia !== "function") {
-        return unsubscribeNothing
+export const resolveItemsWrapperSnapEdge = (panePosition: number, maxPanePosition: number, alignedEdge: AlignedEdge | null): DevicePixelSnapEdge => {
+    if (panePosition <= EDGE_POSITION_TOLERANCE) {
+        return "start"
     }
-    let resolutionQuery = view.matchMedia(`(resolution: ${view.devicePixelRatio}dppx)`)
-    /**
-     * Re-arms the watch at the window's new ratio, then reports the change.
-     *
-     * ウィンドウの新しい比で監視を張り直してから変化を知らせる処理。
-     */
-    const handleResolutionChange = (): void => {
-        resolutionQuery.removeEventListener("change", handleResolutionChange)
-        // ❗ `(resolution: Ndppx)` が知らせるのは比 N との一致・不一致の切り替わりだけ。N 以外の比どうしの変化
-        // (もう一度の拡大縮小・さらに別の画面への移動) を捉えるには、変化のたびに新しい比で張り直すしかない
-        resolutionQuery = view.matchMedia(`(resolution: ${view.devicePixelRatio}dppx)`)
-        resolutionQuery.addEventListener("change", handleResolutionChange)
-        onChange()
+    if (panePosition >= maxPanePosition - EDGE_POSITION_TOLERANCE) {
+        return "end"
     }
-    resolutionQuery.addEventListener("change", handleResolutionChange)
-    /**
-     * Removes the current watch.
-     *
-     * 今の監視を外す処理。
-     */
-    const unsubscribe = (): void => {
-        resolutionQuery.removeEventListener("change", handleResolutionChange)
+    if (alignedEdge !== null && Math.abs(panePosition - alignedEdge.panePosition) <= EDGE_POSITION_TOLERANCE) {
+        return alignedEdge.edge
     }
-    return unsubscribe
+    return "none"
 }
 
 /**
@@ -688,82 +732,43 @@ const subscribeToDevicePixelRatio = (view: Window, onChange: () => void): (() =>
 type ItemsWrapperProps = {
     /** Exact translate in CSS px: top inset + render anchor - pane position / 厳密な平行移動 (CSS px。上のインセット + 描画アンカー - ペイン位置) */
     readonly translateY: number
+    /** The edge the snapped translate keeps (`resolveItemsWrapperSnapEdge`) / 揃えた平行移動が守る端 (`resolveItemsWrapperSnapEdge`) */
+    readonly snapEdge: DevicePixelSnapEdge
     /** The rendered rows and the bottom inset / 描いた行と下のインセット */
     readonly children: ReactNode
 }
 
 /**
- * The items wrapper: a compositor layer (`will-change: transform`) moved by `translateY`, snapped to the
- * device-pixel grid of the window that paints it (`snapToDevicePixelGrid`). Rule: the translate that reaches
- * the screen is always snapped with the ratio of the window that paints the wrapper. Render reads the ratio
- * through `useSyncExternalStore` from the expected painting window — the realm's window (`readRealmWindow`)
- * until the wrapper has attached, since render cannot see the target document. The attach confirms it with the
- * wrapper's own window (`windowOf`): when they agree (a list rendered into its own window's document), the first
- * commit is already snapped and nothing is scheduled in the commit phase; when they differ (a list rendered into
- * an iframe or an opened window), the attach switches to that window; the update is scheduled in the commit
- * phase, so React re-renders the wrapper synchronously before the browser paints. Ratio changes re-render
- * through the store subscription (`subscribeToDevicePixelRatio`), outside the commit phase. The server snapshot
- * is `null`: server HTML and hydration carry the exact translate, replaced by the snapped one right after
- * hydration.
+ * The items wrapper: a compositor layer (`will-change: transform`) moved by `translateY`, snapped to the device-pixel
+ * grid of the window that paints it toward `snapEdge` (`snapToDevicePixelGrid`; the ratio is read during render by
+ * `usePaintingDevicePixelRatio`, so a list rendered into its own window's document is snapped from its first commit).
+ * Only the layer's translate is snapped. The rows inside it paint at their exact layout positions, where rounded
+ * borders, rings and outlines are anti-aliased, so a row starts on a whole device pixel only when its offset from the
+ * 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).
  *
- * 行ラッパー。`translateY` で動かす合成層 (`will-change: transform`) で、平行移動は描くウィンドウの装置の画素の
- * 格子へ揃える (`snapToDevicePixelGrid`)。規則は「画面へ届く平行移動は、常にラッパーを描くウィンドウの比で
- * 揃っている」。描画は `useSyncExternalStore` で、描くと見込むウィンドウから比を読む — 描画からは挿入先の文書が
- * 見えないので、ラッパーが取り付くまではレルムのウィンドウ (`readRealmWindow`)。取り付けがラッパー自身の
- * ウィンドウ (`windowOf`) と突き合わせて確かめ、一致すれば (自分のウィンドウの文書に描いた一覧) 最初の確定から
- * 揃っていて確定の段では何も予約しない。違えば (iframe・開いたウィンドウに描いた一覧) 取り付けがそのウィンドウへ
- * 切り替え、この更新は確定の段で予約されるので、React はブラウザの paint の前にラッパーを同期で描き直す。
- * 比の変化はストアの購読 (`subscribeToDevicePixelRatio`) で確定の段の外から描き直す。サーバーのスナップショットは
- * `null` で、サーバーの HTML とハイドレーションは厳密な平行移動を持ち、ハイドレーションの直後に揃えた値へ置き換わる。
+ * 行ラッパー。`translateY` で動かす合成層 (`will-change: transform`) で、平行移動は描くウィンドウの装置の画素の格子へ
+ * `snapEdge` の側で揃える (`snapToDevicePixelGrid`。比は `usePaintingDevicePixelRatio` が描画の中で読むので、自分の
+ * ウィンドウの文書に描いた一覧は最初の確定から揃う)。揃えるのは層の平行移動だけ。層の中の行は厳密なレイアウトの位置に
+ * 描かれ、角の丸い枠線・輪・輪郭はそこで滲む。行が装置の画素の整数から始まるのは、描画のアンカーからの行の位置が装置 px の
+ * 整数のときだけ (例: どの行の高さも、L × 比が整数になる格子 L の倍数のとき。比が 4 分の 1 刻みなら L = 4px)。
  *
- * @param props - The exact translate and the wrapped rows / 厳密な平行移動と包む行
+ * @param props - The exact translate, the edge it keeps and the wrapped rows / 厳密な平行移動・守る端・包む行
  * @returns The wrapper element / ラッパーの要素
- * @throws {Error} When the wrapper attaches to a document without a window (see `windowOf`) / ウィンドウを持たない文書へ取り付いたとき (`windowOf` を参照)
+ * @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, children }: ItemsWrapperProps) => {
-    const [paintingWindow, setPaintingWindow] = useState<Window | null>(readRealmWindow)
-    /**
-     * Subscribes the store to the painting window's ratio changes.
-     *
-     * 描くウィンドウの比の変化へストアを購読させる処理。
-     */
-    const subscribe = useCallback((onChange: () => void): (() => void) => (paintingWindow === null ? unsubscribeNothing : subscribeToDevicePixelRatio(paintingWindow, onChange)), [paintingWindow])
-    /**
-     * Reads the painting window's current ratio (`null` while no window is known).
-     *
-     * 描くウィンドウの今の比を読む処理 (ウィンドウが分からない間は `null`)。
-     */
-    const readDevicePixelRatio = useCallback((): number | null => (paintingWindow === null ? null : paintingWindow.devicePixelRatio), [paintingWindow])
-    // 大域の devicePixelRatio と同名にしない — 宣言を消したとき参照が黙って大域のウィンドウの比へ化けるため
-    const paintingRatio = useSyncExternalStore(subscribe, readDevicePixelRatio, readServerDevicePixelRatio)
-    /**
-     * Ref callback that confirms the expected painting window against the window of the wrapper's document.
-     *
-     * 描くと見込んだウィンドウを、ラッパーの文書のウィンドウと突き合わせて確かめる ref コールバック。
-     */
-    const confirmPaintingWindow = useCallback(
-        (wrapper: HTMLDivElement | null): void => {
-            if (wrapper === null) {
-                return
-            }
-            const view = windowOf(wrapper)
-            // 同じウィンドウなら描画で読んだ比が正しく、確定の段の更新 (paint 前の同期の描き直し) は要らない
-            if (view !== paintingWindow) {
-                setPaintingWindow(view)
-            }
-        },
-        [paintingWindow],
-    )
+const ItemsWrapper = ({ translateY, snapEdge, children }: ItemsWrapperProps) => {
+    const { ratio, attach } = usePaintingDevicePixelRatio("[VirtualScroll] the items wrapper")
     // ❗ ラッパーは合成層なので、平行移動が装置の画素の端数を持つとブラウザは層ごと再標本化する (実測: -2440.5px で
-    // 2px の輪郭・2px の隙間・2px の輪が 3+1+3 行に滲み、下辺の隙間が消える)。揃えるのは層の平行移動だけでよい —
-    // 層の中の行の端数の位置は描画が画素へ揃える
-    const wrapperTranslateY = paintingRatio === null ? translateY : snapToDevicePixelGrid(translateY, paintingRatio)
+    // 2px の輪郭・2px の隙間・2px の輪が 3+1+3 行に滲み、下辺の隙間が消える)。揃えるのは層の平行移動だけ —
+    // 層の中の行の端数の位置は揃わないので、行の高さを装置の画素の格子に乗せるのはホストの役目
+    const wrapperTranslateY = ratio === null ? translateY : snapToDevicePixelGrid(translateY, ratio, snapEdge)
     // ❗ 層の様式は will-change: transform だけ。perspective や 3D の変換を足すと Chromium は描画の切り取り (cull rect) を
     // 外して描くが、行を非 2D の変換の下で合成するので画素比によっては層ごと再標本化する (実測: 比 1.25 の明色で選択の輪と
     // フォーカスの輪の間の帯が混ざる)。窓をずらす 1 段がはみ出しを切る中身の行を描き直す費用は、その代わりに受け入れる
     return (
-        <div ref={confirmPaintingWindow} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
+        <div ref={attach} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
             {children}
         </div>
     )
@@ -1275,6 +1280,7 @@ const VirtualScrollInner = <T,>(
         testId,
         onScroll,
         onRangeChange,
+        onScrollAdjust,
         children,
         background,
         initialScrollIndex,
@@ -1422,11 +1428,62 @@ const VirtualScrollInner = <T,>(
 
     const [scrollPosition, setScrollPosition] = useState(initialValues.position)
     const [contentSize, setContentSize] = useState<number>(initialValues.total)
+    // 初期位置の index とアンカーは上端揃えの scrollToIndex と同じ位置なので、その位置の上端揃えとして覚えておく
+    const [alignedEdge, setAlignedEdge] = useState<AlignedEdge | null>(() => ((initialScrollAnchor && itemCount > 0) || typeof initialScrollIndex === "number" ? { edge: "start", panePosition: initialValues.position } : null))
+    // 状態の同期の写し。手動スクロールのたびに状態へ null を書くと、同じ値でも React が描画を予約し得るため、写しで要否を決める
+    const alignedEdgeRef = useRef(alignedEdge)
+
+    /**
+     * 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.
+     *
+     * あるペイン位置で成り立つ揃えを覚える処理 (`null` で忘れる)。行ラッパーが揃えに使う状態と、その同期の写しへ書く。
+     *
+     * @param next - The alignment, or `null` / 揃え (無ければ `null`)
+     */
+    const rememberAlignedEdge = useCallback((next: AlignedEdge | null): void => {
+        alignedEdgeRef.current = next
+        setAlignedEdge(next)
+    }, [])
+
+    /**
+     * 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`.
+     *
+     * 揃えた行をその場に留める位置の変化 (レイアウトシフトの補正) に合わせて、覚えた揃えを動かす処理。揃えが
+     * `fromPanePosition` で成り立っていたなら、`toPanePosition` で成り立つ。
+     *
+     * @param fromPanePosition - Pane position before the change / 変化の前のペイン位置
+     * @param toPanePosition - Pane position after the change / 変化の後のペイン位置
+     */
+    const carryAlignedEdge = useCallback(
+        (fromPanePosition: number, toPanePosition: number): void => {
+            const current = alignedEdgeRef.current
+            if (current === null || Math.abs(current.panePosition - fromPanePosition) > EDGE_POSITION_TOLERANCE) {
+                return
+            }
+            rememberAlignedEdge({ edge: current.edge, panePosition: toPanePosition })
+        },
+        [rememberAlignedEdge],
+    )
+
+    /**
+     * Forgets the remembered alignment (a scroll the user started moves the list away from it).
+     *
+     * 覚えた揃えを忘れる処理 (利用者が始めたスクロールは一覧を揃えから離す)。
+     */
+    const forgetAlignedEdge = useCallback((): void => {
+        if (alignedEdgeRef.current !== null) {
+            rememberAlignedEdge(null)
+        }
+    }, [rememberAlignedEdge])
 
     const latestScrollPositionRef = useRef(initialValues.position)
     const previousTopInsetRef = useRef(resolvedInsets.top)
     const onScrollRef = useRef<OnScrollCallback | undefined>(onScroll ?? undefined)
     const onRangeChangeRef = useRef<OnRangeChangeCallback | undefined>(onRangeChange ?? undefined)
+    // 位置を自分で動かしたことの知らせは、補正の最中 (updateItemSize・マイクロタスク・effect) から同期で呼ぶので ref から読む
+    const onScrollAdjustRef = useRef<((adjustment: VirtualScrollAdjustment) => void) | undefined>(onScrollAdjust)
     // 横委譲コールバックを ref 経由で読む。行キーハンドラ (handleItemKeyDown) は全行の React.memo が
     // 依存する安定参照でなければならず、コールバックの差し替えで identity を変えられないため。
     const onWheelHorizontalRef = useRef<((deltaX: number) => void) | undefined>(onWheelHorizontal)
@@ -1477,11 +1534,12 @@ const VirtualScrollInner = <T,>(
     // **1 フレーム古いコールバック**を読む窓を消すため (通常の effect はペイントを跨いで遅延しうる)
     useLayoutEffect(() => {
         // 目的: 外部から渡されたコールバックの参照を最新状態に保つ。
-        // 依存関係: onRangeChange, onScroll, onWheelHorizontal
+        // 依存関係: onRangeChange, onScroll, onScrollAdjust, onWheelHorizontal
         onScrollRef.current = onScroll ?? undefined
         onRangeChangeRef.current = onRangeChange ?? undefined
+        onScrollAdjustRef.current = onScrollAdjust
         onWheelHorizontalRef.current = onWheelHorizontal
-    }, [onRangeChange, onScroll, onWheelHorizontal])
+    }, [onRangeChange, onScroll, onScrollAdjust, onWheelHorizontal])
 
     const tryFocusElement = useCallback(
         (element: HTMLElement | null) => {
@@ -1723,6 +1781,39 @@ const VirtualScrollInner = <T,>(
         return appliedPosition
     }, [])
 
+    /**
+     * Runs one position change VirtualScroll makes on its own (`move` updates the pane, the latest position and, where it
+     * applies, the tree), then reports it through `onScrollAdjust` with the change of `getScrollPosition()` it applied.
+     * Nothing is reported without a connected pane or when the position did not change.
+     *
+     * VirtualScroll が自分で行う位置の変化を 1 回実行し (`move` がペイン・最新の位置・必要なら木を更新する)、それが
+     * `getScrollPosition()` に与えた変化を `onScrollAdjust` で知らせる処理。ペインが繋がっていないときと、位置が変わら
+     * なかったときは知らせない。
+     *
+     * @param cause - Why the position moves / 位置が動く理由
+     * @param move - The change itself / 変化そのもの
+     */
+    const applySelfAdjustment = useCallback((cause: VirtualScrollAdjustmentCause, move: () => void): void => {
+        const pane = scrollPaneRef.current
+        if (pane === null) {
+            move()
+            return
+        }
+        const panePositionBefore = pane.getScrollPosition()
+        move()
+        const notify = onScrollAdjustRef.current
+        if (notify === undefined) {
+            return
+        }
+        // 知らせる位置と差は getScrollPosition() と同じ論理座標 (ペインの位置から上のインセットを除く)。ホストは知らせの中で
+        // ハンドルを読み直すので、ハンドルが返す値と食い違う数を渡さない
+        const position = toLogicalPositionWithInset(pane.getScrollPosition(), resolvedInsetsTopRef.current)
+        const delta = position - toLogicalPositionWithInset(panePositionBefore, resolvedInsetsTopRef.current)
+        if (delta !== 0) {
+            notify({ position, delta, cause })
+        }
+    }, [])
+
     const didApplyInitialOffsetRef = useRef(false)
 
     /**
@@ -1773,14 +1864,16 @@ const VirtualScrollInner = <T,>(
             pendingCompensationRef.current = false
             const pane = scrollPaneRef.current
             if (pane && Math.abs(pane.getScrollPosition() - latestScrollPositionRef.current) > 0.5) {
-                const appliedPosition = issueCompensationScroll(latestScrollPositionRef.current)
-                // 再発行後もなお目標に届かない場合 (目標が負値等) はクランプ済み実位置へ収束させ、
-                // 再発行の連鎖を断つ
-                pendingCompensationRef.current = false
-                updateScrollPositionImmediate(appliedPosition, { immediate: true })
+                applySelfAdjustment("re-issue", () => {
+                    const appliedPosition = issueCompensationScroll(latestScrollPositionRef.current)
+                    // 再発行後もなお目標に届かない場合 (目標が負値等) はクランプ済み実位置へ収束させ、
+                    // 再発行の連鎖を断つ
+                    pendingCompensationRef.current = false
+                    updateScrollPositionImmediate(appliedPosition, { immediate: true })
+                })
             }
         }
-    }, [fenwickTree, contentSize, itemCount, issueCompensationScroll, updateScrollPositionImmediate])
+    }, [fenwickTree, contentSize, itemCount, applySelfAdjustment, issueCompensationScroll, updateScrollPositionImmediate])
 
     useEffect(() => {
         // 目的: サイズ変更やスクロール等でターゲットインデックスの位置がずれた場合、スクロール位置を補正 (ドリフト補正) する。
@@ -1809,23 +1902,29 @@ const VirtualScrollInner = <T,>(
                 const maxScrollPosition = Math.max(0, contentSize + resolvedInsets.top + resolvedInsets.bottom - viewportSize)
                 const targetPanePosition = Math.min(toPanePositionWithInset(targetLogicalPosition, resolvedInsets.top), maxScrollPosition)
 
-                if (Math.abs(targetPanePosition - latestScrollPositionRef.current) > 1.0) {
+                // ❗ 1px 未満のずれも留め直す。揃えた行 (最後の行の下端揃えなど) の端の余白を、行の高さの端数の変化が削ったまま残さない
+                if (Math.abs(targetPanePosition - latestScrollPositionRef.current) > EDGE_POSITION_TOLERANCE) {
                     Logger.debug("[VirtualScroll] Drift correction", {
                         from: latestScrollPositionRef.current,
                         to: targetPanePosition,
                         targetIndex: safeIndex,
                     })
-                    // Guard against double increment if multiple effects fire before scroll handles it
-                    if (isCompensatingRef.current === 0) {
-                        isCompensatingRef.current += 1
-                    }
-                    scrollPaneRef.current?.scrollTo(targetPanePosition)
-                    updateScrollPositionImmediate(targetPanePosition, { immediate: true })
+                    applySelfAdjustment("drift", () => {
+                        // 複数の effect がペインのスクロールの処理より先に走っても、補正の数を二重に数えない
+                        if (isCompensatingRef.current === 0) {
+                            isCompensatingRef.current += 1
+                        }
+                        scrollPaneRef.current?.scrollTo(targetPanePosition)
+                        updateScrollPositionImmediate(targetPanePosition, { immediate: true })
+                        // 留め直した位置で、保留中の揃えの端が成り立つ (知らせの前に覚える — 知らせの中のハンドルの呼び出しが新しい揃えを覚えたら、それを上書きしない)
+                        const edge = edgeOfAlignment(align)
+                        rememberAlignedEdge(edge === null ? null : { edge, panePosition: targetPanePosition })
+                    })
                 }
             }
         }
         isResizingRef.current = false
-    }, [contentSize, fenwickTree, itemCount, resolvedInsets.top, updateScrollPositionImmediate, viewportSize, resolvedInsets.bottom])
+    }, [contentSize, fenwickTree, itemCount, resolvedInsets.top, applySelfAdjustment, rememberAlignedEdge, updateScrollPositionImmediate, viewportSize, resolvedInsets.bottom])
 
     useEffect(() => {
         // 目的: 上部インセットが動的に変更された場合、論理スクロール位置を維持したまま、ペインのスクロール位置を再計算してずらす。
@@ -1853,11 +1952,18 @@ 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.
+     * height reconciliation on the next render. A change above the first visible row 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` の値へ巻き戻る。先頭の可視行より上の変化はスクロール位置を
+     * 同じ差だけ動かし (レイアウトシフトの補正)、覚えた揃えも一緒に動かして、戻る前に `onScrollAdjust`
+     * (`"item-resize"`) で知らせる。
+     *
+     * @param index - Item index / アイテムのインデックス
+     * @param size - New size in px / 新しいサイズ (px)
      */
     const updateItemSize = useCallback(
         (index: number, size: number) => {
@@ -1902,21 +2008,30 @@ const VirtualScrollInner = <T,>(
                 const currentPanePosition = latestScrollPositionRef.current
                 const newPosition = currentPanePosition + delta
 
-                // 同一同期バッチ内では ScrollPane の sizeRef が旧 contentSize のままのため、scrollTo は
-                // 旧最大値でクランプされ得る。issueCompensationScroll がカウンタのリークを防ぎつつ乖離時の
-                // 再発行を予約し、論理位置 (latestScrollPositionRef) には補正目標を保持して二段目の収束先とする。
-                issueCompensationScroll(newPosition, delta)
-                updateScrollPositionImmediate(newPosition, { immediate: true })
+                applySelfAdjustment("item-resize", () => {
+                    // 同一同期バッチ内では ScrollPane の sizeRef が旧 contentSize のままのため、scrollTo は
+                    // 旧最大値でクランプされ得る。issueCompensationScroll がカウンタのリークを防ぎつつ乖離時の
+                    // 再発行を予約し、論理位置 (latestScrollPositionRef) には補正目標を保持して二段目の収束先とする。
+                    issueCompensationScroll(newPosition, delta)
+                    updateScrollPositionImmediate(newPosition, { immediate: true })
+                    carryAlignedEdge(currentPanePosition, newPosition)
+                })
                 Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (manual update)", { from: currentPanePosition, to: newPosition, causedByIndex: safeIndex, delta, activeVisibleStartIndex })
             }
         },
-        [fenwickTree, itemCount, issueCompensationScroll, updateScrollPositionImmediate, contentInsets],
+        [fenwickTree, itemCount, applySelfAdjustment, carryAlignedEdge, issueCompensationScroll, updateScrollPositionImmediate, contentInsets],
     )
 
     /**
-     * Scrolls to the requested logical index.
+     * 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`).
+     *
+     * 指定インデックスへのスクロールを実行する処理。ペインを揃えた位置 (中身の範囲へクランプ) へ厳密に着地させ、ドリフト補正の
+     * 保留中の揃えとして留め、行ラッパーの装置の画素への揃えのためにその位置で揃えの端を覚える (`resolveItemsWrapperSnapEdge`)。
      *
-     * 指定インデックスへのスクロールを実行。
+     * @param index - Item index / アイテムのインデックス
+     * @param options - Alignment (`"top"` by default) and offset / 揃え方 (既定は `"top"`) と offset
      */
     const scrollToIndex = useCallback(
         (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number }) => {
@@ -1972,9 +2087,13 @@ const VirtualScrollInner = <T,>(
                 align: options?.align,
                 offset: options?.offset,
             }
+            const edge = edgeOfAlignment(options?.align)
+            rememberAlignedEdge(edge === null ? null : { edge, panePosition: clampedPaneOffset })
 
             const currentPanePosition = scrollPaneRef.current?.getScrollPosition() ?? -1
-            const shouldScroll = Math.abs(currentPanePosition - clampedPaneOffset) > 0.5
+            // ❗ 揃えは厳密に着地させる。半ピクセル未満のずれを残すと、揃えた行の端の余白をそのずれが削り、行ラッパーを
+            // 揃えた端の側へ丸めても取り戻せない (覚えた揃えもペインの位置と一致せず効かない)
+            const shouldScroll = Math.abs(currentPanePosition - clampedPaneOffset) > EDGE_POSITION_TOLERANCE
 
             // Reset flags for strict accounting to avoid leaks
             // リークを防ぐため、補正関連のフラグをリセットします
@@ -1997,7 +2116,7 @@ const VirtualScrollInner = <T,>(
 
             Logger.debug("[VirtualScroll] Setting scroll position to:", clampedPaneOffset, { original: paneOffset, max: maxScrollPosition })
         },
-        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, updateScrollPositionImmediate],
+        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, rememberAlignedEdge, updateScrollPositionImmediate],
     )
 
     // アンカー付きマウントが itemCount 0 で始まった場合の遅延適用 (一度きり)。
@@ -2157,6 +2276,7 @@ const VirtualScrollInner = <T,>(
             const isCommittedResize = isResizingRef.current && prevItemCountRef.current === itemCount
             if (!(isProgrammatic || isCompensating || isCommittedResize)) {
                 pendingVisibleStartIndexRef.current = null
+                forgetAlignedEdge()
             }
 
             updateScrollPositionImmediate(newPosition)
@@ -2184,7 +2304,7 @@ const VirtualScrollInner = <T,>(
                 }
             }
         },
-        [updateScrollPositionImmediate, enableScrollToTopBottomButtons, itemCount],
+        [updateScrollPositionImmediate, forgetAlignedEdge, enableScrollToTopBottomButtons, itemCount],
     )
 
     // レンダリング範囲を計算
@@ -2640,10 +2760,13 @@ const VirtualScrollInner = <T,>(
 
                 if (shiftAmount !== 0) {
                     const newPosition = panePosition + shiftAmount
-                    // updateItemSize と同型: scrollTo は旧 contentSize でクランプされ得るため、
-                    // issueCompensationScroll でリークを防ぎつつ、乖離時は contentSize 同期 effect で再発行する。
-                    issueCompensationScroll(newPosition, shiftAmount)
-                    updateScrollPositionImmediate(newPosition, { immediate: true })
+                    applySelfAdjustment("reconciliation", () => {
+                        // updateItemSize と同型: scrollTo は旧 contentSize でクランプされ得るため、
+                        // issueCompensationScroll でリークを防ぎつつ、乖離時は contentSize 同期 effect で再発行する。
+                        issueCompensationScroll(newPosition, shiftAmount)
+                        updateScrollPositionImmediate(newPosition, { immediate: true })
+                        carryAlignedEdge(panePosition, newPosition)
+                    })
                     Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (auto update)", { from: panePosition, to: newPosition, shiftAmount })
                 } else if (panePosition !== latestScrollPositionRef.current) {
                     updateScrollPositionImmediate(panePosition)
@@ -2653,6 +2776,8 @@ const VirtualScrollInner = <T,>(
 
         return { visibleItems: nodes, renderAnchor: currentAnchor }
     }, [
+        applySelfAdjustment,
+        carryAlignedEdge,
         children,
         clipItemHeight,
         contentSize,
@@ -2678,11 +2803,14 @@ const VirtualScrollInner = <T,>(
     /**
      * Renders the items wrapper for the pane's current scroll position (ScrollPane's `children` render prop).
      * The wrapper carries the scroll offset, the top inset and the render anchor as one translate, which
-     * `ItemsWrapper` snaps to the device-pixel grid of the window that paints it; rows keep their exact tops.
+     * `ItemsWrapper` snaps to the device-pixel grid of the window that paints it, toward the edge chosen by
+     * `resolveItemsWrapperSnapEdge` (position 0, the maximum position, or the remembered alignment); rows keep their
+     * exact tops.
      *
      * ペインの現在のスクロール位置に対する行ラッパーを描く処理 (ScrollPane の `children` の描画関数)。スクロール位置・
      * 上のインセット・描画アンカーを 1 つの平行移動としてラッパーが運び、`ItemsWrapper` がそれを描くウィンドウの
-     * 装置の画素の格子へ揃える。行の上端は厳密値のまま。
+     * 装置の画素の格子へ、`resolveItemsWrapperSnapEdge` が選ぶ端 (位置 0・最大位置・覚えた揃え) の側で揃える。
+     * 行の上端は厳密値のまま。
      *
      * @param currentScrollPosition - The pane's scroll position in PANE coordinates / ペイン座標のスクロール位置
      * @returns The items wrapper, or the empty state when there are no items / 行ラッパー (項目が無ければ空状態)
@@ -2719,6 +2847,9 @@ const VirtualScrollInner = <T,>(
             // 毎フレームのリフローを避けコンポジタのみで完結させる。
             // アンカーは visibleItems と同じ memo の返り値を使い、行 top との整合を保証する。
             const containerTop = resolvedInsets.top + renderAnchor - rawEffectiveScrollPosition
+            const contentTotal = fenwickTree.getTotal()
+            // ペインがクランプに使うのと同じ和 (中身 + インセット - ビューポート) で、ペインが最大位置に止まっているかを判定する
+            const snapEdge = resolveItemsWrapperSnapEdge(rawEffectiveScrollPosition, contentTotal + resolvedInsets.top + resolvedInsets.bottom - viewportSize, alignedEdge)
 
             const bottomInset =
                 resolvedInsets.bottom > 0 ? (
@@ -2727,7 +2858,7 @@ const VirtualScrollInner = <T,>(
                         className="aqvs-bottom-inset"
                         style={{
                             // ラッパー座標での bottom インセット位置 = コンテンツ総高さ (最終行の下端) - アンカー。
-                            top: fenwickTree.getTotal() - renderAnchor,
+                            top: contentTotal - renderAnchor,
                             height: resolvedInsets.bottom,
                         }}
                     />
@@ -2735,19 +2866,20 @@ const VirtualScrollInner = <T,>(
 
             Logger.debug("[VirtualScroll] Rendering items", () => ({
                 containerTop,
+                snapEdge,
                 logicalScrollPosition,
                 resolvedInsets,
                 effectiveScrollPosition,
             }))
 
             return (
-                <ItemsWrapper translateY={containerTop}>
+                <ItemsWrapper translateY={containerTop} snapEdge={snapEdge}>
                     {visibleItems}
                     {bottomInset}
                 </ItemsWrapper>
             )
         },
-        [callbackThrottleMs, itemCount, fenwickTree, logicalScrollPosition, renderAnchor, renderingEndIndex, renderingStartIndex, resolvedInsets, scrollPosition, viewportSize, visibleItems],
+        [alignedEdge, callbackThrottleMs, itemCount, fenwickTree, logicalScrollPosition, renderAnchor, renderingEndIndex, renderingStartIndex, resolvedInsets, scrollPosition, viewportSize, visibleItems],
     )
 
     const currentRange = useMemo<VirtualScrollRange>(