@aiquants/virtualscroll 3.7.1 → 3.8.0

package/src/VirtualScroll.tsx

@@ -127,13 +127,49 @@ export type VirtualScrollHandle = {
     updateItemSize: (index: number, size: number) => void
 }
 
+/**
+ * Scrollbar options of `VirtualScroll` (forwarded to its ScrollPane and bar) and of `VirtualGrid`
+ * (see `VirtualGridProps["scrollBarOptions"]` for which members reach which of the grid's two bars).
+ *
+ * `VirtualScroll` のスクロールバー設定 (ScrollPane とそのバーへ転送) であり、`VirtualGrid` の
+ * スクロールバー設定でもある (グリッドの 2 本のバーのどちらへ届くかは `VirtualGridProps["scrollBarOptions"]` 参照)。
+ */
 export type VirtualScrollScrollBarOptions = {
+    /** Scrollbar thickness in px (default 12). / スクロールバーの太さ (px、既定 12)。 */
     width?: number
+    /** Whether dragging the thumb scrolls (default `true`). / つまみのドラッグ操作を許可するかどうか (既定 `true`)。 */
     enableThumbDrag?: boolean
+    /** Whether pressing the track scrolls there (default `true`). / トラックの押下によるスクロールを許可するかどうか (既定 `true`)。 */
     enableTrackClick?: boolean
+    /** 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:
+     * `ScrollBarProps["enableArrowButtonTabStops"]`.
+     * スクロールバーの矢印ボタンを Tab の止まり先にするかどうか (既定 `true`)。ホストがキーボード
+     * スクロールを既に提供する場合 (行のロービングフォーカスと矢印 / Page / Home / End) に `false` —
+     * 矢印はバー 1 本あたり冗長な Tab の止まり先を 2 つ足すだけになるため (ネイティブのスクロールバーも
+     * Tab の止まり先にならない)。`false` が変えるのは `tabIndex` (`-1`) だけで、ポインタ操作・
+     * アクセシブルネームと、スクリプトからフォーカスした矢印の Enter / Space は維持。既定が `true`
+     * なのは、行が Tab の止まり先ではないため、ホストのキーボードモデルが無ければ矢印がキーボード
+     * 利用者の Tab で届く唯一のスクロール操作部品だから。契約の全文は
+     * `ScrollBarProps["enableArrowButtonTabStops"]`。
+     */
+    enableArrowButtonTabStops?: boolean
+    /**
+     * Whether to show the auto-hiding Top / Bottom pills (default `false`; texts from `labels.scrollToTop` / `labels.scrollToBottom`).
+     * 自動で隠れる Top / Bottom ピルを表示するかどうか (既定 `false`。文言は `labels.scrollToTop` / `labels.scrollToBottom`)。
+     */
     enableScrollToTopBottomButtons?: boolean
+    /** Renderer for UI anchored near the thumb. / つまみ付近に重ねる UI のレンダラー。 */
     renderThumbOverlay?: ScrollPaneProps["renderThumbOverlay"]
+    /** Tap-scroll circle options (VirtualGrid: its single two-axis circle). / タップスクロールサークルの設定 (VirtualGrid では唯一の 2 軸サークル)。 */
     tapScrollCircleOptions?: ScrollPaneProps["tapScrollCircleOptions"]
 }
 
