@aiquants/virtualscroll 3.7.1 → 3.8.0

package/src/VirtualGrid.tsx

@@ -6,19 +6,31 @@
  * scrolling that never lands total-size pixels in the DOM). Column count inherits the full
  * row-axis scale profile (<= 2^53 - 1). Grid semantics (selection / editing / clipboard)
  * are deliberately NOT owned here — consumers attach them via getCellProps / getRowProps /
- * contentProps. Design: docs/plans/2026.09.01 virtualgrid-horizontal-axis-design-plan (v6).
+ * contentProps. Bounding contract (both axes): the anchored coordinates written to the DOM (cell /
+ * row offsets and the residual transforms) stay in the full-precision band while
+ * z × (ANCHOR_REBASE_DISTANCE + windowSpan) <= 2^24, where z is the ancestor scale and
+ * windowSpan <= viewport + (2 × overscan + 2) × MAX_TRACK_SIZE is the rendered window; with the
+ * default overscan of 3 and a viewport of at most 2^13 px it holds up to z = 5.31.
  * Since v3.6.0 the grid owns ONE unified two-axis tap circle (axis="xy", corner-anchored via the
- * three-arm placement law) driven by useGridTapScroll; both per-bar circles are suppressed
- * grid-side (docs/plans/2026.09.16 unified-tap-circle plan).
+ * three-arm placement law) driven by useGridTapScroll, so one drag vector scrolls both axes. Both
+ * per-bar circles are suppressed grid-side because two circles can never be dragged together: each
+ * bar's document-level pointerdown listener ends its own drag when the other circle is pressed.
+ * A standalone ScrollBar / VirtualScroll keeps its own circle.
  *
  * VirtualGrid — 実証済みの VirtualScroll 行軸に、対称の横列エンジン (同一の兆スケール機構:
  * 疎 Fenwick 幅木・共有 computeRenderingRanges (BigInt huge 分岐込み)・ANCHOR_REBASE_DISTANCE
  * の量子化アンカー再基準化・総サイズ px を DOM に着地させない合成スクロール) を合成した
  * 汎用 2D 仮想化プリミティブ。列数は行軸のスケールプロファイル (≤ 2^53 − 1) を完全継承する。
  * グリッド操作の意味論 (選択 / 編集 / クリップボード) は意図的に非所有 — 消費側が