@@ -488,11 +524,11 @@ const toPanePositionWithInset = (logical: number, top: number) => (logical <= 0
  * Maximum run length of consecutive zero-height rows scanned linearly before attempting an
  * O(log n) jump to the next non-zero row via the Fenwick tree. Module-level export (NOT in the
  * package barrel) so VirtualGrid's column axis shares the SAME constant instead of duplicating
- * the value (the §5 no-copy rule — same treatment as ANCHOR_REBASE_DISTANCE).
+ * the value (a shared constant is never copied — same treatment as ANCHOR_REBASE_DISTANCE).
  *
  * 高さ 0 行の連続をこの件数まで線形走査し、超えたら Fenwick 木で次の非 0 行へ O(log n) ジャンプ
  * する閾値。モジュールレベル export (バレル非公開) — VirtualGrid 列軸が値の複製でなく同一定数を
- * 共有するため (§5 複製禁止規範 — ANCHOR_REBASE_DISTANCE と同じ扱い)。
+ * 共有するため (共有定数は複製しない — ANCHOR_REBASE_DISTANCE と同じ扱い)。
  */
 export const ZERO_HEIGHT_RUN_LIMIT = 1000
 
@@ -520,6 +556,51 @@ 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 (バレル非公開)。
+ *
+ * @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 より大きい有限数でないとき
+ */
+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
+}
+
+/**
+ * Returns the window of the document the element belongs to — the window whose screen paints it.
+ *
+ * 要素が属する文書のウィンドウ (要素を描く画面を持つウィンドウ) を返す処理。大域の `window` は使わない
+ * (別ウィンドウ・iframe へ描いた一覧の装置の画素比は、そのウィンドウのもの)。
+ *
+ * @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) / 要素の文書がウィンドウを持たないとき (閲覧の文脈の外の文書で、何も描かれない)
+ */
+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
+}
+
 /**
  * Pixels emitted per horizontal arrow key press. Matches the ~40px browsers scroll for an arrow key.
  *
@@ -1047,7 +1128,7 @@ const VirtualScrollInner = <T,>(
     }: VirtualScrollProps<T>,
     ref: React.Ref<VirtualScrollHandle>,
 ) => {
-    const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
+    const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableArrowButtonTabStops, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
     const resolvedLabels = useMemo(() => resolveVirtualScrollLabels(locale, labels), [locale, labels])
 
     const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, enableEscapeRowReturn = false, wheelSpeedMultiplier, inertiaOptions, overscrollBehavior, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
@@ -2426,6 +2507,78 @@ const VirtualScrollInner = <T,>(
         visibleStartIndex,
     ])
 
+    // 行ラッパーを描くウィンドウの装置の画素比。ラッパーの最初の取り付けまで (サーバー描画と初回描画) は null。
+    // 大域の devicePixelRatio と同名にしない — 宣言を消したとき参照が黙って大域のウィンドウの比へ化けるため
+    const [wrapperDevicePixelRatio, setWrapperDevicePixelRatio] = useState<number | null>(null)
+
+    /**
+     * Ref callback of the items wrapper. Commits the device-pixel ratio of the window the wrapper is painted in
+     * (`windowOf`, never the global `window`), and commits it again whenever that ratio changes (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. The first commit runs in React's commit phase, so a client mount
+     * paints the snapped translate in its first frame. A window without media queries (jsdom) cannot change its
+     * ratio: the ratio read at attach applies and no watch is armed. The callback identity is stable, so React
+     * calls it once per attach. React 19 calls the returned cleanup on detach; it calls the ref with `null`
+     * only when the attach threw (no cleanup exists), and that call does nothing.
+     *
+     * 行ラッパーの ref コールバック。ラッパーを描くウィンドウ (`windowOf`。大域の `window` ではない) の装置の
+     * 画素比を状態へ確定し、比が変わるたび (ブラウザの拡大縮小・密度の違う画面へのウィンドウの移動) に
+     * `(resolution: <比>dppx)` のメディアクエリの監視で確定し直す (監視は新しい比で張り直す)。最初の確定は
+     * React の確定の段で走るので、クライアントでのマウントは最初のフレームから揃えた平行移動で描く。
+     * メディアクエリを持たないウィンドウ (jsdom) は比が変わり得ないので、取り付け時に読んだ比を使い監視は
+     * 張らない。コールバックの同一性は安定しているので、React は取り付け 1 回につき 1 回だけ呼ぶ。取り外し時に
+     * React 19 は返した後始末を呼び、ref を `null` で呼ぶのは取り付けが投げて後始末が無いときだけ (何もしない)。
+     *
+     * @param wrapper - The attached items wrapper, or `null` on the detach that follows an attach that threw / 取り付けた行ラッパー (投げた取り付けの後の取り外しでは `null`)
+     * @returns Cleanup that removes the resolution watch, or `undefined` for `null` / 解像度の監視を外す後始末 (`null` には `undefined`)
+     * @throws {Error} When the wrapper's document has no window (see `windowOf`) / ラッパーの文書がウィンドウを持たないとき (`windowOf` を参照)
+     */
+    const observeItemsWrapperDevicePixelRatio = useCallback((wrapper: HTMLDivElement | null): (() => void) | undefined => {
+        // 後始末を返した ref を React 19 は null で呼ばない。null が届くのは取り付けが投げた後だけで、外す監視も無い
+        if (wrapper === null) {
+            return undefined
+        }
+        const view = windowOf(wrapper)
+        let resolutionQuery: MediaQueryList | undefined
+        /**
+         * Commits the window's current device-pixel ratio and re-arms the resolution watch at that ratio.
+         *
+         * ウィンドウの現在の装置の画素比を確定し、その比で解像度の監視を張り直す処理。
+         */
+        const syncDevicePixelRatio = (): void => {
+            resolutionQuery?.removeEventListener("change", syncDevicePixelRatio)
+            const ratio = view.devicePixelRatio
+            setWrapperDevicePixelRatio(ratio)
+            // ❗ `(resolution: Ndppx)` が知らせるのは比 N との一致・不一致の切り替わりだけ。N 以外の比どうしの変化
+            // (もう一度の拡大縮小・さらに別の画面への移動) を捉えるには、変化のたびに新しい比で張り直すしかない。
+            // matchMedia を持たないウィンドウ (jsdom) は比が変わり得ないので監視だけを省く (読んだ比は使う)
+            resolutionQuery = typeof view.matchMedia === "function" ? view.matchMedia(`(resolution: ${ratio}dppx)`) : undefined
+            resolutionQuery?.addEventListener("change", syncDevicePixelRatio)
+        }
+        syncDevicePixelRatio()
+        /**
+         * Removes the resolution watch; React calls it when the wrapper detaches.
+         *
+         * 解像度の監視を外す後始末 (ラッパーの取り外し時に React が呼ぶ)。
+         */
+        const stopObservingDevicePixelRatio = (): void => {
+            resolutionQuery?.removeEventListener("change", syncDevicePixelRatio)
+        }
+        return stopObservingDevicePixelRatio
+    }, [])
+
+    /**
+     * 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, snapped to
+     * the device-pixel grid once the wrapper is attached (`snapToDevicePixelGrid`); rows keep their exact tops.
+     *
+     * ペインの現在のスクロール位置に対する行ラッパーを描く処理 (ScrollPane の `children` の描画関数)。スクロール位置・
+     * 上のインセット・描画アンカーを 1 つの平行移動としてラッパーが運び、ラッパーの取り付け後はそれを装置の画素の
+     * 格子へ揃える (`snapToDevicePixelGrid`)。行の上端は厳密値のまま。
+     *
+     * @param currentScrollPosition - The pane's scroll position in PANE coordinates / ペイン座標のスクロール位置
+     * @returns The items wrapper, or the empty state when there are no items / 行ラッパー (項目が無ければ空状態)
+     */
     const renderVisibleItems = useCallback(
         (currentScrollPosition: number) => {
             const shouldUseThrottledPosition = (callbackThrottleMs ?? 0) > 0
@@ -2458,6 +2611,12 @@ const VirtualScrollInner = <T,>(
             // 毎フレームのリフローを避けコンポジタのみで完結させる。
             // アンカーは visibleItems と同じ memo の返り値を使い、行 top との整合を保証する。
             const containerTop = resolvedInsets.top + renderAnchor - rawEffectiveScrollPosition
+            // ❗ ラッパーは合成層 (willChange: transform) なので、平行移動が装置の画素の端数を持つとブラウザは層ごと
+            // 再標本化する (実測: -2440.5px で 2px の輪郭・2px の隙間・2px の輪が 3+1+3 行に滲み、下辺の隙間が消える)。
+            // 揃えるのは層の平行移動だけでよい — 層の中の行の端数の位置は描画が画素へ揃える。比が決まるのは
+            // ラッパーの取り付け時なので、それまで (サーバー描画と初回描画) は描く画面が無く厳密値のまま書く。
+            // クライアントのマウントは取り付けの確定が paint 前に再描画するので、端数のまま描かれることはない
+            const wrapperTranslateY = wrapperDevicePixelRatio === null ? containerTop : snapToDevicePixelGrid(containerTop, wrapperDevicePixelRatio)
 
             const bottomInset =
                 resolvedInsets.bottom > 0 ? (
@@ -2474,19 +2633,21 @@ const VirtualScrollInner = <T,>(
 
             Logger.debug("[VirtualScroll] Rendering items", () => ({
                 containerTop,
+                wrapperDevicePixelRatio,
+                wrapperTranslateY,
                 logicalScrollPosition,
                 resolvedInsets,
                 effectiveScrollPosition,
             }))
 
             return (
-                <div className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${containerTop}px)`, willChange: "transform" }}>
+                <div ref={observeItemsWrapperDevicePixelRatio} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
                     {visibleItems}
                     {bottomInset}
                 </div>
             )
         },
-        [callbackThrottleMs, itemCount, fenwickTree, logicalScrollPosition, renderAnchor, renderingEndIndex, renderingStartIndex, resolvedInsets, scrollPosition, viewportSize, visibleItems],
+        [callbackThrottleMs, itemCount, fenwickTree, logicalScrollPosition, observeItemsWrapperDevicePixelRatio, renderAnchor, renderingEndIndex, renderingStartIndex, resolvedInsets, scrollPosition, viewportSize, visibleItems, wrapperDevicePixelRatio],
     )
 
     const currentRange = useMemo<VirtualScrollRange>(
@@ -2602,6 +2763,7 @@ const VirtualScrollInner = <T,>(
             enableThumbDrag={enableThumbDrag}
             enableTrackClick={enableTrackClick}
             enableArrowButtons={enableArrowButtons}
+            enableArrowButtonTabStops={enableArrowButtonTabStops}
             enablePointerDrag={enablePointerDrag}
             pointerDragInputs={pointerDragInputs}
             renderThumbOverlay={renderThumbOverlay}

package/src/computeTapScrollVelocity.ts

@@ -60,7 +60,7 @@ export type TapScrollVelocityInput = {
  *   so never assert bit-equality (`toBe` / `Object.is`) of a pure-axis component against
  *   `computeTapScrollSpeed` outside the committed exact fixtures. The rejected order
  *   `s * (o / r)` would be bit-exact on pure axes (`o / r = ±1` exactly); the pin below
- *   trades that for fixture-order independence (plan §4.2 T1 / §4.3).
+ *   trades that for fixture-order independence (see the evaluation-order pin below).
  * - D2 (radial law under isotropy): when `s_x = s_y = s`, `|v| = s(r)` at every angle.
  * - D3 (separability): `v_a = s_a(r) * u_a(theta)` for a direction-only unit field `u`.
  * - D4 (isotropic direction fidelity — a CHOSEN axiom, not derived): when `s_x = s_y`,
@@ -69,8 +69,8 @@ export type TapScrollVelocityInput = {
  * D1-D3 alone do NOT force this law: they admit the whole family
  * `u = (cos phi(theta), sin phi(theta))` for any continuous strictly increasing angle remap
  * `phi` fixing the four cardinal angles (e.g. `phi(theta) = theta - epsilon * sin(4 theta)`).
- * D4 pins `phi = id`. That family is the registered invariant-preserving tuning point for
- * near-axis leakage (plan §4.4); v3.6.0 ships `phi = id`.
+ * D4 pins `phi = id`. That family is the invariant-preserving tuning point for near-axis
+ * leakage; the package ships `phi = id`.
  *
  * Evaluation-order pin: each component is computed literally as `s_a(r) * o_a / r`
  * (left-to-right, i.e. `(s * o) / r`). The two orders differ by 1 ulp for SOME inputs —

package/src/styles/virtualscroll.css

@@ -482,7 +482,7 @@
   transform: translateX(calc(var(--aqvs-grid-hx-residual, 0px) - var(--aqvs-grid-frozen-width, 0px)));
 }
 
-/* 末尾列クリップ (3.5.0 — ADR-19-3): left の max() は先頭優先の CSS エンコード。
+/* 末尾列クリップ: left の max() は先頭優先の CSS エンコード。
  * ❗ この max() 形は trailingVisibleSize の calc() 版そのもの (クリップ左端 = extent − W_T_vis
  * が恒等) — CSS は JS ヘルパーを読めないための登記済み例外 (単一情報源レジスタのエントリ 1)。 */
 .aqvs-grid-row-trailing {

package/src/useGridTapScroll.ts

@@ -16,7 +16,7 @@ import { minmax } from "./utils.ts"
 
 /**
  * Default corner-relative offset (px) for BOTH grid tap-circle axes — the reachability arm (R)
- * of the three-arm placement law (plan §5). Derivation: full speed needs
+ * of the three-arm placement law. Derivation: full speed needs
  * `maxVisualDistance = 240 px` of advancing pull toward the far screen edge, which is a hard
  * stop on touch (`touch-action: none`). With `off = −200` the disc center sits
  * `sbw − off − size/2 = 12 + 200 − 20 = 192 px` inboard of each far root edge, giving a
@@ -26,11 +26,11 @@ import { minmax } from "./utils.ts"
  * nav-zone envelope ≥ ~2/3. Deliberately a LITERAL: it must NOT track a consumer-supplied
  * `maxVisualDistance` (coupling two knobs would make one silently move the other), and
  * shrinking `maxVisualDistance` instead is forbidden (it changes the speed law's `maxDistance`
- * input and breaks the T1 identity anchor).
+ * input, so a pure-axis drag would no longer reproduce the bar's own speed law).
  * グリッドタップサークル両軸のコーナー相対既定オフセット (px) — 3 アーム配置則の到達性アーム
  * (R)。導出: 全速には前進方向へ 240 px の引きが要り、タッチではスクリーン端がハードストップ。
  * −200 で中心は各遠端から 192 px 内側 = 最悪ケース引き分率 0.80 (ナビ帯込み 0.66)。意図的な
- * リテラル — 消費側 `maxVisualDistance` へ連動させない (ノブ連動の登記済み禁止)。
+ * リテラル — 消費側 `maxVisualDistance` へ連動させない (2 つのノブを連動させると一方が他方を黙って動かす)。
  */
 export const GRID_TAP_CIRCLE_DEFAULT_OFFSET = -200
 
@@ -51,27 +51,27 @@ export type UseGridTapScrollParams = {
     enabled: boolean
     /** Shared pull range (= `max(maxVisualDistance, 1)`). / 共有引き範囲 (= `max(maxVisualDistance, 1)`)。 */
     maxDistance: number
-    /** Horizontal speed parameters (§4.1 Pₓ). / 横軸速度パラメータ (§4.1 Pₓ)。 */
+    /** Horizontal speed parameters (Pₓ, built from the scroll-band width and the column count). / 横軸速度パラメータ (Pₓ。スクロール帯幅と列数から構成)。 */
     xSpeedParams: TapScrollAxisSpeedParams
-    /** Vertical speed parameters (§4.1 P_y). / 縦軸速度パラメータ (§4.1 P_y)。 */
+    /** Vertical speed parameters (P_y, built from the embedded pane height and the scroll-row count). / 縦軸速度パラメータ (P_y。埋め込みペイン高とスクロール行数から構成)。 */
     ySpeedParams: TapScrollAxisSpeedParams
     /** The grid's x apply seam (absolute position in, clamped applied position out). / グリッドの x 適用シーム (絶対位置 → クランプ後位置)。 */
     applyHxRef: { readonly current: (next: number) => number }
     /** Synchronous-fresh hx read. / hx の同期・最新読み。 */
     getHx: () => number
-    /** The ONE extracted x clamp law (`getMaxHx` SSOT — §3.5-7). / 唯一抽出の x クランプ則 (`getMaxHx` SSOT — §3.5-7)。 */
+    /** The ONE extracted x clamp law (`getMaxHx` SSOT — never re-derived from the grid's tree). / 唯一抽出の x クランプ則 (`getMaxHx` SSOT — グリッドの木から再導出しない)。 */
     getMaxHx: () => number
-    /** y apply seam: wraps `scrollBy(delta)` AND syncs `vyRef.current = applied` before returning (§3.5-8 — NOT a bare handle passthrough). / y 適用シーム: `scrollBy(delta)` をラップし `vyRef.current = applied` を同期してから返す (§3.5-8 — 素のハンドル素通しではない)。 */
+    /** y apply seam: wraps `scrollBy(delta)` AND syncs `vyRef.current = applied` before returning (NOT a bare handle passthrough — without the sync, x-frame notifications during a diagonal drag carry a stale y). / y 適用シーム: `scrollBy(delta)` をラップし `vyRef.current = applied` を同期してから返す (素のハンドル素通しではない — 同期が無いと対角ドラッグ中の x フレーム通知が stale な y を運ぶ)。 */
     applyVy: (delta: number) => number
     /** Synchronous-fresh vy read — MUST read the same authority `applyVy` resolves against (the embedded pane's position), never a notification mirror with a second writer (v3.6.1 — a lagging mirror base overstates `actualDelta` and drives the residual negative = yo-yo). / vy の同期・最新読み — `applyVy` が解決するのと同一権威 (埋め込みペイン位置) を読むこと。第 2 の書き手を持つ通知鏡像は禁止 (v3.6.1 — 遅延鏡像基準は `actualDelta` を過大化し残差を負へ落とすヨーヨー)。 */
     getVy: () => number
     /** y extent read through the embedded handle's freshness channel (never re-derived). / 埋め込みハンドルの鮮度チャネル経由の y 延長 (再導出禁止)。 */
     getMaxVy: () => number
-    /** Pending column anchor — cleared ONLY on frames whose APPLIED hx delta ≠ 0 (§3.5-5). / 保留列アンカー — 適用済み hx デルタ ≠ 0 のフレームのみ解除 (§3.5-5)。 */
+    /** Pending column anchor — cleared ONLY on frames whose APPLIED hx delta ≠ 0 (a request the clamp swallows keeps it). / 保留列アンカー — 適用済み hx デルタ ≠ 0 のフレームのみ解除 (クランプに吸収された要求では残す)。 */
     pendingColAnchorRef: { current: unknown }
-    /** x extent-growth freshness key (columnWindow / total width — §3.5-3). / x 延長成長の鮮度キー (columnWindow / 総幅 — §3.5-3)。 */
+    /** x extent-growth freshness key (columnWindow / total width — a change re-arms a loop parked at the edge). / x 延長成長の鮮度キー (columnWindow / 総幅 — 変化で端に止まったループを再武装)。 */
     xExtentFreshness: unknown
-    /** y extent-growth freshness key (the vertical range state — §3.5-3). / y 延長成長の鮮度キー (縦レンジ state — §3.5-3)。 */
+    /** y extent-growth freshness key (the vertical range state — a change re-arms a loop parked at the edge). / y 延長成長の鮮度キー (縦レンジ state — 変化で端に止まったループを再武装)。 */
     yExtentFreshness: unknown
 }
 
@@ -89,7 +89,7 @@ export type UseGridTapScrollResult = {
  * Owns the unified tap circle's drag state and the two-axis rAF integration loop.
  * 統合タップサークルのドラッグ状態と 2 軸 rAF 積分ループを所有するフック。
  *
- * Per-frame semantics (plan §8.3 — implemented verbatim):
+ * Per-frame semantics:
  *
  * ```text
  * dt = min(max((t − last)/1000, 0), TAP_SCROLL_MAX_FRAME_DELTA_SECONDS); skip if dt ≤ 0
@@ -186,7 +186,7 @@ export const useGridTapScroll = (params: UseGridTapScrollParams): UseGridTapScro
      */
     const step = useCallback(
         (timestamp: number) => {
-            // この rAF ループ意味論は ScrollBar.tsx の tap ループ (stepAutoScroll) と双子 — 片方を直したらもう片方も直すこと (ADR-27)
+            // この rAF ループ意味論は ScrollBar.tsx の tap ループ (stepAutoScroll) と双子 — 片方を直したらもう片方も直すこと
             const current = paramsRef.current
             const state = tapDragStateRef.current
             if (!state.active || state.direction === 0) {