- * getCellProps / getRowProps / contentProps で装着する。v3.6.0 からグリッドは統合 2 軸
- * タップサークル (axis="xy"・3 アーム則のコーナーアンカー・useGridTapScroll 駆動) を 1 つ
- * 所有し、両バーのサークルはグリッド側で抑止する。
+ * getCellProps / getRowProps / contentProps で装着する。有界化契約 (両軸): 祖先スケール z と
+ * 描画窓スパン windowSpan (≤ viewport + (2 × overscan + 2) × MAX_TRACK_SIZE) について
+ * z × (ANCHOR_REBASE_DISTANCE + windowSpan) ≤ 2^24 である限り、DOM へ書くアンカー基準の座標
+ * (セル / 行の位置と残差 transform) は完全精度帯に収まる。overscan が既定の 3 で viewport が
+ * 2^13 px 以下なら z = 5.31 まで成り立つ。v3.6.0 からグリッドは統合 2 軸タップサークル
+ * (axis="xy"・3 アーム則のコーナーアンカー・useGridTapScroll 駆動) を 1 つ所有し、1 本の
+ * ドラッグで両軸をスクロールする。両バーのサークルはグリッド側で抑止する — 2 つのサークルは
+ * 同時にドラッグできない (各バーの document 捕捉の pointerdown が、他方のサークルの押下で自身の
+ * ドラッグを終える) ため。単体の ScrollBar / VirtualScroll は自身のサークルを保つ。
  */
 
 import { type CSSProperties, forwardRef, type HTMLAttributes, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
@@ -36,13 +48,15 @@ import { ANCHOR_REBASE_DISTANCE, computeRenderingRanges, MAX_RENDERED_ITEMS, Vir
 
 /**
  * Hard per-track size cap (px) for both axes. Values above this are rejected with a RangeError
- * (fail-fast, no silent clamp): the §6 bounding contract `z × (ANCHOR_REBASE_DISTANCE +
- * windowSpan) <= 2^24` relies on every track being bounded, and a single oversized track would
- * let cell coordinates / the residual transform pierce the measured LayoutUnit wall (2^25).
+ * (fail-fast, no silent clamp): the bounding contract `z × (ANCHOR_REBASE_DISTANCE + windowSpan)
+ * <= 2^24` (z = ancestor scale, windowSpan <= viewport + (2 × overscan + 2) × MAX_TRACK_SIZE)
+ * relies on every track being bounded, and a single oversized track would let cell coordinates /
+ * the residual transform pierce the measured LayoutUnit wall (2^25).
  *
  * 両軸共通のトラックサイズ上限 (px)。超過は RangeError で fail-fast (暗黙 clamp なし):
- * §6 の有界化契約はトラック有界性に立脚し、1 本の過大トラックでセル座標 / 残差 transform が
- * 実測の LayoutUnit 壁 (2^25) を踏み抜くため。
+ * 有界化契約 `z × (ANCHOR_REBASE_DISTANCE + windowSpan) ≤ 2^24` (z = 祖先スケール、windowSpan ≤
+ * viewport + (2 × overscan + 2) × MAX_TRACK_SIZE) はトラック有界性に立脚し、1 本の過大トラックで
+ * セル座標 / 残差 transform が実測の LayoutUnit 壁 (2^25) を踏み抜くため。
  */
 export const MAX_TRACK_SIZE = 262_144 // 2^18 px
 
@@ -61,25 +75,25 @@ const DEFAULT_GRID_OVERSCAN = 3
  * Safety cap for cell nodes materialized in one render pass (rendered rows × rendered cols).
  * Unlike the row-side MAX_RENDERED_ITEMS (a pathological-input guard), the 2D product can be
  * reached by LEGITIMATE configurations (min zoom on large displays), so truncation is never
- * silent — onRenderTruncated fires. Initial value assumes WQHD; §9-3 of the design plan owns
- * the final calibration (4K floor ≈ 55,955).
+ * silent — onRenderTruncated fires. The value covers a WQHD display at minimum zoom; the same
+ * configuration on a 4K display needs about 55,955 cells and is truncated there.
  *
  * 1 レンダーで具現化するセルノード数 (描画行 × 描画列) の安全上限。行側 MAX_RENDERED_ITEMS
  * (病的入力ガード) と違い、2D 積は正当な構成 (大型ディスプレイの最小ズーム) で到達し得るため
- * 打切りは無言にしない — onRenderTruncated が発火する。初期値は WQHD 前提で、最終確定は
- * 設計計画 §9-3 の所有 (4K の床 ≈ 55,955)。
+ * 打切りは無言にしない — onRenderTruncated が発火する。値は WQHD ディスプレイの最小ズームを
+ * 賄う大きさで、同じ構成の 4K ディスプレイでは約 55,955 セルが必要となり打ち切られる。
  */
 export const MAX_RENDERED_CELLS = 32_768 // 2^15
 
 /**
- * Hard cap for `frozenLeadingCols` (design §8). The frozen band is NOT windowed — every frozen
+ * Hard cap for `frozenLeadingCols`. The frozen band is NOT windowed — every frozen
  * column materializes in every rendered row and is EXEMPT from the MAX_RENDERED_CELLS
  * truncation (the scroll-band budget is reduced by the frozen count instead) — so the cap is
  * what bounds the band: worst case 128 x MAX_RENDERED_ITEMS rows, and W_F <= 128 x
  * MAX_TRACK_SIZE = 2^25 (the measured layout wall; practical W_F <= viewport << 2^24). Real
  * frozen panes are single-digit; violations fail fast with a RangeError.
  *
- * `frozenLeadingCols` の上限 (設計 §8)。凍結帯は窓化されず全描画行で具現化し、かつ
+ * `frozenLeadingCols` の上限。凍結帯は窓化されず全描画行で具現化し、かつ
  * MAX_RENDERED_CELLS の打切り対象外 (代わりにスクロール帯予算を凍結数ぶん控除) のため、帯を
  * 有界にするのはこの上限そのもの: 最悪 128 × MAX_RENDERED_ITEMS 行、W_F ≤ 128 × MAX_TRACK_SIZE
  * = 2^25 (実測壁ちょうど — 実運用は W_F ≤ viewport ≪ 2^24)。違反は fail-fast の RangeError。
@@ -87,44 +101,42 @@ export const MAX_RENDERED_CELLS = 32_768 // 2^15
 export const MAX_FROZEN_LEADING_COLS = 128
 
 /**
- * Hard cap for `frozenLeadingRows` (frozen-rows design plan §4-1). The frozen-row band is
- * grid-owned and OUT of the embedded VirtualScroll (index-shift architecture — plan §2):
- * every band row materializes every rendered column and is exempt from MAX_RENDERED_CELLS
+ * Hard cap for `frozenLeadingRows`. The frozen-row band is grid-owned and OUT of the embedded
+ * VirtualScroll (the grid shifts the scroll rows' indices by the frozen count before handing them
+ * over): every band row materializes every rendered column and is exempt from MAX_RENDERED_CELLS
  * (the budget denominator counts band rows instead), so the cap bounds the band itself.
- * `frozenLeadingRows` の上限 (行凍結設計 §4-1)。凍結行帯はグリッド所有で埋め込み
- * VirtualScroll の外 (インデックスシフト方式 — 設計 §2)。帯行は描画列を全て具現化し
+ * Violations fail fast with a RangeError.
+ * `frozenLeadingRows` の上限。凍結行帯はグリッド所有で埋め込み VirtualScroll の外 (スクロール行の
+ * インデックスを凍結数ぶんずらしてから渡すインデックスシフト方式)。帯行は描画列を全て具現化し
  * MAX_RENDERED_CELLS の打切り対象外 (予算分母に帯行数を算入) のため、帯を有界にするのは
  * この上限そのもの。違反は fail-fast の RangeError。
  */
 export const MAX_FROZEN_LEADING_ROWS = 128
 
 /**
- * Hard cap for `frozenTrailingCols` (v3.5.0 trailing-freeze plan §3). The trailing band is NOT
- * windowed — every trailing column materializes in every rendered row and is EXEMPT from the
- * MAX_RENDERED_CELLS truncation (the scroll-band budget is reduced by the trailing count
- * instead) — so the cap is what bounds the band: worst case 128 x MAX_RENDERED_ITEMS rows, and
- * W_T <= 128 x MAX_TRACK_SIZE = 2^25 (the measured layout wall; practical W_T <= viewport <<
- * 2^24). Violations fail fast with a RangeError.
+ * Hard cap for `frozenTrailingCols`. The trailing band is NOT windowed — every trailing column
+ * materializes in every rendered row and is EXEMPT from the MAX_RENDERED_CELLS truncation (the
+ * scroll-band budget is reduced by the trailing count instead) — so the cap is what bounds the
+ * band: worst case 128 x MAX_RENDERED_ITEMS rows, and W_T <= 128 x MAX_TRACK_SIZE = 2^25 (the
+ * measured layout wall; practical W_T <= viewport << 2^24). Violations fail fast with a
+ * RangeError.
  *
- * `frozenTrailingCols` の上限 (3.5.0 末尾凍結プラン §3)。末尾帯は窓化されず全描画行で具現化し、
- * かつ MAX_RENDERED_CELLS の打切り対象外 (代わりにスクロール帯予算を末尾数ぶん控除) のため、
- * 帯を有界にするのはこの上限そのもの: 最悪 128 × MAX_RENDERED_ITEMS 行、W_T ≤ 128 ×
- * MAX_TRACK_SIZE = 2^25 (実測壁ちょうど — 実運用は W_T ≤ viewport ≪ 2^24)。違反は fail-fast の
- * RangeError。
+ * `frozenTrailingCols` の上限。末尾帯は窓化されず全描画行で具現化し、かつ MAX_RENDERED_CELLS の
+ * 打切り対象外 (代わりにスクロール帯予算を末尾数ぶん控除) のため、帯を有界にするのはこの上限
+ * そのもの: 最悪 128 × MAX_RENDERED_ITEMS 行、W_T ≤ 128 × MAX_TRACK_SIZE = 2^25 (実測壁ちょうど —
+ * 実運用は W_T ≤ viewport ≪ 2^24)。違反は fail-fast の RangeError。
  */
 export const MAX_FROZEN_TRAILING_COLS = 128
 
 /**
- * Hard cap for `frozenTrailingRows` (v3.5.0 trailing-freeze plan §3). The trailing-row band is
- * grid-owned and OUT of the embedded VirtualScroll (the SECOND out-of-pane band, below the
- * pane): every band row materializes every rendered column and is exempt from
- * MAX_RENDERED_CELLS (the budget denominator counts band rows instead), so the cap bounds the
- * band itself. Violations fail fast with a RangeError.
+ * Hard cap for `frozenTrailingRows`. The trailing-row band is grid-owned and OUT of the embedded
+ * VirtualScroll (the SECOND out-of-pane band, below the pane): every band row materializes every
+ * rendered column and is exempt from MAX_RENDERED_CELLS (the budget denominator counts band rows
+ * instead), so the cap bounds the band itself. Violations fail fast with a RangeError.
  *
- * `frozenTrailingRows` の上限 (3.5.0 末尾凍結プラン §3)。末尾行帯はグリッド所有で埋め込み
- * VirtualScroll の外 (ペインの**下**の第 2 帯外バンド)。帯行は描画列を全て具現化し
- * MAX_RENDERED_CELLS の打切り対象外 (予算分母に帯行数を算入) のため、帯を有界にするのは
- * この上限そのもの。違反は fail-fast の RangeError。
+ * `frozenTrailingRows` の上限。末尾行帯はグリッド所有で埋め込み VirtualScroll の外 (ペインの**下**の
+ * 第 2 帯外バンド)。帯行は描画列を全て具現化し MAX_RENDERED_CELLS の打切り対象外 (予算分母に
+ * 帯行数を算入) のため、帯を有界にするのはこの上限そのもの。違反は fail-fast の RangeError。
  */
 export const MAX_FROZEN_TRAILING_ROWS = 128
 
@@ -236,10 +248,10 @@ export type VirtualGridBehaviorOptions = VirtualScrollBehaviorOptions & {
      */
     resetOnGetColWidthChange?: boolean
     /**
-     * Explicit Fenwick baseValue for the column width tree (design §3.4): skips the stride
+     * Explicit Fenwick baseValue for the column width tree: skips the stride
      * sampling of getColWidth at construction, so unmaterialized columns are estimated at exactly
      * this width. Integer in [0, MAX_TRACK_SIZE] — RangeError otherwise (fail-fast, no clamp).
-     * 列幅木の Fenwick baseValue の明示指定 (設計 §3.4): 構築時の getColWidth ストライド
+     * 列幅木の Fenwick baseValue の明示指定: 構築時の getColWidth ストライド
      * サンプリングを省略し、未具現化列をこの幅で見積もる。[0, MAX_TRACK_SIZE] の整数 —
      * 違反は RangeError (fail-fast、clamp なし)。
      */
@@ -311,14 +323,14 @@ export type VirtualGridProps<T> = {
     /** Restores both axes from a {row, col, offsetY, offsetX} anchor (px-restore is refuted row-side — anchors survive estimation-space changes). / 両軸を {row, col, offsetY, offsetX} アンカーから復元 (生 px 復元は行側で反証済み)。 */
     initialScrollAnchor?: { row: number; col: number; offsetY: number; offsetX: number }
     /**
-     * Number of leading columns frozen at the left edge (design §8; default 0). The frozen band
+     * Number of leading columns frozen at the left edge (default 0). The frozen band
      * lives OUTSIDE the anchor machinery: tree coordinates [0, W_F) render as direct static
      * lefts (safe — W_F <= viewport << 2^24), the scroll band's window search starts at the
      * W_F offset, and its residual transform carries the -W_F origin-shift term. Non-negative
      * integer <= MAX_FROZEN_LEADING_COLS — RangeError otherwise (fail-fast); values beyond the
      * CURRENT colCount freeze every column (documented dynamic clamp, not a fallback — the
      * scroll band then reports the EMPTY window start > end and renders no scroll cells).
-     * 左端に凍結する先頭列数 (設計 §8。既定 0)。凍結帯はアンカー機構の**外**: 木座標 [0, W_F)
+     * 左端に凍結する先頭列数 (既定 0)。凍結帯はアンカー機構の**外**: 木座標 [0, W_F)
      * を静的 left で直接描画 (W_F は上限 128 × 2^18 = 2^25 で有界 — 実運用は viewport ≪ 2^24)、
      * スクロール帯の窓探索は W_F
      * オフセット始まり、残差 transform は −W_F の原点シフト項を持つ。0 以上の整数かつ
@@ -327,14 +339,14 @@ export type VirtualGridProps<T> = {
      */
     frozenLeadingCols?: number
     /**
-     * Number of leading rows pinned at the top (frozen-rows design plan — default 0). The band
+     * Number of leading rows pinned at the top (default 0). The band
      * is grid-owned and OUT of the embedded VirtualScroll: the scroll rows live in a SHIFTED
      * index space (itemCount = rowCount − R, getItem = i + R), so vy is the scroll-band
      * logical position and the vertical bar maps the band naturally. Non-negative integer <=
      * MAX_FROZEN_LEADING_ROWS — RangeError otherwise (fail-fast); values beyond the CURRENT
      * rowCount freeze every row (documented dynamic clamp — the scroll rows then report the
      * canonical EMPTY window start > end and render nothing).
-     * 上端に凍結する先頭行数 (行凍結設計 — 既定 0)。帯はグリッド所有で埋め込み VirtualScroll
+     * 上端に凍結する先頭行数 (既定 0)。帯はグリッド所有で埋め込み VirtualScroll
      * の外: スクロール行は**シフト済みインデックス空間** (itemCount = rowCount − R、getItem =
      * i + R) に住み、vy はスクロール帯の論理位置・縦バーは帯を自然に写像する。0 以上の整数
      * かつ MAX_FROZEN_LEADING_ROWS 以下 — 違反は RangeError (fail-fast)。現在の rowCount を
@@ -343,14 +355,14 @@ export type VirtualGridProps<T> = {
      */
     frozenLeadingRows?: number
     /**
-     * Number of trailing columns frozen at the right edge (v3.5.0 trailing-freeze plan §3;
-     * default 0). Integer in [0, MAX_FROZEN_TRAILING_COLS] — RangeError otherwise (fail-fast).
+     * Number of trailing columns frozen at the right edge (default 0). Integer in
+     * [0, MAX_FROZEN_TRAILING_COLS] — RangeError otherwise (fail-fast).
      * Dynamic clamp (documented contract): min(T, colCount − effectiveFrozenCols) — the LEADING
      * band wins the count space. Trailing cells render in a right-anchored clip outside the
      * anchor machinery (band-local lefts); `--aqvs-grid-trailing-width` is written iff T > 0.
      * `scrollToCell` / `initialScrollAnchor` targeting a trailing column are horizontal no-ops
      * (always visible). T = 0 is structurally identical to the pre-trailing DOM.
-     * 右端に凍結する末尾列数 (3.5.0 末尾凍結プラン §3。既定 0)。[0, MAX_FROZEN_TRAILING_COLS]
+     * 右端に凍結する末尾列数 (既定 0)。[0, MAX_FROZEN_TRAILING_COLS]
      * の整数 — 違反は RangeError (fail-fast)。動的クランプ (文書化契約): min(T, colCount −
      * effectiveFrozenCols) — カウント空間は**先頭が勝つ**。末尾セルはアンカー機構の外の
      * 右アンカークリップに帯ローカル left で描画し、`--aqvs-grid-trailing-width` は T > 0 の
@@ -359,19 +371,19 @@ export type VirtualGridProps<T> = {
      */
     frozenTrailingCols?: number
     /**
-     * Number of trailing rows pinned at the bottom (v3.5.0 trailing-freeze plan §3; default 0).
+     * Number of trailing rows pinned at the bottom (default 0).
      * Integer in [0, MAX_FROZEN_TRAILING_ROWS] — RangeError otherwise (fail-fast). Dynamic
      * clamp (documented contract): min(T, rowCount − effectiveFrozenRows) — leading wins. The
      * band is grid-owned BELOW the pane; the embedded scroll rows shrink at the TAIL only
      * (itemCount = rowCount − R − T, getItem = i + R unchanged), so a runtime T change does NOT
-     * remount the embedded VirtualScroll (ADR-23). `scrollToCell` / `initialScrollAnchor`
+     * remount the embedded VirtualScroll. `scrollToCell` / `initialScrollAnchor`
      * targeting a trailing row are vertical no-ops (always visible). T = 0 is structurally
      * identical to the pre-trailing DOM.
-     * 下端に凍結する末尾行数 (3.5.0 末尾凍結プラン §3。既定 0)。[0, MAX_FROZEN_TRAILING_ROWS]
+     * 下端に凍結する末尾行数 (既定 0)。[0, MAX_FROZEN_TRAILING_ROWS]
      * の整数 — 違反は RangeError (fail-fast)。動的クランプ (文書化契約): min(T, rowCount −
      * effectiveFrozenRows) — 先頭が勝つ。帯はペインの**下**のグリッド所有バンドで、埋め込み
      * スクロール行は**末尾**だけが伸縮する (itemCount = rowCount − R − T、getItem = i + R
-     * 不変) — T の実行時変更は埋め込み VirtualScroll を再マウントしない (ADR-23)。
+     * 不変) — T の実行時変更は埋め込み VirtualScroll を再マウントしない。
      * `scrollToCell` / `initialScrollAnchor` の末尾行狙いは縦 no-op (常時可視)。T = 0 は
      * DOM 構造まで従来と恒等。
      */
@@ -391,6 +403,19 @@ export type VirtualGridProps<T> = {
     /** TEST-ONLY seam: overrides MAX_RENDERED_CELLS so the truncation path is gateable without materializing 32k DOM nodes in jsdom. / テスト専用シーム: 打切り経路を jsdom で 32k ノード無しにゲート化するための上限上書き。 */
     __maxRenderedCells?: number
     behaviorOptions?: VirtualGridBehaviorOptions
+    /**
+     * Scrollbar options. The bar-local members — `width`, `enableThumbDrag`, `enableTrackClick`,
+     * `enableArrowButtons` and `enableArrowButtonTabStops` — reach BOTH bars alike (the embedded
+     * vertical bar and the horizontal bar), so no setting ever covers only half of the grid.
+     * `tapScrollCircleOptions` configures the grid's single two-axis circle (the per-bar circles are
+     * suppressed); the row-axis features `renderThumbOverlay` (fed with visible row indices) and
+     * `enableScrollToTopBottomButtons` (the Top / Bottom pills) belong to the embedded VirtualScroll.
+     * スクロールバー設定。バー固有のメンバー (`width` / `enableThumbDrag` / `enableTrackClick` /
+     * `enableArrowButtons` / `enableArrowButtonTabStops`) は内包の縦バーと横バーの両方へ同じく届き、
+     * 設定がグリッドの片側にだけ効くことは無い。`tapScrollCircleOptions` はグリッド唯一の 2 軸サークルの
+     * 設定 (バーごとのサークルは抑止)、行軸の機能である `renderThumbOverlay` (可視行インデックスを
+     * 受け取る) と `enableScrollToTopBottomButtons` (Top / Bottom ピル) は内包 VirtualScroll の所有。
+     */
     scrollBarOptions?: VirtualScrollScrollBarOptions
     liveRegion?: VirtualGridLiveRegionOptions
     /**
@@ -432,17 +457,17 @@ export type VirtualGridHandle = {
      * frozen column is a horizontal no-op that leaves any previously armed column anchor in
      * place (the visual status quo is preserved; manual horizontal input clears anchors as
      * usual); targeting a leading/trailing frozen row is a vertical no-op. Band membership is
-     * judged at CALL time — a T change AFTER arming follows the ADR-23 clamp semantics: a
-     * pending row anchor whose target row lands inside the trailing band after a T increase
-     * clamps to the last scroll row. Overlap registration (ADR-19-1): when the leading +
-     * trailing band extents exceed the viewport, occluded trailing cells cannot be scrolled
-     * into view — the no-op is exact there too.
+     * judged at CALL time — a T change AFTER arming clamps instead of remounting: a pending row
+     * anchor whose target row lands inside the trailing band after a T increase clamps to the
+     * last scroll row. Overlapping bands: when the leading + trailing band extents exceed the
+     * viewport, occluded trailing cells cannot be scrolled into view — the no-op is exact there
+     * too.
      * セル狙いジャンプ。"nearest" は無し。先頭 / 末尾凍結列狙いの横成分は no-op で、既存の
      * 列アンカーはそのまま残る (視覚的現状維持 — 手動横入力が従来どおり解除する)。先頭 /
      * 末尾凍結行狙いの縦成分も no-op。帯所属の判定は**呼出し時** — 張った後の T 変更は
-     * ADR-23 のクランプ意味論 (T 増加で末尾帯入りする行を狙った保留行アンカーは最終
-     * スクロール行へクランプ) に従う。重複登記 (ADR-19-1): 先頭 + 末尾の帯寸がビューポートを
-     * 超えるとき、隠れた末尾セルはどのスクロール位置でも可視化できない — no-op はそこでも正確。
+     * 再マウントせずクランプする (T 増加で末尾帯入りする行を狙った保留行アンカーは最終
+     * スクロール行へクランプ)。帯の重なり: 先頭 + 末尾の帯寸がビューポートを超えるとき、
+     * 隠れた末尾セルはどのスクロール位置でも可視化できない — no-op はそこでも正確。
      */
     scrollToCell(row: number, col: number, options?: { alignY?: "top" | "bottom" | "center"; alignX?: "start" | "end" | "center"; offsetX?: number; offsetY?: number }): void
     /** Synchronous-fresh position read (internal refs — safe mid-event; {-1,-1} pre-attach). / 同期・最新の位置読み (内部 ref — イベント中も安全。未接続 {-1,-1})。 */
@@ -493,16 +518,26 @@ export type VirtualGridHandle = {
 /**
  * Validates a track size returned by a consumer accessor: finite integer in [0, MAX_TRACK_SIZE].
  * Throws RangeError otherwise (fail-fast — a contract violation surfaces to the error boundary,
- * possibly during render since the width tree materializes lazily).
+ * possibly during render since the width tree materializes lazily). The message is complete on
+ * its own: it names the accessor, the index and the value, states the range, and says how to
+ * comply and why the cap exists.
  *
  * 消費側アクセサのトラックサイズ検証: [0, MAX_TRACK_SIZE] の有限整数。違反は RangeError
  * (fail-fast — 幅木は遅延具現化のため render 中の throw もあり得る契約違反として error
- * boundary へ)。
+ * boundary へ)。メッセージは単独で完結: アクセサ・インデックス・値、許容範囲、従い方と上限の理由。
+ *
+ * @param value - Size returned by the accessor (px) / アクセサが返したサイズ (px)
+ * @param axis - Track axis ("row" = getRowHeight, "col" = getColWidth) / トラックの軸
+ * @param index - Track index passed to the accessor / アクセサへ渡したトラックのインデックス
+ * @returns `value` unchanged / 検証済みの `value` (無変更)
+ * @throws {RangeError} When `value` is not an integer in [0, MAX_TRACK_SIZE] / [0, MAX_TRACK_SIZE] の整数でない場合
  */
 const validateTrackSize = (value: number, axis: "row" | "col", index: number): number => {
     if (!(Number.isInteger(value) && value >= 0 && value <= MAX_TRACK_SIZE)) {
+        const accessor = axis === "row" ? "getRowHeight" : "getColWidth"
+        const tracks = axis === "row" ? "rows" : "columns"
         throw new RangeError(
-            `[VirtualGrid] ${axis === "row" ? "getRowHeight" : "getColWidth"}(${index}) returned ${value} — must be an integer in [0, ${MAX_TRACK_SIZE}] (0 = hidden). Oversized tracks would pierce the browser layout-coordinate wall (see the design plan §3.1/§6).`,
+            `[VirtualGrid] ${accessor}(${index}) returned ${value} — must be an integer in [0, ${MAX_TRACK_SIZE}] (0 = hidden). Round fractional sizes to whole pixels and split content larger than ${MAX_TRACK_SIZE} px across several ${tracks}: a larger track could push cell positions past the 2^25 px layout-coordinate limit of browsers.`,
         )
     }
     return value
@@ -829,7 +864,7 @@ const VirtualGridInner = <T,>(
     const frozenWidthRef = useRef(0)
 
     // ---- 末尾凍結列帯 (3.5.0 プラン §6.1-3) — 先頭側と同文の fail-fast。動的クランプは
-    //      min(T, colCount − 先頭実効) で**先頭がカウント空間で勝つ** (ADR-19-1 の文書化契約) ----
+    //      min(T, colCount − 先頭実効) で**先頭がカウント空間で勝つ** (文書化した契約) ----
     if (!(Number.isInteger(frozenTrailingCols) && frozenTrailingCols >= 0 && frozenTrailingCols <= MAX_FROZEN_TRAILING_COLS)) {
         throw new RangeError(`[VirtualGrid] frozenTrailingCols must be an integer in [0, ${MAX_FROZEN_TRAILING_COLS}], received ${frozenTrailingCols}.`)
     }
@@ -1324,7 +1359,7 @@ const VirtualGridInner = <T,>(
         }
     }, [trailingWidth, effectiveTrailingCols])
 
-    // ---- 統合 2 軸タップサークル (v3.6.0 — ADR-27..32) ----
+    // ---- 統合 2 軸タップサークル ----
     // 埋め込み VirtualScroll へ転送するオプションのメモ化フォーク (§3.1): tapScrollCircleOptions
     // だけ enabled: false を強制し、兄弟フィールド (width 等) は必ず生存させる。両バーの
     // サークルはグリッド側だけで抑止し、単体 VirtualScroll / ScrollPane / ScrollBar は触らない
@@ -1636,7 +1671,7 @@ const VirtualGridInner = <T,>(
             // 行直下の独立 subtree で木絶対 left の直接描画 — DOM は**前置** (論理列順 = 読み上げ /
             // フォーカス順)。末尾セルは右アンカー inner の帯ローカル left で**後置** (同じく論理列順)。
             // class はモードマーカー (描画トレイト) のまま、data-aqvs-frozen-row は F_eff > 0 のみ
-            // (ADR-25 — 末尾のみのグリッドが凍結列ゼロで属性を出すフック面の嘘の封じ)。
+            // (末尾のみのグリッドが凍結列ゼロで属性を出すと、フック面が嘘をつくため)。
             // 描画順は自由: クリップが帯への侵入を構造的に遮断するため重なり自体が無い
             return (
                 <div {...rowProps} data-aqvs-frozen-row={effectiveFrozenCols > 0 ? "" : undefined} className={twMerge("aqvs-grid-row aqvs-grid-row-frozen-host", rowProps?.className)} style={rowProps?.style}>
@@ -1970,13 +2005,19 @@ const VirtualGridInner = <T,>(
                         pendingColAnchorRef.current = null
                         return applyHxRef.current(typeof request === "function" ? request(previous ?? hxRef.current) : request)
                     }}
+                    // バー固有の設定は縦バー (内包 VirtualScroll へ scrollBarOptions を全量透過) と同じ値を
+                    // 横バーへも渡す — 片方のバーにだけ効く設定面を作らない
+                    enableThumbDrag={scrollBarOptions?.enableThumbDrag}
+                    enableTrackClick={scrollBarOptions?.enableTrackClick}
+                    enableArrowButtons={scrollBarOptions?.enableArrowButtons}
+                    enableArrowButtonTabStops={scrollBarOptions?.enableArrowButtonTabStops}
                     scrollBarWidth={scrollBarWidth}
                     locale={locale}
                     labels={labels}
                 />
             </div>
             {tapCircleEnabled && gridScrollable && (
-                // 統合 2 軸タップサークル (v3.6.0 — ADR-30 の 3 アーム則): (C) 可視上限
+                // 統合 2 軸タップサークルの 3 アーム配置則: (C) 可視上限
                 // `100% − (sbw + size)` / (R) 到達性 `100% − sbw + off` / (Q) 遠象限床
                 // `75% − size/2`。全アームが root 寸・sbw・size・オフセットのみに依存 —
                 // 帯幅非依存 (凍結トグル不変)。wrapper は純配置で transition を持たない